@elevasis/sdk 1.48.0 → 1.50.0

package/reference/sdk/templates/pdf-generator.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Template: PDF Generator"
-description: "PDF generation from structured data with platform storage upload -- render a PDF from a template and upload to platform storage"
+description: "PDF generation from structured data with platform storage upload -- render a PDF from typed content blocks and upload to platform storage"
 loadWhen: "Applying the pdf-generator workflow template"
 ---
 
@@ -16,7 +16,9 @@ loadWhen: "Applying the pdf-generator workflow template"
 
 ## What This Workflow Does
 
-Receives structured data, renders a PDF using an HTML template, uploads the result to platform storage, and returns a signed URL for download. Suitable for invoices, reports, certificates, contracts, and any document that needs to be generated on demand and delivered as a downloadable file.
+Receives structured content (a title, body text, and an optional data table), renders it to a PDF using the platform's declarative document builder, uploads the result to platform storage, and returns a signed URL for download. Suitable for invoices, reports, certificates, contracts, and any document that needs to be generated on demand and delivered as a downloadable file.
+
+The platform's `pdf` tool does not accept raw HTML -- it renders a JSON document tree of typed content blocks (`text`, `metric`, `list`, `table`, `card`, `columns`). This template covers the common `text` + `table` case; adapt the `sections` array for other block types.
 
 ---
 
@@ -26,8 +28,10 @@ Receives structured data, renders a PDF using an HTML template, uploads the resu
 
 ```typescript
 z.object({
-  templateHtml: z.string(),          // HTML template with {variable} placeholders
-  data: z.record(z.string(), z.unknown()),        // Data to inject into the template
+  title: z.string(),                  // Document title, rendered as the page heading
+  bodyText: z.string(),               // Main body paragraph
+  tableHeaders: z.array(z.string()).optional(), // Optional data table column headers
+  tableRows: z.array(z.array(z.string())).optional(), // Optional data table rows
   filename: z.string(),               // Output filename (without .pdf extension)
   expiresInSeconds: z.number().optional(), // Signed URL expiry (default: 3600)
 })
@@ -56,8 +60,10 @@ import { platform } from '@elevasis/sdk/worker'
 import { z } from 'zod'
 
 const inputSchema = z.object({
-  templateHtml: z.string(),
-  data: z.record(z.string(), z.unknown()),
+  title: z.string(),
+  bodyText: z.string(),
+  tableHeaders: z.array(z.string()).optional(),
+  tableRows: z.array(z.array(z.string())).optional(),
   filename: z.string(),
   expiresInSeconds: z.number().optional(),
 })
@@ -69,16 +75,12 @@ const outputSchema = z.object({
 
 type Input = z.infer<typeof inputSchema>
 
-function renderTemplate(html: string, data: Record<string, unknown>): string {
-  return html.replace(/\{(\w+)\}/g, (_, key) => String(data[key] ?? ''))
-}
-
 export const pdfGenerator: WorkflowDefinition = {
   config: {
-    resourceId: 'pdf-generator',
+    resourceId: 'pdf-generator-workflow',
     name: 'PDF Generator',
     type: 'workflow',
-    description: 'Generates a PDF from HTML template and uploads to storage',
+    description: 'Generates a PDF from structured content blocks and uploads to storage',
     version: '1.0.0',
     status: 'dev',
   },
@@ -87,17 +89,30 @@ export const pdfGenerator: WorkflowDefinition = {
     render: {
       id: 'render',
       name: 'Render PDF',
-      description: 'Render HTML template to PDF buffer',
+      description: 'Render a structured document to a PDF buffer',
       inputSchema,
       outputSchema: z.object({ buffer: z.string(), filename: z.string(), expiresInSeconds: z.number() }),
       handler: async (input) => {
-        const { templateHtml, data, filename, expiresInSeconds } = input as Input
-        const html = renderTemplate(templateHtml, data)
+        const { title, bodyText, tableHeaders, tableRows, filename, expiresInSeconds } = input as Input
+
+        const document = {
+          pages: [
+            {
+              sections: [
+                { type: 'text' as const, content: title, variant: 'title' as const },
+                { type: 'text' as const, content: bodyText, variant: 'body' as const },
+                ...(tableHeaders && tableRows
+                  ? [{ type: 'table' as const, headers: tableHeaders, rows: tableRows }]
+                  : []),
+              ],
+            },
+          ],
+        }
 
         const result = await platform.call({
           tool: 'pdf',
           method: 'renderToBuffer',
-          params: { html },
+          params: { document },
         }) as { buffer: string } // base64-encoded buffer
 
         return { buffer: result.buffer, filename, expiresInSeconds: expiresInSeconds ?? 3600 }
@@ -112,13 +127,15 @@ export const pdfGenerator: WorkflowDefinition = {
       outputSchema,
       handler: async (input, context) => {
         const { buffer, filename, expiresInSeconds } = input as { buffer: string; filename: string; expiresInSeconds: number }
-        const key = `documents/${filename}-${Date.now()}.pdf`
+        const bucket = 'documents'
+        const path = `${filename}-${Date.now()}.pdf`
 
         await platform.call({
           tool: 'storage',
           method: 'upload',
           params: {
-            key,
+            bucket,
+            path,
             content: buffer,
             contentType: 'application/pdf',
           },
@@ -127,11 +144,11 @@ export const pdfGenerator: WorkflowDefinition = {
         const urlResult = await platform.call({
           tool: 'storage',
           method: 'createSignedUrl',
-          params: { key, expiresIn: expiresInSeconds },
+          params: { bucket, path, expiresIn: expiresInSeconds },
         }) as { signedUrl: string; expiresAt: string }
 
-        context.logger.info(`PDF generated and uploaded: ${filename} at ${key}`)
-        return { downloadUrl: urlResult.signedUrl, storageKey: key, expiresAt: urlResult.expiresAt }
+        context.logger.info(`PDF generated and uploaded: ${filename} at ${bucket}/${path}`)
+        return { downloadUrl: urlResult.signedUrl, storageKey: `${bucket}/${path}`, expiresAt: urlResult.expiresAt }
       },
       next: null,
     },
@@ -144,11 +161,12 @@ export const pdfGenerator: WorkflowDefinition = {
 
 ## Adaptation Notes
 
-- **Template format:** The simple `{variable}` placeholder system handles most cases. For complex documents, suggest the user write a more complete HTML template with inline CSS.
+- **Content blocks:** The `pdf` tool renders a JSON document tree, not HTML. This template covers `text` and `table` blocks; add `metric`, `list`, `card`, or `columns` blocks to `sections` for richer layouts.
+- **Storage bucket:** The template hardcodes `bucket = 'documents'`. Ask the user what bucket name their organization's platform storage is configured to use.
 - **Filename:** The template appends a timestamp to avoid collisions. Adapt naming to the user's convention (e.g., `invoice-{invoiceId}`).
 - **Expiry:** Default is 1 hour. For document delivery workflows, increase to 24-72 hours.
-- **Data structure:** Ask the user what fields their document needs before defining the `data` schema. For typed use cases (invoices, reports), define a stricter input schema.
-- **Skill adaptation:** For beginners, show a complete example HTML template and explain what "template variables" are.
+- **Data structure:** Ask the user what fields their document needs before defining the input schema and mapping it into `sections`. For typed use cases (invoices, reports), add more input fields and a matching table row or card per field group.
+- **Skill adaptation:** For beginners, walk through the difference between a JSON document tree and an HTML template before generating code.
 
 ---
 

package/reference/sdk/templates/recurring-job.mdx

@@ -18,8 +18,8 @@ loadWhen: "Applying the recurring-job workflow template"
 
 Two-part pattern for recurring jobs:
 
-1. **Setup workflow** (`recurring-job-setup`): Creates a schedule entry that triggers the main job workflow on a recurring basis. Run once to activate.
-2. **Main job workflow** (`recurring-job`): The actual work executed on each scheduled trigger.
+1. **Setup workflow** (`recurring-job-setup-workflow`): Creates a schedule entry that triggers the main job workflow on a recurring basis. Run once to activate.
+2. **Main job workflow** (`recurring-job-workflow`): The actual work executed on each scheduled trigger.
 
 The job workflow and setup workflow share a schedule key for idempotent schedule management.
 
@@ -43,8 +43,7 @@ z.object({
 
 ```typescript
 z.object({
-  scheduledAt: z.string(),              // ISO timestamp of the scheduled trigger
-  jobInput: z.record(z.string(), z.unknown()).optional(), // Passed through from schedule creation
+  jobInput: z.record(z.string(), z.unknown()).optional(), // Passed through as scheduleConfig.payload at setup time
 })
 ```
 
@@ -72,7 +71,7 @@ import { z } from 'zod'
 // Setup workflow -- run once to create the schedule
 export const recurringJobSetup: WorkflowDefinition = {
   config: {
-    resourceId: 'recurring-job-setup',
+    resourceId: 'recurring-job-setup-workflow',
     name: 'Recurring Job Setup',
     type: 'workflow',
     description: 'Creates or updates the schedule for the recurring job',
@@ -104,10 +103,15 @@ export const recurringJobSetup: WorkflowDefinition = {
           tool: 'scheduler',
           method: 'createSchedule',
           params: {
-            resourceId: 'recurring-job',
-            cronExpression,
-            timezone: timezone ?? 'UTC',
-            input: { scheduledAt: new Date().toISOString(), jobInput: jobInput ?? {} },
+            organizationId: context.organizationId, // ignored -- the platform re-scopes this from execution context
+            name: 'Recurring Job Schedule',
+            target: { resourceType: 'workflow', resourceId: 'recurring-job-workflow' },
+            scheduleConfig: {
+              type: 'recurring',
+              cron: cronExpression,
+              timezone: timezone ?? 'UTC',
+              payload: { jobInput: jobInput ?? {} },
+            },
             idempotencyKey: 'recurring-job-schedule',
           },
         }) as { id: string }
@@ -124,7 +128,7 @@ export const recurringJobSetup: WorkflowDefinition = {
 // Main job workflow -- triggered by the scheduler on each run
 export const recurringJob: WorkflowDefinition = {
   config: {
-    resourceId: 'recurring-job',
+    resourceId: 'recurring-job-workflow',
     name: 'Recurring Job',
     type: 'workflow',
     description: 'Executes on each scheduled trigger',
@@ -133,7 +137,6 @@ export const recurringJob: WorkflowDefinition = {
   },
   contract: {
     inputSchema: z.object({
-      scheduledAt: z.string(),
       jobInput: z.record(z.string(), z.unknown()).optional(),
     }),
     outputSchema: z.object({
@@ -147,12 +150,12 @@ export const recurringJob: WorkflowDefinition = {
       id: 'run',
       name: 'Run Job',
       description: 'Execute the recurring job logic',
-      inputSchema: z.object({ scheduledAt: z.string(), jobInput: z.record(z.string(), z.unknown()).optional() }),
+      inputSchema: z.object({ jobInput: z.record(z.string(), z.unknown()).optional() }),
       outputSchema: z.object({ completed: z.boolean(), processedAt: z.string(), summary: z.string() }),
       handler: async (input, context) => {
-        const { scheduledAt, jobInput } = input as { scheduledAt: string; jobInput?: Record<string, unknown> }
+        const { jobInput } = input as { jobInput?: Record<string, unknown> }
 
-        context.logger.info(`Recurring job started at ${scheduledAt}`)
+        context.logger.info(`Recurring job started at ${new Date().toISOString()}`)
 
         // === REPLACE THIS SECTION WITH THE ACTUAL JOB LOGIC ===
         // Example: fetch data, process it, send a report
@@ -186,9 +189,11 @@ export const recurringJob: WorkflowDefinition = {
 ## Adaptation Notes
 
 - **Job logic:** Replace the placeholder comment in the `run` handler with the actual job logic. Ask the user what the job should do before generating the full workflow.
-- **Both workflows needed:** Remind the user to add both `recurringJob` and `recurringJobSetup` to their `src/index.ts` registry. Run `setup` once to activate; only `recurring-job` runs automatically thereafter.
+- **Both workflows needed:** Remind the user to add both `recurringJob` and `recurringJobSetup` to their `src/index.ts` registry. Run `setup` once to activate; only `recurring-job-workflow` runs automatically thereafter.
 - **Idempotency key:** The `recurring-job-schedule` key ensures re-running setup does not create duplicate schedules.
 - **Timezone:** Always ask the user their preferred timezone. Defaults to UTC which may cause unexpected run times.
+- **`organizationId` in `createSchedule` params:** The platform always re-scopes this from the execution context server-side, so the value passed here is ignored -- it exists only because the field is required by the scheduler's type.
+- **Execution input on each run:** The job workflow receives `scheduleConfig.payload` as its input, with a `_scheduleMetadata` object (`scheduleId`, `scheduleName`, `scheduleStep`) merged in automatically. Extra fields are not part of the validated `inputSchema` and are silently dropped by Zod's default parsing.
 
 ---
 

package/reference/sdk/templates/text-classifier.mdx

@@ -70,7 +70,7 @@ type Input = z.infer<typeof inputSchema>
 
 export const textClassifier: WorkflowDefinition = {
   config: {
-    resourceId: 'text-classifier',
+    resourceId: 'text-classifier-workflow',
     name: 'Text Classifier',
     type: 'workflow',
     description: 'Classifies text into predefined categories using an LLM',

package/reference/sdk/templates/web-scraper.mdx

@@ -72,7 +72,7 @@ type Input = z.infer<typeof inputSchema>
 
 export const webScraper: WorkflowDefinition = {
   config: {
-    resourceId: 'web-scraper',
+    resourceId: 'web-scraper-workflow',
     name: 'Web Scraper',
     type: 'workflow',
     description: 'Scrapes structured data via Apify and stores in Supabase',
@@ -86,16 +86,20 @@ export const webScraper: WorkflowDefinition = {
       name: 'Run Apify Actor',
       description: 'Execute the Apify actor and collect results',
       inputSchema,
-      outputSchema: z.object({ items: z.array(z.unknown()), runId: z.string() }),
+      outputSchema: z.object({ items: z.array(z.unknown()), runId: z.string(), tableName: z.string() }),
       handler: async (input) => {
-        const { actorId, startUrls, maxItems } = input as Input
+        const { actorId, startUrls, tableName, maxItems } = input as Input
         const result = await platform.call({
           tool: 'apify',
           method: 'runActor',
           credential: 'apify',
-          params: { actorId, input: { startUrls: startUrls.map(url => ({ url })), maxItems: maxItems ?? 100 } },
+          params: {
+            actorId,
+            input: { startUrls: startUrls.map(url => ({ url })) },
+            maxItems: maxItems ?? 100,
+          },
         }) as { items: unknown[]; runId: string }
-        return { items: result.items, runId: result.runId }
+        return { items: result.items, runId: result.runId, tableName }
       },
       next: { type: StepType.LINEAR, target: 'store' },
     },

package/reference/sdk/troubleshooting.mdx

@@ -38,6 +38,42 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ---
 
+## System Readiness Errors (503)
+
+### API request refused (503): `<system>`/`<interface>` is not ready
+
+**Message:** starts with `API request refused (503)` and continues `This IS the API rejecting the request -- it is not a gateway hiccup, and re-running it will not help.`
+
+**Cause:** The route you called is gated on a System Interface, and your organization's deployed Organization Model has not satisfied it. This is the API deliberately refusing, not a transport fault -- retrying will not help.
+
+**Fix:** Read the `Issues:` block in the message. Those entries are the API's own explanation and name the specific missing thing. The guidance line above them tells you the general shape of the fix:
+
+- **The System has not been adopted** -- declare it in `core/config/organization-model/systems.ts` with an `apiInterface` block, then deploy. Omitting the block entirely is the supported opt-out; an empty `apiInterface.resourceIds` array is not and will throw.
+- **The interface is declared but disabled** -- set its lifecycle back to active and redeploy.
+- **The `readinessContract` is unsatisfied** -- the issues name the missing `requiredObjects` or `requiredCatalogs` refs. Add them and redeploy.
+- **A cross-System handoff is not ready** -- check the counterpart System as well as the one named.
+- **The deployed snapshot is missing or stale** -- run `elevasis-sdk deploy`. The message already carries this instruction.
+- **The stored snapshot could not be read** -- deploy again first. No field of your declaration is known to be wrong.
+
+Then run `elevasis-sdk doctor` to see what else is not ready. Its Systems roster checks every platform-cataloged System, including ones you have not adopted.
+
+### This CLI does not recognize readiness code `{CODE}`
+
+**Cause:** The API returned a readiness family your installed `@elevasis/sdk` predates. Tenants run a published SDK that lags the deployed API, so this is expected after a platform release and not a defect.
+
+**Fix:**
+
+1. Read the `Issues:` block -- it is family-independent and remains the authoritative part of the message
+2. Run `pnpm update @elevasis/sdk` and re-run the command for the full guidance
+
+### 503 with "work may still be running server-side"
+
+**Cause:** This is the gateway message, not the readiness message. It means a proxy or load balancer returned the `503` with no readiness body -- a genuine transport fault.
+
+**Fix:** Retry. Unlike a readiness refusal, this class is transient and the request may have reached the API.
+
+---
+
 ## Validation Errors (elevasis-sdk check)
 
 ### Duplicate resource ID
@@ -64,6 +100,41 @@ This is the static SDK-level error catalog. Check `.claude/memory/errors/` first
 
 ---
 
+## Deploy Errors (elevasis-sdk deploy)
+
+### ORGANIZATION_MODEL_MISSING (400)
+
+**Cause:** The deploy carried no organization model, so the platform had nothing to persist as a snapshot.
+
+**Fix:** Export an `organizationModel` from your deployment spec and deploy again. This is a hard failure by design -- a deploy without a model used to report success, write no snapshot, and then refuse every subsequent API request with a readiness `503`.
+
+### `sdkVersion` is required (400)
+
+**Cause:** The multipart `metadata` part failed schema validation before the deploy pipeline started. `sdkVersion` is the only required field.
+
+**Fix:** Deploy through `elevasis-sdk deploy`, which always sends it. A hand-rolled `POST /api/external/deploy` must include it.
+
+### Deploy succeeded but warnings were printed
+
+Deploy warnings never block the deploy. Each one names something that will fail later if left alone:
+
+- **Workflow graph warnings** -- a dangling `next` target, a missing `entryPoint`, a cycle, or a step unreachable from the entry point. These are warnings at deploy so an existing project carrying a latent invalid graph is not blocked, but the same checks **throw at execution** when the workflow is constructed. Fix them before the workflow next runs.
+- **Missing credential** -- an `IntegrationDefinition.credentialName` you declared has no matching credential in your organization. Create it in the command center; otherwise the first execution fails with a `credentials_missing` tooling error. Only credential names are checked and logged, never values.
+- **Missing `apiInterface` declaration** -- a System with API-backed resources has no `apiInterface` block. Run `elevasis-sdk om:scaffold:fill` for the affected system path.
+- **Unresolvable contract refs** -- contract refs are declared but no `contractRegistry` is exported from your entry.
+
+### Validation reported only one error, but there are more
+
+Governance and System Interface readiness failures now report **every** issue in one deploy, not just the first. If you see a single issue, that is the whole list. Set `ELEVASIS_RESOURCE_VALIDATOR=warn-only` to downgrade governance, contract-ref resolution, readiness, and the agent grammar checks to warnings so a deploy can proceed while you work through them -- it never bypasses the structural schema parse or the OM conformance gate.
+
+### The deploy authenticated but the upload was rejected
+
+**Cause:** Historically the auth step and the upload step resolved the API key two different ways, so pointing `--api-url` at production with `NODE_ENV=development` set authenticated with one key and uploaded with the other.
+
+**Fix:** Update `@elevasis/sdk`. Both steps now derive the key from the URL the request is actually sent to. If you are pinning `NODE_ENV=development` and targeting production, set `ELEVASIS_PLATFORM_KEY` to the production key and use `--prod` or `--api-url`.
+
+---
+
 ## Schema Validation Errors
 
 ### Schema validation failed (input)
@@ -219,4 +290,4 @@ Status values: `Resolved` (fixed this session), `Recurring` (seen 2+ times), `Pr
 
 ---
 
-**Last Updated:** 2026-02-26
+**Last Updated:** 2026-08-20

package/reference/ui/exports.mdx

@@ -44,7 +44,7 @@ description: "Auto-generated catalog of all published @elevasis/ui subpath expor
 | `@elevasis/ui/layout` | Layout | Components | Published layout component entry for downstream applications. |
 | `@elevasis/ui/charts` | Charts | Components | Published chart component entry for downstream applications. |
 | `@elevasis/ui/theme` | Theme | Visual | Published theme entry for downstream applications. |
-| `@elevasis/ui/theme/presets` | Theme Presets | Visual | Re-exports the canonical THEME_PRESETS tuple, ThemePresetName union, and ThemePresetEnum Zod enum from @repo/core. Single source of truth for preset names across UI, schemas, and Zustand state. |
+| `@elevasis/ui/theme/presets` | Theme Presets | Visual | Published THEME_PRESETS tuple, ThemePresetName union, and ThemePresetEnum Zod enum, defined locally and kept manually aligned with the canonical list in packages/core/src/auth/multi-tenancy/theme-presets.ts. |
 | `@elevasis/ui/api` | API | Foundation | Published API client entry for downstream applications. |
 | `@elevasis/ui/utils` | Utils | Foundation | Published utility entry for downstream applications. |
 | `@elevasis/ui/graph` | Graph | Visual | Published graph helper and visualization entry. |

package/reference/ui/index.mdx

@@ -77,6 +77,6 @@ You do not need `@elevasis/ui` if you are only writing backend workflows and age
 
 `@elevasis/ui` uses `@elevasis/core` internally for entity schemas, org-model types, and auth contracts. Installing `@elevasis/ui` will pull in `@elevasis/core` as a dependency. You do not need to install `@elevasis/core` separately unless you need direct access to its subpaths.
 
-## Export Catalog
+## Documentation
 
-See [Export Catalog](exports.mdx) for a generated table of all published subpath exports derived from the reference manifest.
+- [Export Catalog](exports.mdx) - Generated table of all published subpath exports derived from the reference manifest