@elevasis/sdk 0.5.13 → 0.5.15

package/reference/resources/patterns.mdx

@@ -1,354 +1,355 @@
----
-title: Common Patterns
-description: Common resource patterns for Elevasis SDK developers -- sequential steps, conditional branching, platform tools, error handling, and resource status management
-loadWhen: "Building or modifying a workflow"
----
-
-This page collects the patterns you will reach for most often when writing resources. Each pattern is self-contained and can be adapted directly into your project.
-
----
-
-## Sequential Workflow Steps
-
-The simplest pattern: a chain of steps where each step feeds its output into the next.
-
-```typescript
-import { z } from 'zod';
-import { StepType } from '@elevasis/sdk';
-import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
-
-const inputSchema = z.object({ orderId: z.string() });
-const outputSchema = z.object({ shipped: z.boolean(), trackingNumber: z.string() });
-
-type Input = z.infer<typeof inputSchema>;
-type Output = z.infer<typeof outputSchema>;
-
-const validateStep: WorkflowStep = {
-  type: StepType.LINEAR,
-  handler: async (input: Input) => {
-    const order = await getOrder(input.orderId);
-    if (!order) throw new Error(`Order ${input.orderId} not found`);
-    return { order };
-  },
-  next: { target: 'ship' },
-};
-
-const shipStep: WorkflowStep = {
-  type: StepType.LINEAR,
-  handler: async (input) => {
-    const tracking = await createShipment(input.order);
-    return { shipped: true, trackingNumber: tracking.number };
-  },
-  next: null, // terminal -- no further steps
-};
-
-const fulfillOrder: WorkflowDefinition = {
-  config: { name: 'fulfill-order', description: 'Validates and ships an order', status: 'dev' },
-  contract: { input: inputSchema, output: outputSchema },
-  steps: { validate: validateStep, ship: shipStep },
-  entryPoint: 'validate',
-};
-```
-
-**Key points:**
-
-- `next: { target: 'stepName' }` routes to the next step
-- `next: null` marks the terminal step
-- Each step receives the full return value of the previous step as its `input`
-- The terminal step's return value must satisfy `contract.output`
-
----
-
-## Conditional Branching
-
-Use `StepType.CONDITIONAL` when the next step depends on the output of the current step.
-
-```typescript
-import { StepType } from '@elevasis/sdk';
-import type { WorkflowStep } from '@elevasis/sdk';
-
-const scoreStep: WorkflowStep = {
-  type: StepType.CONDITIONAL,
-  handler: async (input) => {
-    const score = await calculateRiskScore(input.applicationId);
-    return { score, applicationId: input.applicationId };
-  },
-  next: {
-    routes: [
-      {
-        condition: (output) => output.score \>= 80,
-        target: 'autoApprove',
-      },
-      {
-        condition: (output) => output.score \>= 40,
-        target: 'manualReview',
-      },
-    ],
-    defaultTarget: 'autoReject', // used when no condition matches
-  },
-};
-```
-
-**Key points:**
-
-- Routes are evaluated in order -- the first matching condition wins
-- `defaultTarget` is required and acts as the `else` branch
-- The condition function receives the full handler output
-- All route targets and `defaultTarget` must be keys in your `steps` record
-
----
-
-## Using Platform Tools in Steps
-
-Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and a credential reference.
-
-```typescript
-import { platform, PlatformToolError } from '@elevasis/sdk/worker';
-import type { WorkflowStep } from '@elevasis/sdk';
-import { StepType } from '@elevasis/sdk';
-
-const sendEmailStep: WorkflowStep = {
-  type: StepType.LINEAR,
-  handler: async (input, context) => {
-    const result = await platform.call({
-      tool: 'email',
-      method: 'send',
-      params: {
-        to: input.recipientEmail,
-        subject: input.subject,
-        body: input.body,
-      },
-      credential: 'sendgrid',          // name of the stored credential
-    });
-
-    context.logger.info('Email sent', { messageId: result.messageId });
-    return { sent: true, messageId: result.messageId };
-  },
-  next: null,
-};
-```
-
-**Key points:**
-
-- `platform.call()` is async and times out after 60 seconds
-- `credential` is the name of a platform environment variable set via `elevasis-sdk env set`
-- On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
-- Always log success so executions are easy to debug in the dashboard
-
----
-
-## Error Handling
-
-### Catching Tool Errors
-
-Use `PlatformToolError` (from `@elevasis/sdk/worker`) to handle tool-specific failures without catching everything:
-
-```typescript
-import { platform, PlatformToolError } from '@elevasis/sdk/worker';
-
-const step = async (input) => {
-  try {
-    const result = await platform.call({
-      tool: 'crm',
-      method: 'createContact',
-      params: { email: input.email, name: input.name },
-      credential: 'CRM_API_KEY',
-    });
-    return { contactId: result.id };
-  } catch (err) {
-    if (err instanceof PlatformToolError) {
-      // Tool failed -- log it and return a degraded result
-      console.error('CRM tool failed:', err.message);
-      return { contactId: null, error: err.message };
-    }
-    throw err; // re-throw unexpected errors
-  }
-};
-```
-
-### Failing an Execution Explicitly
-
-Use `ExecutionError` when your step detects a condition that should mark the entire execution as failed:
-
-```typescript
-import { ExecutionError } from '@elevasis/sdk';
-
-const validateStep = async (input) => {
-  if (!input.userId) {
-    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
-  }
-  if (input.amount \<= 0) {
-    throw new ExecutionError('amount must be positive', { code: 'INVALID_AMOUNT' });
-  }
-  return { valid: true };
-};
-```
-
-`ExecutionError` messages and metadata appear in the Elevasis dashboard under the failed execution's detail view.
-
-### Using ToolingError
-
-`ToolingError` is thrown by lower-level platform operations (not `platform.call()` directly). You may encounter it in advanced scenarios:
-
-```typescript
-import { ToolingError } from '@elevasis/sdk';
-
-const step = async (input) => {
-  try {
-    return await doSomething(input);
-  } catch (err) {
-    if (err instanceof ToolingError) {
-      // check err.type for the error category
-      console.error('Tooling error:', err.type, err.message);
-    }
-    throw err;
-  }
-};
-```
-
----
-
-## Logging in Steps
-
-The `context.logger` writes structured logs attached to the execution. Use it instead of `console.log` so logs appear in the dashboard alongside the execution record.
-
-```typescript
-import type { StepHandler } from '@elevasis/sdk';
-
-const processStep: StepHandler = async (input, context) => {
-  context.logger.info('Starting process', { userId: input.userId });
-
-  const result = await doWork(input);
-
-  context.logger.info('Process complete', { resultId: result.id });
-  return result;
-};
-```
-
-Avoid logging sensitive values (API keys, passwords, PII) since logs are stored and visible in the dashboard.
-
----
-
-## Using the Execution Store
-
-`context.store` is a simple key-value store scoped to the current execution. Use it to pass data between steps without coupling step interfaces, or to checkpoint long-running work.
-
-```typescript
-const firstStep: StepHandler = async (input, context) => {
-  const data = await fetchExpensiveData(input.id);
-
-  // Save for use by later steps
-  await context.store.set('fetchedData', JSON.stringify(data));
-
-  return { fetched: true };
-};
-
-const secondStep: StepHandler = async (input, context) => {
-  const raw = await context.store.get('fetchedData');
-  const data = JSON.parse(raw ?? '{}');
-
-  return { processed: transform(data) };
-};
-```
-
-Store values are strings. Serialize objects with `JSON.stringify` and parse with `JSON.parse`.
-
----
-
-## Resource Status
-
-### Dev vs Production
-
-While building a resource, set `config.status` to `'dev'`:
-
-```typescript
-const myWorkflow: WorkflowDefinition = {
-  config: {
-    name: 'my-workflow',
-    description: 'Does something useful',
-    status: 'dev', // only manually triggerable
-  },
-  // ...
-};
-```
-
-Dev resources:
-
-- Appear in `elevasis-sdk resources` output
-- Can be triggered with `elevasis-sdk exec my-workflow --input '{...}'`
-- Will NOT receive scheduled or webhook-triggered executions
-- Will NOT appear as available to external callers
-
-When you are ready to go live, change to `'production'` and redeploy:
-
-```typescript
-config: {
-  name: 'my-workflow',
-  description: 'Does something useful',
-  status: 'production', // receives all execution sources
-},
-```
-
-### Global Default Status
-
-Set a project-wide default in `elevasis.config.ts` to keep all resources in `'dev'` mode during development without touching each resource file:
-
-```typescript
-import type { ElevasConfig } from '@elevasis/sdk';
-
-const config: ElevasConfig = {
-  defaultStatus: 'dev',
-};
-
-export default config;
-```
-
-Individual resources that set their own `config.status` override this default.
-
----
-
-## Organizing Multiple Resources
-
-As your project grows, organize resources by business domain. Each domain gets its own directory with an `index.ts` barrel that exports `workflows` and `agents` arrays:
-
-```typescript
-// src/orders/fulfill-order.ts
-export const fulfillOrder: WorkflowDefinition = { ... };
-
-// src/billing/send-invoice.ts
-export const sendInvoice: WorkflowDefinition = { ... };
-
-// src/orders/index.ts
-import { fulfillOrder } from './fulfill-order.js';
-export const workflows = [fulfillOrder];
-export const agents = [];
-
-// src/billing/index.ts
-import { sendInvoice } from './send-invoice.js';
-export const workflows = [sendInvoice];
-export const agents = [];
-
-// src/index.ts
-import type { OrganizationResources } from '@elevasis/sdk';
-import * as orders from './orders/index.js';
-import * as billing from './billing/index.js';
-
-const org: OrganizationResources = {
-  workflows: [
-    ...orders.workflows,
-    ...billing.workflows,
-  ],
-  agents: [
-    ...orders.agents,
-    ...billing.agents,
-  ],
-};
-
-export default org;
-```
-
-The keys in `workflows` and `agents` are the resource identifiers used in CLI commands and the dashboard. Choose names that are descriptive and use kebab-case for consistency.
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Common Patterns
+description: Common resource patterns for Elevasis SDK developers -- sequential steps, conditional branching, platform tools, error handling, and resource status management
+loadWhen: "Building or modifying a workflow"
+---
+
+This page collects the patterns you will reach for most often when writing resources. Each pattern is self-contained and can be adapted directly into your project.
+
+---
+
+## Sequential Workflow Steps
+
+The simplest pattern: a chain of steps where each step feeds its output into the next.
+
+```typescript
+import { z } from 'zod';
+import { StepType } from '@elevasis/sdk';
+import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
+
+const inputSchema = z.object({ orderId: z.string() });
+const outputSchema = z.object({ shipped: z.boolean(), trackingNumber: z.string() });
+
+type Input = z.infer<typeof inputSchema>;
+type Output = z.infer<typeof outputSchema>;
+
+const validateStep: WorkflowStep = {
+  type: StepType.LINEAR,
+  handler: async (input: Input) => {
+    const order = await getOrder(input.orderId);
+    if (!order) throw new Error(`Order ${input.orderId} not found`);
+    return { order };
+  },
+  next: { type: 'linear', target: 'ship' },
+};
+
+const shipStep: WorkflowStep = {
+  type: StepType.LINEAR,
+  handler: async (input) => {
+    const tracking = await createShipment(input.order);
+    return { shipped: true, trackingNumber: tracking.number };
+  },
+  next: null, // terminal -- no further steps
+};
+
+const fulfillOrder: WorkflowDefinition = {
+  config: { resourceId: 'fulfill-order', name: 'Fulfill Order', type: 'workflow', description: 'Validates and ships an order', version: '1.0.0', status: 'dev' },
+  contract: { inputSchema, outputSchema },
+  steps: { validate: validateStep, ship: shipStep },
+  entryPoint: 'validate',
+};
+```
+
+**Key points:**
+
+- `next: { target: 'stepName' }` routes to the next step
+- `next: null` marks the terminal step
+- Each step receives the full return value of the previous step as its `input`
+- The terminal step's return value must satisfy `contract.output`
+
+---
+
+## Conditional Branching
+
+Use `StepType.CONDITIONAL` when the next step depends on the output of the current step.
+
+```typescript
+import { StepType } from '@elevasis/sdk';
+import type { WorkflowStep } from '@elevasis/sdk';
+
+const scoreStep: WorkflowStep = {
+  type: StepType.CONDITIONAL,
+  handler: async (input) => {
+    const score = await calculateRiskScore(input.applicationId);
+    return { score, applicationId: input.applicationId };
+  },
+  next: {
+    type: 'conditional',
+    routes: [
+      {
+        condition: (output) => output.score \>= 80,
+        target: 'autoApprove',
+      },
+      {
+        condition: (output) => output.score \>= 40,
+        target: 'manualReview',
+      },
+    ],
+    default: 'autoReject', // used when no condition matches
+  },
+};
+```
+
+**Key points:**
+
+- Routes are evaluated in order -- the first matching condition wins
+- `default` is required and acts as the `else` branch
+- The condition function receives the full handler output
+- All route targets and `default` must be keys in your `steps` record
+
+---
+
+## Using Platform Tools in Steps
+
+Platform tools let your steps call integrations managed by Elevasis (email, CRM, databases, etc.). Import `platform` from `@elevasis/sdk/worker` and call it with the tool name, method, parameters, and a credential reference.
+
+```typescript
+import { platform, PlatformToolError } from '@elevasis/sdk/worker';
+import type { WorkflowStep } from '@elevasis/sdk';
+import { StepType } from '@elevasis/sdk';
+
+const sendEmailStep: WorkflowStep = {
+  type: StepType.LINEAR,
+  handler: async (input, context) => {
+    const result = await platform.call({
+      tool: 'email',
+      method: 'send',
+      params: {
+        to: input.recipientEmail,
+        subject: input.subject,
+        body: input.body,
+      },
+      credential: 'sendgrid',          // name of the stored credential
+    });
+
+    context.logger.info('Email sent', { messageId: result.messageId });
+    return { sent: true, messageId: result.messageId };
+  },
+  next: null,
+};
+```
+
+**Key points:**
+
+- `platform.call()` is async and times out after 60 seconds
+- `credential` is the name of a platform environment variable set via `elevasis-sdk env set`
+- On failure, `platform.call()` throws `PlatformToolError` (not `ToolingError`)
+- Always log success so executions are easy to debug in the dashboard
+
+---
+
+## Error Handling
+
+### Catching Tool Errors
+
+Use `PlatformToolError` (from `@elevasis/sdk/worker`) to handle tool-specific failures without catching everything:
+
+```typescript
+import { platform, PlatformToolError } from '@elevasis/sdk/worker';
+
+const step = async (input) => {
+  try {
+    const result = await platform.call({
+      tool: 'crm',
+      method: 'createContact',
+      params: { email: input.email, name: input.name },
+      credential: 'CRM_API_KEY',
+    });
+    return { contactId: result.id };
+  } catch (err) {
+    if (err instanceof PlatformToolError) {
+      // Tool failed -- log it and return a degraded result
+      console.error('CRM tool failed:', err.message);
+      return { contactId: null, error: err.message };
+    }
+    throw err; // re-throw unexpected errors
+  }
+};
+```
+
+### Failing an Execution Explicitly
+
+Use `ExecutionError` when your step detects a condition that should mark the entire execution as failed:
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk';
+
+const validateStep = async (input) => {
+  if (!input.userId) {
+    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
+  }
+  if (input.amount \<= 0) {
+    throw new ExecutionError('amount must be positive', { code: 'INVALID_AMOUNT' });
+  }
+  return { valid: true };
+};
+```
+
+`ExecutionError` messages and metadata appear in the Elevasis dashboard under the failed execution's detail view.
+
+### Using ToolingError
+
+`ToolingError` is thrown by lower-level platform operations (not `platform.call()` directly). You may encounter it in advanced scenarios:
+
+```typescript
+import { ToolingError } from '@elevasis/sdk';
+
+const step = async (input) => {
+  try {
+    return await doSomething(input);
+  } catch (err) {
+    if (err instanceof ToolingError) {
+      // check err.type for the error category
+      console.error('Tooling error:', err.type, err.message);
+    }
+    throw err;
+  }
+};
+```
+
+---
+
+## Logging in Steps
+
+The `context.logger` writes structured logs attached to the execution. Use it instead of `console.log` so logs appear in the dashboard alongside the execution record.
+
+```typescript
+import type { StepHandler } from '@elevasis/sdk';
+
+const processStep: StepHandler = async (input, context) => {
+  context.logger.info('Starting process', { userId: input.userId });
+
+  const result = await doWork(input);
+
+  context.logger.info('Process complete', { resultId: result.id });
+  return result;
+};
+```
+
+Avoid logging sensitive values (API keys, passwords, PII) since logs are stored and visible in the dashboard.
+
+---
+
+## Using the Execution Store
+
+`context.store` is a simple key-value store scoped to the current execution. Use it to pass data between steps without coupling step interfaces, or to checkpoint long-running work.
+
+```typescript
+const firstStep: StepHandler = async (input, context) => {
+  const data = await fetchExpensiveData(input.id);
+
+  // Save for use by later steps
+  await context.store.set('fetchedData', JSON.stringify(data));
+
+  return { fetched: true };
+};
+
+const secondStep: StepHandler = async (input, context) => {
+  const raw = await context.store.get('fetchedData');
+  const data = JSON.parse(raw ?? '{}');
+
+  return { processed: transform(data) };
+};
+```
+
+Store values are strings. Serialize objects with `JSON.stringify` and parse with `JSON.parse`.
+
+---
+
+## Resource Status
+
+### Dev vs Production
+
+While building a resource, set `config.status` to `'dev'`:
+
+```typescript
+const myWorkflow: WorkflowDefinition = {
+  config: {
+    name: 'my-workflow',
+    description: 'Does something useful',
+    status: 'dev', // only manually triggerable
+  },
+  // ...
+};
+```
+
+Dev resources:
+
+- Appear in `elevasis-sdk resources` output
+- Can be triggered with `elevasis-sdk exec my-workflow --input '{...}'`
+- Will NOT receive scheduled or webhook-triggered executions
+- Will NOT appear as available to external callers
+
+When you are ready to go live, change to `'prod'` and redeploy:
+
+```typescript
+config: {
+  name: 'my-workflow',
+  description: 'Does something useful',
+  status: 'prod', // receives all execution sources
+},
+```
+
+### Global Default Status
+
+Set a project-wide default in `elevasis.config.ts` to keep all resources in `'dev'` mode during development without touching each resource file:
+
+```typescript
+import type { ElevasConfig } from '@elevasis/sdk';
+
+const config: ElevasConfig = {
+  defaultStatus: 'dev',
+};
+
+export default config;
+```
+
+Individual resources that set their own `config.status` override this default.
+
+---
+
+## Organizing Multiple Resources
+
+As your project grows, organize resources by business domain. Each domain gets its own directory with an `index.ts` barrel that exports `workflows` and `agents` arrays:
+
+```typescript
+// src/orders/fulfill-order.ts
+export const fulfillOrder: WorkflowDefinition = { ... };
+
+// src/billing/send-invoice.ts
+export const sendInvoice: WorkflowDefinition = { ... };
+
+// src/orders/index.ts
+import { fulfillOrder } from './fulfill-order.js';
+export const workflows = [fulfillOrder];
+export const agents = [];
+
+// src/billing/index.ts
+import { sendInvoice } from './send-invoice.js';
+export const workflows = [sendInvoice];
+export const agents = [];
+
+// src/index.ts
+import type { OrganizationResources } from '@elevasis/sdk';
+import * as orders from './orders/index.js';
+import * as billing from './billing/index.js';
+
+const org: OrganizationResources = {
+  workflows: [
+    ...orders.workflows,
+    ...billing.workflows,
+  ],
+  agents: [
+    ...orders.agents,
+    ...billing.agents,
+  ],
+};
+
+export default org;
+```
+
+The keys in `workflows` and `agents` are the resource identifiers used in CLI commands and the dashboard. Choose names that are descriptive and use kebab-case for consistency.
+
+---
+
+**Last Updated:** 2026-02-25