@elevasis/sdk 0.4.5 → 0.4.7

package/reference/resources/index.mdx

@@ -0,0 +1,289 @@
+---
+title: Writing Resources
+description: Guide to creating workflows and agents using WorkflowDefinition, AgentDefinition, and OrganizationResources with the Elevasis SDK
+loadWhen: "Building or modifying a workflow"
+---
+
+Resources are the building blocks of your Elevasis project. A resource is a workflow or agent definition that the platform can execute on your behalf. You define them in TypeScript, export them from a single entry point, and the platform handles scheduling, retries, logging, and execution.
+
+This page covers how to structure your resources, write step handlers, and export everything through `OrganizationResources`.
+
+## WorkflowDefinition
+
+A workflow is a series of named steps executed in sequence or branching paths. You define it with a `WorkflowDefinition` object.
+
+A complete workflow definition has four required properties:
+
+- `config` - metadata about the workflow (name, description, status)
+- `contract` - Zod schemas for input and output validation
+- `steps` - a record of named step handlers
+- `entryPoint` - the name of the first step to execute
+
+### Minimal Example
+
+```typescript
+import { z } from 'zod';
+import type { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
+
+const echoInput = z.object({
+  message: z.string(),
+});
+
+const echoOutput = z.object({
+  result: z.string(),
+});
+
+type EchoInput = z.infer<typeof echoInput>;
+type EchoOutput = z.infer<typeof echoOutput>;
+
+const echoWorkflow: WorkflowDefinition = {
+  config: {
+    name: 'echo',
+    description: 'Returns the input message unchanged',
+    status: 'dev',
+  },
+  contract: {
+    input: echoInput,
+    output: echoOutput,
+  },
+  steps: {
+    run: async (input: EchoInput): Promise<EchoOutput> => {
+      return { result: input.message };
+    },
+  },
+  entryPoint: 'run',
+};
+```
+
+### config
+
+The `config` block identifies the workflow on the platform:
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `name` | `string` | Unique name within your organization. Used by the CLI and platform UI. |
+| `description` | `string` | Human-readable summary shown in the dashboard. |
+| `status` | `'dev' | 'production'` | Controls availability. Use `'dev'` while building. See [Resource Status](#resource-status). |
+
+### contract
+
+The `contract` block defines the Zod schemas for input and output. The platform validates input against `contract.input` before passing it to your step handler, and validates the step's return value against `contract.output`.
+
+Always use `z.object()` for both schemas. Use `z.infer` to derive TypeScript types from the schemas -- this keeps types and runtime validation in sync automatically.
+
+```typescript
+const contract = {
+  input: z.object({
+    userId: z.string().uuid(),
+    action: z.string(),
+  }),
+  output: z.object({
+    success: z.boolean(),
+    message: z.string(),
+  }),
+};
+```
+
+### steps
+
+The `steps` record maps step names to handler functions. Each handler receives the validated input and an optional `StepContext` (execution metadata). Single-step workflows have one entry; multi-step workflows have one entry per step.
+
+```typescript
+const steps = {
+  validate: async (input: MyInput) => {
+    // first step -- returns output to pass to next step
+    return { validated: true, data: input };
+  },
+  process: async (input: ValidatedData) => {
+    // second step
+    return { result: 'done' };
+  },
+};
+```
+
+### entryPoint
+
+`entryPoint` is the name of the first step. For single-step workflows it is always the only step name. For multi-step workflows it is the name of the first step in the chain.
+
+```typescript
+const workflow: WorkflowDefinition = {
+  // ...
+  entryPoint: 'validate', // execution starts here
+};
+```
+
+---
+
+## Multi-Step Workflows
+
+For workflows with more than one step, import `StepType` from `@elevasis/sdk` to configure step routing.
+
+### Linear Steps
+
+Use `StepType.LINEAR` to connect steps in a fixed sequence. Each step declares a `next` property pointing to the next step name.
+
+```typescript
+import { z } from 'zod';
+import { StepType } from '@elevasis/sdk';
+import type { WorkflowDefinition, WorkflowStep } from '@elevasis/sdk';
+
+const fetchStep: WorkflowStep = {
+  type: StepType.LINEAR,
+  handler: async (input) => {
+    const data = await fetchSomething(input.id);
+    return { data };
+  },
+  next: { target: 'process' },
+};
+
+const processStep: WorkflowStep = {
+  type: StepType.LINEAR,
+  handler: async (input) => {
+    return { result: transform(input.data) };
+  },
+  next: null, // terminal step
+};
+
+const pipeline: WorkflowDefinition = {
+  config: { name: 'pipeline', description: 'Fetch then process', status: 'dev' },
+  contract: { input: pipelineInput, output: pipelineOutput },
+  steps: { fetch: fetchStep, process: processStep },
+  entryPoint: 'fetch',
+};
+```
+
+### Conditional Branching
+
+Use `StepType.CONDITIONAL` to route to different steps based on output values. Each route has a `condition` function and a `target` step name. The first condition that returns `true` wins. A `defaultTarget` is required as a fallback.
+
+```typescript
+import { StepType } from '@elevasis/sdk';
+import type { WorkflowStep } from '@elevasis/sdk';
+
+const routerStep: WorkflowStep = {
+  type: StepType.CONDITIONAL,
+  handler: async (input) => {
+    const score = await evaluate(input);
+    return { score };
+  },
+  next: {
+    routes: [
+      {
+        condition: (output) => output.score \>= 80,
+        target: 'highScorePath',
+      },
+      {
+        condition: (output) => output.score \>= 50,
+        target: 'mediumScorePath',
+      },
+    ],
+    defaultTarget: 'lowScorePath',
+  },
+};
+```
+
+---
+
+## StepContext
+
+Every step handler can optionally accept a second `context` parameter. TypeScript allows you to omit it if you do not need it -- you can write `handler: async (input) => { ... }` without declaring `context`.
+
+When you do need it, the context provides runtime metadata:
+
+```typescript
+import type { StepHandler } from '@elevasis/sdk';
+
+const myStep: StepHandler = async (input, context) => {
+  const { executionId, organizationId, resourceId, logger, store } = context;
+
+  logger.info('Starting step', { executionId });
+
+  // store is a simple key-value store scoped to this execution
+  await store.set('progress', '50%');
+
+  return { done: true };
+};
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `executionId` | `string` | Unique ID for this execution run |
+| `organizationId` | `string` | Your organization ID |
+| `resourceId` | `string` | ID of the workflow or agent being executed |
+| `logger` | `Logger` | Structured logger -- messages appear in the Elevasis dashboard |
+| `store` | `Store` | Key-value store scoped to the current execution |
+
+---
+
+## AgentDefinition
+
+Agents are autonomous resources that use an LLM and tools to complete a goal. You define them with `AgentDefinition`.
+
+**Note:** Agent execution in the worker runtime is not yet fully supported. Defining agents is supported for forward compatibility, but executions will return a failure response until agent execution ships.
+
+```typescript
+import type { AgentDefinition } from '@elevasis/sdk';
+
+const myAgent: AgentDefinition = {
+  config: {
+    name: 'my-agent',
+    description: 'Answers questions using platform tools',
+    status: 'dev',
+  },
+  agentConfig: {
+    model: { provider: 'openai', model: 'gpt-4o' },
+    systemPrompt: 'You are a helpful assistant.',
+    maxIterations: 10,
+  },
+  tools: [],
+};
+```
+
+---
+
+## OrganizationResources
+
+All resources must be exported through an `OrganizationResources` default export from `src/index.ts`. This is the entry point the platform reads when you deploy.
+
+```typescript
+import type { OrganizationResources } from '@elevasis/sdk';
+
+const org: OrganizationResources = {
+  workflows: {
+    echo: echoWorkflow,
+    pipeline: pipeline,
+  },
+  agents: {
+    // myAgent: myAgent,
+  },
+};
+
+export default org;
+```
+
+The keys under `workflows` and `agents` are used as resource identifiers on the platform. They appear in CLI output (`elevasis resources`), execution commands (`elevasis exec`), and the dashboard.
+
+### Resource Status
+
+Set `config.status` to control whether the platform accepts execution requests:
+
+- `'dev'` - Resource is visible in the dashboard but the platform will not route scheduled or webhook-triggered executions to it. You can still trigger it manually via `elevasis exec`.
+- `'production'` - Resource is live and accepts all execution sources.
+
+Use `'dev'` while you are building and testing. Switch to `'production'` when you are ready to go live.
+
+You can also set a global default status in `elevasis.config.ts`:
+
+```typescript
+import type { ElevasConfig } from '@elevasis/sdk';
+
+const config: ElevasConfig = {
+  defaultStatus: 'dev',
+};
+
+export default config;
+```
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/resources/patterns.mdx

@@ -0,0 +1,341 @@
+---
+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 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 resources` output
+- Can be triggered with `elevasis 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, split resources into separate files and import them into `src/index.ts`:
+
+```typescript
+// src/workflows/fulfill-order.ts
+export const fulfillOrder: WorkflowDefinition = { ... };
+
+// src/workflows/send-invoice.ts
+export const sendInvoice: WorkflowDefinition = { ... };
+
+// src/index.ts
+import { fulfillOrder } from './workflows/fulfill-order';
+import { sendInvoice } from './workflows/send-invoice';
+import type { OrganizationResources } from '@elevasis/sdk';
+
+const org: OrganizationResources = {
+  workflows: {
+    'fulfill-order': fulfillOrder,
+    'send-invoice': sendInvoice,
+  },
+  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