Add Document Generator SDK app + step-by-step tutorial (#22522)

## What & why This adds a **guided tutorial** that teaches the Twenty SDK by building one real, useful app end to end — plus the finished app itself, ready for the marketplace. The app, **Document Generator**, turns reusable templates into personalized documents using CRM data: write a template once with `{{placeholders}}`, then generate a filled-in document for any Person or Company from the command menu, an AI agent, or a workflow. ## Two parts **1. The app — `packages/twenty-apps/public/document-generator`** Each capability maps to one tutorial chapter: - **Data:** `documentTemplate` + `document` objects, fields, and a bidirectional relation - **Logic:** a single `generate-document` handler exposed as an **AI tool**, a **workflow action**, and an **HTTP POST route**; plus a public **HTML view route** - **UI:** two views + sidebar navigation, a **command-menu item** (on Person selection) that opens a **React front component** - **AI:** an agent + skill; a default application role; marketplace metadata + logo - **Tests:** unit tests for the template renderer + an install integration test **2. The tutorial — `packages/twenty-docs/.../apps/tutorials/document-generator/`** A six-chapter series under **Developers › Apps › Tutorial** (Overview → Data model → Generating documents → HTTP routes → Building the UI → AI agent → Publishing). Minimal prose, paste-ready code, inline links to the matching reference pages, and real screenshots. Registers a new "Tutorial" nav group and regenerates `docs.json` + the navigation template. ## Verification Validated against a running Twenty instance (`twenty-app-dev` on `:2020`): - `twenty dev --once` installs cleanly (28 metadata objects created) - Generated a real document from a Person — placeholders resolved (name, job title, `company.name`, email), zero missing tokens - Command menu → front component → generate flow works in the UI - Public HTML view route renders the document - App gates green: `yarn lint` (0/0), `yarn typecheck`, `yarn test:unit` (7/7) All screenshots in the tutorial are captured from this run. ## Notes - Left out per-app CI workflows (`.github/workflows`) to keep scope tight — happy to add them if wanted. https://claude.ai/code/session_012FoC76zPbPmpgtN7MXMPwy --- _Generated by [Claude Code](https://claude.ai/code/session_012FoC76zPbPmpgtN7MXMPwy)_  <a href="https://cubic.dev/pr/twentyhq/twenty/pull/22522?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a>  --------- Co-authored-by: github-actions <github-actions@twenty.com>
2026-07-07 11:13:34 +02:00
parent 2a495c3477
commit 07a921f8ca
73 changed files with 7344 additions and 0 deletions
@@ -0,0 +1,27 @@
+import { MetadataApiClient } from 'twenty-client-sdk/metadata';
+import { describe, expect, it } from 'vitest';
+
+import { APPLICATION_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';
+
+// The app is synced once in src/__tests__/global-setup.ts and uninstalled on
+// teardown, so this test just asserts the install succeeded.
+describe('Document Generator installation', () => {
+  it('should install the application onto the workspace', async () => {
+    const metadataClient = new MetadataApiClient();
+
+    const result = await metadataClient.query({
+      findManyApplications: {
+        id: true,
+        name: true,
+        universalIdentifier: true,
+      },
+    });
+
+    const installedApp = result.findManyApplications.find(
+      (application: { universalIdentifier: string }) =>
+        application.universalIdentifier === APPLICATION_UNIVERSAL_IDENTIFIER,
+    );
+
+    expect(installedApp).toBeDefined();
+  });
+});
@@ -0,0 +1,87 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import { appDevOnce, appUninstall } from 'twenty-sdk/cli';
+
+const APP_PATH = process.cwd();
+const CONFIG_DIR = path.join(os.homedir(), '.twenty');
+
+function validateEnv(): { apiUrl: string; apiKey: string } {
+  const apiUrl = process.env.TWENTY_API_URL;
+  const apiKey = process.env.TWENTY_API_KEY;
+
+  if (!apiUrl || !apiKey) {
+    throw new Error(
+      'TWENTY_API_URL and TWENTY_API_KEY must be set.\n' +
+        'Start a local server: yarn twenty docker:start\n' +
+        'Or set them in vitest env config.',
+    );
+  }
+
+  return { apiUrl, apiKey };
+}
+
+async function checkServer(apiUrl: string) {
+  let response: Response;
+
+  try {
+    response = await fetch(`${apiUrl}/healthz`);
+  } catch {
+    throw new Error(
+      `Twenty server is not reachable at ${apiUrl}. ` +
+        'Make sure the server is running before executing integration tests.',
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(`Server at ${apiUrl} returned ${response.status}`);
+  }
+}
+
+function writeConfig(apiUrl: string, apiKey: string) {
+  const payload = JSON.stringify(
+    {
+      remotes: {
+        local: { apiUrl, apiKey, accessToken: apiKey },
+      },
+      defaultRemote: 'local',
+    },
+    null,
+    2,
+  );
+
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CONFIG_DIR, 'config.test.json'), payload);
+}
+
+export async function setup() {
+  const { apiUrl, apiKey } = validateEnv();
+
+  await checkServer(apiUrl);
+
+  writeConfig(apiUrl, apiKey);
+
+  await appUninstall({ appPath: APP_PATH }).catch(() => {});
+
+  const result = await appDevOnce({
+    appPath: APP_PATH,
+    onProgress: (message: string) => console.log(`[dev] ${message}`),
+  });
+
+  if (!result.success) {
+    throw new Error(
+      `Dev sync failed: ${result.error?.message ?? 'Unknown error'}`,
+    );
+  }
+}
+
+export async function teardown() {
+  const uninstallResult = await appUninstall({ appPath: APP_PATH });
+
+  if (!uninstallResult.success) {
+    console.warn(
+      `App uninstall failed: ${uninstallResult.error?.message ?? 'Unknown error'}`,
+    );
+  }
+}