@vertesia/appgen-docs 1.5.0-dev.20260725.083715Z

package/lib/docs/package-processes.md

@@ -0,0 +1,220 @@
+# App Package Processes
+
+Use this when a Vertesia app needs to expose process definitions through its service package.
+
+## Registering Processes
+
+App package processes are exposed as `InCodeProcessDefinition` objects registered on the tool server config.
+
+For non-trivial processes, prefer a YAML/YML file as the app-owned source of truth. The service can load/parse that YAML into the native JSON `ProcessDefinitionBody` that Studio validates and installs. If you must keep the definition in TypeScript, keep it small, explicit, and validate it before publish.
+
+## Preferred YAML Source
+
+```yaml
+format_version: 1
+process: creative_ops_pipeline
+description: Run the campaign creative operations workflow.
+initial: brief_intake
+context:
+  schema:
+    type: object
+    properties:
+      campaign_id:
+        type: string
+      asset_ids:
+        type: array
+        items:
+          type: string
+      approved:
+        type: boolean
+      notes:
+        type: string
+    additionalProperties: true
+  initial:
+    campaign_id: ""
+    asset_ids: []
+    approved: false
+    notes: ""
+nodes:
+  brief_intake:
+    type: human_task
+    title: Brief intake
+    task:
+      title: Review campaign brief
+      description: Confirm the campaign is ready for creative production.
+      assignee: group:marketing-ops
+      fields:
+        - name: approved
+          label: Approved
+          type: boolean
+          required: true
+        - name: notes
+          label: Review notes
+          type: text
+    writes:
+      - approved
+      - notes
+    transitions:
+      - to: done
+        trigger: user
+  done:
+    type: final
+    title: Intake complete
+```
+
+Register the parsed definition in `ServerConfig.processes`:
+
+```ts
+import type { InCodeProcessDefinition, ProcessDefinitionBody } from '@vertesia/common';
+import type { ToolServerConfig } from '@vertesia/tools-sdk';
+
+const creativeOpsPipelineDefinition: ProcessDefinitionBody = {
+  format_version: 1,
+  process: 'creative_ops_pipeline',
+  description: 'Run the campaign creative operations workflow.',
+  initial: 'brief_intake',
+  context: {
+    schema: {
+      type: 'object',
+      properties: {
+        campaign_id: { type: 'string' },
+        asset_ids: { type: 'array', items: { type: 'string' } },
+        approved: { type: 'boolean' },
+        notes: { type: 'string' },
+      },
+      additionalProperties: true,
+    },
+    initial: {
+      campaign_id: '',
+      asset_ids: [],
+      approved: false,
+      notes: '',
+    },
+  },
+  nodes: {
+    brief_intake: {
+      type: 'human_task',
+      title: 'Brief intake',
+      task: {
+        title: 'Review campaign brief',
+        description: 'Confirm the campaign is ready for creative production.',
+        assignee: 'group:marketing-ops',
+        fields: [
+          { name: 'approved', label: 'Approved', type: 'boolean', required: true },
+          { name: 'notes', label: 'Review notes', type: 'text' },
+        ],
+      },
+      writes: ['approved', 'notes'],
+      transitions: [{ to: 'done', trigger: 'user' }],
+    },
+    done: {
+      type: 'final',
+      title: 'Intake complete',
+    },
+  },
+};
+
+export const processes = [
+  {
+    id: 'creative-ops-pipeline',
+    name: 'creative_ops_pipeline',
+    title: 'Creative Ops Pipeline',
+    description: 'Campaign creative operations workflow.',
+    tags: ['creative-ops'],
+    definition: creativeOpsPipelineDefinition,
+  },
+] satisfies InCodeProcessDefinition[];
+
+export const ServerConfig = {
+  prefix: '/api',
+  processes,
+  // tools, interactions, types, dashboards, templates...
+} satisfies ToolServerConfig;
+```
+
+The app package endpoint serializes `ServerConfig.processes`:
+
+- `GET /api/package?scope=processes` returns `{ processes: [...] }`.
+- `GET /api/processes` lists registered processes.
+- `GET /api/processes/:name` retrieves by `id`, `name`, or `definition.process`.
+
+The standard `pnpm run service:build:server` package writer validates every packaged process before it writes `dist/app-package.json`. Always also run `validate_process_definition` on the parsed JSON definition while authoring so failures are found before publish. Treat validation failures as blocker app-code issues. The tool input is the native JSON definition, not the raw YAML string:
+
+```json
+{
+  "definition": {
+    "format_version": 1,
+    "process": "creative_ops_pipeline",
+    "initial": "brief_intake",
+    "context": {
+      "schema": {
+        "type": "object",
+        "properties": {
+          "campaign_id": { "type": "string" },
+          "approved": { "type": "boolean" },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": true
+      },
+      "initial": {
+        "campaign_id": "",
+        "approved": false,
+        "notes": ""
+      }
+    },
+    "nodes": {
+      "brief_intake": {
+        "type": "human_task",
+        "task": {
+          "title": "Review campaign brief",
+          "fields": [
+            { "name": "approved", "type": "boolean", "required": true },
+            { "name": "notes", "type": "text" }
+          ]
+        },
+        "writes": ["approved", "notes"],
+        "transitions": [{ "to": "done", "trigger": "user" }]
+      },
+      "done": { "type": "final" }
+    }
+  }
+}
+```
+
+## Shape
+
+`InCodeProcessDefinition`:
+
+```ts
+interface InCodeProcessDefinition {
+  id: string;
+  name: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  definition: ProcessDefinitionBody;
+}
+```
+
+`ProcessDefinitionBody` requires:
+
+- `format_version: 1`
+- `process`: stable process name
+- `initial`: first node id
+- `context: { schema, initial }`
+- `nodes`: record of node ids to process nodes
+
+Common node types are `tool`, `interaction`, `agent`, `script`, `human_task`, `foreach`, `branch`, `condition`, `process`, and `final`.
+
+Transition rules:
+
+- Use `transitions: [{ to: "node_id" }]`; do not use `target`.
+- `branch` and `condition` nodes use `branches: [{ to: "node_id" }]`.
+- A `human_task` node must include `task.title` and `task.fields`; fields support `string`, `number`, `boolean`, `select`, and `text`.
+- A `script` node references an embedded bundle in top-level `resources.scripts`. Scripts read `VERTESIA_PROCESS_INPUT`, write JSON to `VERTESIA_PROCESS_RESULT`, and may place artifacts under `VERTESIA_PROCESS_OUT_DIR`. JavaScript and TypeScript sandboxes include `@vertesia/client`; import it without adding it to the resource's packages.
+
+## App Manifest
+
+When publishing a service app that exposes processes, ensure the app manifest/capabilities include `processes` and publish with `target: "service"`.
+
+Studio normalizes app process ids to `app:<app-name>:<id>` when returning installed app processes.

package/lib/docs/package-types.md

@@ -0,0 +1,80 @@
+# App-Owned Types
+
+Use app-owned in-code type definitions for schema owned by the generated app. Do not create tenant-local stored content types for product-owned schema unless the user explicitly asks for project-local configuration.
+
+## Type refs
+
+Use stable app refs in runtime data and UI code:
+
+```ts
+const APP_NAME = 'my-business-app'; // MUST equal package.json name === VITE_APP_NAME === manifest name
+const CASE_TYPE = `app:${APP_NAME}:case`;
+const TASK_TYPE = `app:${APP_NAME}:task`;
+```
+
+> **App-owned types are in-code strings, not ObjectIds.** A Store object's `type` is EITHER a stored-type ObjectId OR an in-code-type string `app:<app-name>:<local>`. Portable apps MUST pass the in-code string directly to `objects.create`/`objects.search` — the platform resolves it from the app package (including during preview, for the app owner, before install). NEVER resolve an app-owned type to a project-local ObjectId (e.g. a `types.list({ name })`→id lookup or a `useTypeIds` hook): that bakes in one project's id and breaks the app the moment it is installed anywhere else. Derive every `app:` ref from the single `APP_NAME` constant; never paste the literal app name into a ref.
+
+> **For TYPES, `<local>` is the declared type `name` — bare, no collection segment.** `app:<name>:case` is correct; `app:<name>:cases:case` is only a legacy alias. The `ContentTypesCollection` is code organization, not identity, so type names MUST be unique across collections (the package build fails on duplicates). This differs from interactions/activities, whose ids DO include the collection (`app:<name>:<collection>:<interaction>`).
+
+When creating or searching Store objects, pass the app type code string:
+
+```ts
+await client.objects.create({
+  type: CASE_TYPE,
+  properties: {
+    title: 'Supplier review',
+    status: 'open',
+    seed_marker: `appgen:${APP_NAME}`,
+  },
+});
+
+const { results } = await client.objects.search({
+  query: {
+    type: CASE_TYPE,
+    match: { 'properties.seed_marker': `appgen:${APP_NAME}` },
+  },
+  limit: 50,
+});
+```
+
+## Package source
+
+Define package types under `src/modules/app/resources/types/<domain>/index.ts` and export their collection from `src/modules/app/resources/types/index.ts`. Generated module wiring includes that array in `ServerConfig.types`.
+
+```ts
+import type { InCodeTypeSpec } from '@vertesia/common';
+import { ContentTypesCollection } from '@vertesia/tools-sdk';
+
+const caseType = {
+  name: 'case',
+  title: 'Compliance Case',
+  description: 'App-owned case record.',
+  tags: ['compliance'],
+  object_schema: {
+    type: 'object',
+    properties: {
+      title: { type: 'string' },
+      status: { type: 'string' },
+      owner: { type: 'string' },
+      seed_marker: { type: 'string' },
+    },
+    required: ['title', 'status'],
+  },
+} satisfies InCodeTypeSpec;
+
+export const ComplianceTypes = new ContentTypesCollection({
+  name: 'compliance',
+  title: 'Compliance Types',
+  types: [caseType],
+});
+```
+
+`src/modules/app/resources/types/index.ts`:
+
+```ts
+import { ComplianceTypes } from './compliance/index.js';
+
+export const types = [ComplianceTypes];
+```
+
+Keep generated apps portable: schema and behavior live in the app package; seeded records live in the Store and use installed app type refs.

package/lib/docs/store-objects.md

@@ -0,0 +1,94 @@
+# Store Object Search And Seeding
+
+Use the Vertesia client from `useUserSession()` in browser code and the injected token/client in app workspace scripts. Prefer `client.objects.search` over list/find guessing.
+
+App-owned types are referenced by their **in-code string** `app:<app-name>:<local>`, never a resolved ObjectId — pass the string straight to `search`/`create` and derive it from a single `APP_NAME` constant (= package.json name = VITE_APP_NAME = manifest name) so the app stays portable. See `package-types.md` for the rule.
+
+## Search
+
+```ts
+const APP_NAME = 'my-app'; // = package.json name = VITE_APP_NAME = manifest name
+const CASE_TYPE = `app:${APP_NAME}:case`;
+
+const { results, count } = await client.objects.search({
+  query: {
+    type: CASE_TYPE,
+    match: { 'properties.seed_marker': `appgen:${APP_NAME}` },
+  },
+  limit: 100,
+  offset: 0,
+});
+```
+
+For text search:
+
+```ts
+const { results } = await client.objects.search({
+  query: {
+    type: CASE_TYPE,
+    full_text: searchText,
+    match: { 'properties.status': 'open' },
+  },
+  limit: 25,
+});
+```
+
+## Idempotent seed
+
+Always mark generated records so they can be counted, updated, and cleaned up safely.
+
+```ts
+import type { VertesiaClient } from '@vertesia/client';
+
+const APP_NAME = 'my-app';
+const SEED_MARKER = `appgen:${APP_NAME}`;
+const CASE_TYPE = `app:${APP_NAME}:case`;
+
+async function seedCase(client: VertesiaClient, record: { external_id: string; title: string }) {
+  const existing = await client.objects.search({
+    query: {
+      type: CASE_TYPE,
+      match: {
+        'properties.seed_marker': SEED_MARKER,
+        'properties.external_id': record.external_id,
+      },
+    },
+    limit: 1,
+  });
+
+  if (existing.results?.[0]?.id) {
+    return client.objects.update(existing.results[0].id, {
+      properties: { ...record, seed_marker: SEED_MARKER },
+    });
+  }
+
+  return client.objects.create({
+    type: CASE_TYPE,
+    properties: { ...record, seed_marker: SEED_MARKER },
+  });
+}
+```
+
+## Markdown source content
+
+For document, review, and intake apps, attach realistic source content to representative objects instead of only creating properties.
+
+```ts
+await client.objects.create({
+  type: `app:${APP_NAME}:evidence`,
+  properties: {
+    title: 'Screening evidence',
+    seed_marker: SEED_MARKER,
+  },
+  text: [
+    '# Screening Evidence',
+    '',
+    'Denied party screening completed for shipment GTC-1001.',
+    '',
+    '- Result: potential hit',
+    '- Reviewer: trade compliance',
+  ].join('\n'),
+});
+```
+
+If the exact source attachment API differs in the installed SDK, write the intended create code first, then run `app_workspace_typecheck` and fix from compiler diagnostics. Do not spend more than five docs lookups rediscovering the object shape.