@elevasis/sdk 0.5.13 → 0.5.15

package/reference/resources/types.mdx

@@ -1,207 +1,207 @@
----
-title: SDK Types
-description: Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values
-loadWhen: "Looking up type signatures or SDK exports"
----
-
-`@elevasis/sdk` is published to the public npm registry. It bundles all platform types from `@repo/core` into a single self-contained type declaration file with zero internal monorepo references. External developers install the package and get full TypeScript support without any monorepo tooling.
-
-```bash
-pnpm add @elevasis/sdk zod
-```
-
-Zod is a peer dependency and must be installed separately.
-
----
-
-## Package Exports
-
-The package exposes two subpaths:
-
-```json
-{
-  "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./worker": { "import": "./dist/worker/index.js" }
-  }
-}
-```
-
-- `@elevasis/sdk` -- all types plus runtime values (`StepType`, `ExecutionError`, `ToolingError`)
-- `@elevasis/sdk/worker` -- worker runtime module (`startWorker`, `platform`, `PlatformToolError`)
-
----
-
-## Type Re-exports
-
-All types come from the platform core. The SDK re-exports them grouped by source domain:
-
-### Platform Types
-
-| Type | Description |
-| ---- | ----------- |
-| `ResourceDefinition` | Base interface for all resource types |
-| `ResourceType` | Enum: `'workflow' | 'agent'` |
-| `ResourceStatus` | Enum: `'dev' | 'production'` |
-| `ResourceDomain` | Domain classification for a resource |
-| `DomainDefinition` | Structure for grouping resources by domain |
-| `OrganizationResources` | Top-level export shape: `{ workflows, agents }` |
-| `TriggerDefinition` | Base for trigger configuration |
-| `IntegrationDefinition` | Integration configuration structure |
-| `WebhookProviderType` | Supported webhook providers |
-| `WebhookTriggerConfig` | Webhook trigger configuration |
-| `ScheduleTriggerConfig` | Cron/schedule trigger configuration |
-| `EventTriggerConfig` | Internal event trigger configuration |
-| `TriggerConfig` | Union of all trigger config types |
-
-### Execution Types
-
-| Type | Description |
-| ---- | ----------- |
-| `WorkflowDefinition` | Complete workflow definition including config, contract, steps, entryPoint |
-| `WorkflowStep` | Individual step definition with type, handler, and next routing |
-| `WorkflowConfig` | Metadata block: name, description, status |
-| `StepHandler` | Function type: `(input: unknown, context: StepContext) => Promise<unknown>` |
-| `NextConfig` | Union of `LinearNext` and `ConditionalNext` |
-| `LinearNext` | `{ target: string }` -- fixed next step |
-| `ConditionalNext` | `{ routes: Route[], defaultTarget: string }` -- branching routing |
-| `StepType` | Runtime enum: `LINEAR | CONDITIONAL` (also a runtime value -- see below) |
-| `AgentDefinition` | Complete agent definition including config, agentConfig, tools |
-| `AgentConfig` | Agent metadata: name, description, status |
-| `AgentConstraints` | Execution limits for agents |
-| `Tool` | Tool definition for agent use |
-| `ToolExecutionOptions` | Options passed when a tool executes |
-| `ToolingErrorType` | Enum of tool error categories |
-| `ToolingError` | Error class for tool execution failures (also a runtime value -- see below) |
-| `ExecutionError` | Error class for execution-level failures (also a runtime value -- see below) |
-| `Contract` | Input/output Zod schema pair |
-| `ExecutionContext` | Runtime context passed to step handlers |
-| `ExecutionMetadata` | Metadata about a running execution |
-| `LLMModel` | Model identifier: provider + model name |
-| `ModelConfig` | Full model configuration including temperature and token limits |
-| `ExecutionInterface` | Interface for triggering and inspecting executions |
-
-### Form and Metrics Types
-
-| Type | Description |
-| ---- | ----------- |
-| `FormField` | Individual form field definition |
-| `FormSchema` | Collection of form fields |
-| `FormFieldType` | Enum of supported field types |
-| `ResourceMetricsConfig` | Observability configuration for a resource |
-
----
-
-## ElevasConfig
-
-`ElevasConfig` is the only type defined by the SDK itself (not re-exported from the platform). It configures SDK behavior via `elevasis.config.ts` in your project root.
-
-```typescript
-export interface ElevasConfig {
-  defaultStatus?: ResourceStatus
-  dev?: { port?: number }
-}
-```
-
-| Field | Type | Default | Description |
-| ----- | ---- | ------- | ----------- |
-| `defaultStatus` | `'dev' | 'production'` | `'production'` | Default status applied to all resources that do not set their own `config.status`. Set to `'dev'` to keep resources inactive while building. |
-| `dev.port` | `number` | `3001` | Local port for the development worker process. Change this if port 3001 conflicts with another service. |
-
-Usage:
-
-```typescript
-import type { ElevasConfig } from '@elevasis/sdk';
-
-const config: ElevasConfig = {
-  defaultStatus: 'dev',
-  dev: { port: 3002 },
-};
-
-export default config;
-```
-
----
-
-## StepHandler Context
-
-`StepHandler` accepts two parameters: `input` (validated by your contract schema) and `context` (runtime metadata). The `context` parameter is not optional in the type definition, but TypeScript allows you to omit it in your handler function -- writing `async (input) => { ... }` works without error.
-
-```typescript
-import type { StepHandler, ExecutionContext } from '@elevasis/sdk';
-
-const handler: StepHandler = async (input, context: ExecutionContext) => {
-  const { executionId, organizationId, resourceId, logger, store } = context;
-
-  logger.info('Processing', { executionId, resourceId });
-
-  await store.set('checkpoint', JSON.stringify({ step: 'started' }));
-
-  return { done: true };
-};
-```
-
-### ExecutionContext Fields
-
-| Field | Type | Description |
-| ----- | ---- | ----------- |
-| `executionId` | `string` | Unique identifier for this execution run |
-| `organizationId` | `string` | Your organization identifier |
-| `resourceId` | `string` | Identifier of the executing workflow or agent |
-| `logger` | `Logger` | Structured logger -- messages appear in the Elevasis dashboard under the execution |
-| `store` | `Store` | Key-value store scoped to the current execution. Useful for passing data between steps or checkpointing progress. |
-
----
-
-## Runtime Values
-
-Three runtime values are exported from `@elevasis/sdk` as JavaScript values (not just types). They are defined directly in the SDK package to avoid pulling in the full platform execution engine.
-
-### StepType
-
-An enum used to configure step routing in multi-step workflows.
-
-```typescript
-import { StepType } from '@elevasis/sdk';
-
-// StepType.LINEAR   -- fixed next step via { target: 'stepName' }
-// StepType.CONDITIONAL -- branching via { routes: [...], defaultTarget: 'stepName' }
-```
-
-### ToolingError
-
-Thrown by platform tool calls when a tool fails. Use this class to distinguish tool failures from general errors in `try/catch` blocks.
-
-```typescript
-import { ToolingError } from '@elevasis/sdk';
-
-try {
-  const result = await platform.call({ ... });
-} catch (err) {
-  if (err instanceof ToolingError) {
-    // tool-specific failure -- check err.type for category
-    console.error('Tool failed:', err.type, err.message);
-  } else {
-    throw err; // re-throw unexpected errors
-  }
-}
-```
-
-### ExecutionError
-
-Represents a failure at the execution level (distinct from a tool-level failure). Throw this from a step handler to signal that the execution should be marked as failed with a structured error message.
-
-```typescript
-import { ExecutionError } from '@elevasis/sdk';
-
-const handler = async (input) => {
-  if (!input.userId) {
-    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
-  }
-  return { result: 'ok' };
-};
-```
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: SDK Types
+description: Complete type reference for @elevasis/sdk -- package exports, re-exported platform types, ElevasConfig interface, StepHandler context, and runtime values
+loadWhen: "Looking up type signatures or SDK exports"
+---
+
+`@elevasis/sdk` is published to the public npm registry. It bundles all platform types from `@repo/core` into a single self-contained type declaration file with zero internal monorepo references. External developers install the package and get full TypeScript support without any monorepo tooling.
+
+```bash
+pnpm add @elevasis/sdk zod
+```
+
+Zod is a peer dependency and must be installed separately.
+
+---
+
+## Package Exports
+
+The package exposes two subpaths:
+
+```json
+{
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./worker": { "import": "./dist/worker/index.js" }
+  }
+}
+```
+
+- `@elevasis/sdk` -- all types plus runtime values (`StepType`, `ExecutionError`, `ToolingError`)
+- `@elevasis/sdk/worker` -- worker runtime module (`startWorker`, `platform`, `PlatformToolError`)
+
+---
+
+## Type Re-exports
+
+All types come from the platform core. The SDK re-exports them grouped by source domain:
+
+### Platform Types
+
+| Type                    | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| `ResourceDefinition`    | Base interface for all resource types           |
+| `ResourceType`          | Enum: `'workflow' | 'agent'`                   |
+| `ResourceStatus`        | Enum: `'dev' | 'prod'`                         |
+| `ResourceDomain`        | Domain classification for a resource            |
+| `DomainDefinition`      | Structure for grouping resources by domain      |
+| `OrganizationResources` | Top-level export shape: `{ workflows, agents }` |
+| `TriggerDefinition`     | Base for trigger configuration                  |
+| `IntegrationDefinition` | Integration configuration structure             |
+| `WebhookProviderType`   | Supported webhook providers                     |
+| `WebhookTriggerConfig`  | Webhook trigger configuration                   |
+| `ScheduleTriggerConfig` | Cron/schedule trigger configuration             |
+| `EventTriggerConfig`    | Internal event trigger configuration            |
+| `TriggerConfig`         | Union of all trigger config types               |
+
+### Execution Types
+
+| Type                   | Description                                                                      |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| `WorkflowDefinition`   | Complete workflow definition including config, contract, steps, entryPoint       |
+| `WorkflowStep`         | Individual step definition with type, handler, and next routing                  |
+| `WorkflowConfig`       | Metadata block: name, description, status                                        |
+| `StepHandler`          | Function type: `(input: unknown, context: StepContext) => Promise<unknown>`    |
+| `NextConfig`           | Union of `LinearNext` and `ConditionalNext`                                      |
+| `LinearNext`           | `{ type: 'linear', target: string }` -- fixed next step                          |
+| `ConditionalNext`      | `{ type: 'conditional', routes: Route[], default: string }` -- branching routing |
+| `StepType`             | Runtime enum: `LINEAR | CONDITIONAL` (also a runtime value -- see below)        |
+| `AgentDefinition`      | Complete agent definition including config, agentConfig, tools                   |
+| `AgentConfig`          | Agent metadata: name, description, status                                        |
+| `AgentConstraints`     | Execution limits for agents                                                      |
+| `Tool`                 | Tool definition for agent use                                                    |
+| `ToolExecutionOptions` | Options passed when a tool executes                                              |
+| `ToolingErrorType`     | Enum of tool error categories                                                    |
+| `ToolingError`         | Error class for tool execution failures (also a runtime value -- see below)      |
+| `ExecutionError`       | Error class for execution-level failures (also a runtime value -- see below)     |
+| `Contract`             | Input/output Zod schema pair                                                     |
+| `ExecutionContext`     | Runtime context passed to step handlers                                          |
+| `ExecutionMetadata`    | Metadata about a running execution                                               |
+| `LLMModel`             | Model identifier: provider + model name                                          |
+| `ModelConfig`          | Full model configuration including temperature and token limits                  |
+| `ExecutionInterface`   | Interface for triggering and inspecting executions                               |
+
+### Form and Metrics Types
+
+| Type                    | Description                                |
+| ----------------------- | ------------------------------------------ |
+| `FormField`             | Individual form field definition           |
+| `FormSchema`            | Collection of form fields                  |
+| `FormFieldType`         | Enum of supported field types              |
+| `ResourceMetricsConfig` | Observability configuration for a resource |
+
+---
+
+## ElevasConfig
+
+`ElevasConfig` is the only type defined by the SDK itself (not re-exported from the platform). It configures SDK behavior via `elevasis.config.ts` in your project root.
+
+```typescript
+export interface ElevasConfig {
+  defaultStatus?: ResourceStatus
+  dev?: { port?: number }
+}
+```
+
+| Field           | Type              | Default  | Description                                                                                                                                  |
+| --------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `defaultStatus` | `'dev' | 'prod'` | `'prod'` | Default status applied to all resources that do not set their own `config.status`. Set to `'dev'` to keep resources inactive while building. |
+| `dev.port`      | `number`          | `3001`   | Local port for the development worker process. Change this if port 3001 conflicts with another service.                                      |
+
+Usage:
+
+```typescript
+import type { ElevasConfig } from '@elevasis/sdk';
+
+const config: ElevasConfig = {
+  defaultStatus: 'dev',
+  dev: { port: 3002 },
+};
+
+export default config;
+```
+
+---
+
+## StepHandler Context
+
+`StepHandler` accepts two parameters: `input` (validated by your contract schema) and `context` (runtime metadata). The `context` parameter is not optional in the type definition, but TypeScript allows you to omit it in your handler function -- writing `async (input) => { ... }` works without error.
+
+```typescript
+import type { StepHandler, ExecutionContext } from '@elevasis/sdk';
+
+const handler: StepHandler = async (input, context: ExecutionContext) => {
+  const { executionId, organizationId, resourceId, logger, store } = context;
+
+  logger.info('Processing', { executionId, resourceId });
+
+  await store.set('checkpoint', JSON.stringify({ step: 'started' }));
+
+  return { done: true };
+};
+```
+
+### ExecutionContext Fields
+
+| Field            | Type     | Description                                                                                                       |
+| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| `executionId`    | `string` | Unique identifier for this execution run                                                                          |
+| `organizationId` | `string` | Your organization identifier                                                                                      |
+| `resourceId`     | `string` | Identifier of the executing workflow or agent                                                                     |
+| `logger`         | `Logger` | Structured logger -- messages appear in the Elevasis dashboard under the execution                                |
+| `store`          | `Store`  | Key-value store scoped to the current execution. Useful for passing data between steps or checkpointing progress. |
+
+---
+
+## Runtime Values
+
+Three runtime values are exported from `@elevasis/sdk` as JavaScript values (not just types). They are defined directly in the SDK package to avoid pulling in the full platform execution engine.
+
+### StepType
+
+An enum used to configure step routing in multi-step workflows.
+
+```typescript
+import { StepType } from '@elevasis/sdk';
+
+// StepType.LINEAR   -- fixed next step via { target: 'stepName' }
+// StepType.CONDITIONAL -- branching via { type: 'conditional', routes: [...], default: 'stepName' }
+```
+
+### ToolingError
+
+Thrown by platform tool calls when a tool fails. Use this class to distinguish tool failures from general errors in `try/catch` blocks.
+
+```typescript
+import { ToolingError } from '@elevasis/sdk';
+
+try {
+  const result = await platform.call({ ... });
+} catch (err) {
+  if (err instanceof ToolingError) {
+    // tool-specific failure -- check err.type for category
+    console.error('Tool failed:', err.type, err.message);
+  } else {
+    throw err; // re-throw unexpected errors
+  }
+}
+```
+
+### ExecutionError
+
+Represents a failure at the execution level (distinct from a tool-level failure). Throw this from a step handler to signal that the execution should be marked as failed with a structured error message.
+
+```typescript
+import { ExecutionError } from '@elevasis/sdk';
+
+const handler = async (input) => {
+  if (!input.userId) {
+    throw new ExecutionError('userId is required', { code: 'MISSING_INPUT' });
+  }
+  return { result: 'ok' };
+};
+```
+
+---
+
+**Last Updated:** 2026-02-25