@elevasis/sdk 0.5.13 → 0.5.15

package/reference/concepts.mdx

@@ -120,35 +120,9 @@ type MyInput = z.infer<typeof myInput>;
 
 ## Platform Tools Overview
 
-Platform tools are pre-built integrations the platform provides. You call them from inside workflow steps using `platform.call()` without managing API keys in your code.
+Platform tools are pre-built integrations the platform provides. You call them from inside workflow steps using `platform.call()` or typed adapters without managing API keys in your code. The platform supports 70+ tools across 12 categories including CRM, email, payments, AI, storage, and more. Credentials are stored securely on the platform and injected at runtime -- they never appear in your code.
 
-### Tool Categories
-
-| Category      | Tools                      | Example Use                                        |
-| ------------- | -------------------------- | -------------------------------------------------- |
-| Communication | Gmail, Resend, email       | Send transactional emails, notifications           |
-| CRM           | Attio (11 methods)         | Create leads, update records, search contacts      |
-| Documents     | PDF, Google Sheets, Notion | Generate invoices, read spreadsheets, update pages |
-| AI            | LLM (GPT, Gemini, Claude)  | Classify text, extract data, generate content      |
-| Storage       | Dropbox, platform storage  | Upload files, create signed URLs                   |
-| Scheduling    | Scheduler                  | Run workflows on a schedule or after a delay       |
-| Approvals     | Approval gates             | Pause workflow until a human approves              |
-| Verification  | Mailso                     | Verify email addresses                             |
-| E-Signatures  | SignatureAPI               | Create and manage document envelopes               |
-| Marketing     | Instantly                  | Send email campaigns                               |
-| Payments      | Stripe                     | Create payment links, checkout sessions            |
-| Automation    | Apify                      | Run web scraping actors                            |
-
-### How Credentials Work
-
-1. Create a credential in the Elevasis platform (API key, OAuth token, etc.) via the command center UI
-2. Give it a name (e.g., `my-gmail`, `production-attio`)
-3. In your code, pass that name: `platform.call({ credential: 'my-gmail', ... })`
-4. The platform injects the actual API key at runtime -- it never appears in your code
-
-### What Happens When a Credential Name is Wrong
-
-You will see a `PlatformToolError` with the message "credential not found". Check for typos -- credential names are case-sensitive.
+See [Platform Tools](platform-tools/index.mdx) for the complete catalog, credential setup, and code examples.
 
 ---
 
@@ -156,7 +130,7 @@ You will see a `PlatformToolError` with the message "credential not found". Chec
 
 | Error                                     | How to Fix                                                                      |
 | ----------------------------------------- | ------------------------------------------------------------------------------- |
-| `ELEVASIS_API_KEY not set`                | Add `ELEVASIS_API_KEY=sk_...` to `.env`                                         |
+| `ELEVASIS_PLATFORM_KEY not set`           | Add `ELEVASIS_PLATFORM_KEY=sk_...` to `.env`                                    |
 | `Schema validation failed`                | Compare error field names to your schema. Check types and required vs optional. |
 | `Cannot find module '@elevasis/sdk'`      | Run `pnpm install`                                                              |
 | `PlatformToolError: credential not found` | Check spelling and case in the command center UI                                |
@@ -177,26 +151,13 @@ Use a single step when the workflow does one thing -- validate an email, format
 
 Use multiple steps when you have distinct phases (fetch data, process it, send a notification) or when you want separate error handling per phase. Each step failure is logged independently, making it easier to identify where something went wrong.
 
-### dev vs production Status
-
-- **dev** -- Resource is visible in the dashboard and can be triggered manually, but will not auto-trigger from schedules or webhooks. Use while building and testing.
-- **production** -- Resource is fully live. All trigger sources work. Use when you are confident it works correctly.
-
-You can switch between them by changing `status` in the workflow config and redeploying.
-
 ### When to Use Conditional Routing
 
 Use `StepType.CONDITIONAL` when different inputs should follow different processing paths.
 
 Example: score >= 80 goes to the approve path, score >= 50 goes to the review path, everything else goes to the reject path. Each path can have its own steps and logic.
 
-Always include a `defaultTarget` fallback for inputs that do not match any condition. Without a fallback, an unmatched execution will fail.
-
-### When to Use Platform Tools vs Custom Code
-
-Use platform tools when the integration exists in the tool catalog -- they handle auth, retries, and error normalization for you.
-
-Write custom code (e.g., using `fetch` directly) only when you need a service or API method that is not in the catalog, or when you need fine-grained control over the HTTP request.
+Always include a `default` fallback step for inputs that do not match any condition. Without a fallback, an unmatched execution will fail.
 
 ---
 

package/reference/deployment/api.mdx

@@ -1,297 +1,297 @@
----
-title: Execution API
-description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
-loadWhen: "Calling the API directly or debugging API responses"
----
-
-The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_API_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
-
-**Authentication header:**
-
-```
-Authorization: Bearer sk_...
-```
-
----
-
-## API Base URL
-
-| Environment | Base URL |
-| ----------- | -------- |
-| Production | `https://api.elevasis.io` |
-| Development | `http://localhost:<port>` |
-
-Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
-
----
-
-## Endpoints
-
-| Method | Path | Purpose |
-| ------ | ---- | ------- |
-| `GET` | `/api/external/resources` | List all resources for your organization |
-| `GET` | `/api/external/resources/:resourceId/definition` | Get resource metadata and schemas |
-| `POST` | `/api/external/execute` | Execute a resource synchronously |
-| `POST` | `/api/external/execute-async` | Execute a resource asynchronously |
-| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution |
-| `GET` | `/api/external/executions/:resourceId` | List execution history for a resource |
-| `GET` | `/api/external/executions/:resourceId/:executionId` | Get full execution detail |
-| `POST` | `/api/external/deploy` | Upload bundle and deploy resources |
-| `GET` | `/api/external/deployments` | List all deployments |
-| `GET` | `/api/external/deployments/:id` | Get a deployment by ID |
-
----
-
-## Execution Endpoints
-
-### POST /api/external/execute
-
-Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "success": true,
-  "data": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  }
-}
-```
-
-### POST /api/external/execute-async
-
-Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
-
-**Request body:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "input": { "clientName": "Jane" }
-}
-```
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "status": "running"
-}
-```
-
-### POST /api/external/executions/:resourceId/:executionId/cancel
-
-Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
-
-**Response:**
-
-```json
-{
-  "success": true
-}
-```
-
----
-
-## Resource Endpoints
-
-### GET /api/external/resources
-
-List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
-
-**Response:**
-
-```json
-[
-  {
-    "resourceId": "onboard-client",
-    "resourceType": "workflow",
-    "name": "Onboard Client",
-    "status": "prod"
-  },
-  {
-    "resourceId": "email-assistant",
-    "resourceType": "agent",
-    "name": "Email Assistant",
-    "status": "prod"
-  }
-]
-```
-
-### GET /api/external/resources/:resourceId/definition
-
-Get the full definition for a single resource: metadata, input schema, and output schema.
-
-**Response:**
-
-```json
-{
-  "resourceId": "onboard-client",
-  "resourceType": "workflow",
-  "name": "Onboard Client",
-  "description": "Creates a client record and sends a welcome email",
-  "status": "prod",
-  "inputSchema": {
-    "type": "object",
-    "properties": {
-      "clientName": { "type": "string" },
-      "email": { "type": "string", "format": "email" }
-    },
-    "required": ["clientName", "email"]
-  },
-  "outputSchema": {
-    "type": "object",
-    "properties": {
-      "success": { "type": "boolean" },
-      "clientId": { "type": "string" }
-    }
-  }
-}
-```
-
-Returns `404` if the resource is not found.
-
----
-
-## Execution History Endpoints
-
-### GET /api/external/executions/:resourceId
-
-List execution history for a resource.
-
-**Query parameters:**
-
-| Parameter | Description |
-| --------- | ----------- |
-| `limit` | Maximum number of results (default: 20) |
-| `status` | Filter by status: `running`, `completed`, `failed`, `cancelled` |
-
-**Response:**
-
-```json
-[
-  {
-    "executionId": "550e8400-e29b-41d4-a716-446655440000",
-    "resourceId": "onboard-client",
-    "status": "completed",
-    "createdAt": "2026-02-25T14:32:01Z",
-    "durationMs": 1234
-  }
-]
-```
-
-### GET /api/external/executions/:resourceId/:executionId
-
-Get the full detail for a single execution including input, output, logs, and error.
-
-**Response:**
-
-```json
-{
-  "executionId": "550e8400-e29b-41d4-a716-446655440000",
-  "resourceId": "onboard-client",
-  "status": "completed",
-  "createdAt": "2026-02-25T14:32:01Z",
-  "durationMs": 1234,
-  "input": {
-    "clientName": "Jane",
-    "email": "jane@example.com"
-  },
-  "output": {
-    "success": true,
-    "clientId": "client_1708521600000",
-    "welcomeEmailSent": true
-  },
-  "logs": [
-    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
-    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
-  ],
-  "error": null
-}
-```
-
----
-
-## Deployment Endpoints
-
-### POST /api/external/deploy
-
-Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
-
-**Response:**
-
-```json
-{
-  "deployId": "deploy_abc123",
-  "status": "active",
-  "resources": 4
-}
-```
-
-Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
-
-### GET /api/external/deployments
-
-List all deployments for your organization.
-
-**Response:**
-
-```json
-[
-  {
-    "id": "deploy_abc123",
-    "status": "active",
-    "createdAt": "2026-02-25T14:00:00Z",
-    "resources": 4
-  },
-  {
-    "id": "deploy_abc122",
-    "status": "stopped",
-    "createdAt": "2026-02-24T09:30:00Z",
-    "resources": 3
-  }
-]
-```
-
-### GET /api/external/deployments/:id
-
-Get a single deployment by ID.
-
-**Response shape:** Same as a single item from `GET /deployments`.
-
----
-
-## CLI Execution Commands
-
-The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
-
-| Command | API call | Purpose |
-| ------- | -------- | ------- |
-| `elevasis-sdk resources` | `GET /api/external/resources` | List all resources |
-| `elevasis-sdk describe <resource>` | `GET /api/external/resources/:id/definition` | Show resource definition |
-| `elevasis-sdk exec <resource> --input '...'` | `POST /api/external/execute` | Execute synchronously |
-| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async` | Execute asynchronously |
-| `elevasis-sdk executions <resource>` | `GET /api/external/executions/:id` | List execution history |
-| `elevasis-sdk execution <resource> <id>` | `GET /api/external/executions/:id/:execId` | Get execution detail |
-| `elevasis-sdk deployments` | `GET /api/external/deployments` | List deployments |
-
----
-
-**Last Updated:** 2026-02-25
+---
+title: Execution API
+description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
+loadWhen: "Calling the API directly or debugging API responses"
+---
+
+The Elevasis external API exposes REST endpoints under `/api/external/` for executing your deployed resources and inspecting results. All endpoints require your `ELEVASIS_PLATFORM_KEY` sent as a Bearer token. Organization is resolved server-side from the API key -- you never pass an org identifier in requests.
+
+**Authentication header:**
+
+```
+Authorization: Bearer sk_...
+```
+
+---
+
+## API Base URL
+
+| Environment | Base URL                    |
+| ----------- | --------------------------- |
+| Production  | `https://api.elevasis.io`   |
+| Development | `http://localhost:<port>` |
+
+Override the base URL by setting `ELEVASIS_API_URL` in your environment or passing `--api-url` to any CLI command.
+
+---
+
+## Endpoints
+
+| Method | Path                                                       | Purpose                                  |
+| ------ | ---------------------------------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/external/resources`                                  | List all resources for your organization |
+| `GET`  | `/api/external/resources/:resourceId/definition`           | Get resource metadata and schemas        |
+| `POST` | `/api/external/execute`                                    | Execute a resource synchronously         |
+| `POST` | `/api/external/execute-async`                              | Execute a resource asynchronously        |
+| `POST` | `/api/external/executions/:resourceId/:executionId/cancel` | Cancel a running execution               |
+| `GET`  | `/api/external/executions/:resourceId`                     | List execution history for a resource    |
+| `GET`  | `/api/external/executions/:resourceId/:executionId`        | Get full execution detail                |
+| `POST` | `/api/external/deploy`                                     | Upload bundle and deploy resources       |
+| `GET`  | `/api/external/deployments`                                | List all deployments                     |
+| `GET`  | `/api/external/deployments/:id`                            | Get a deployment by ID                   |
+
+---
+
+## Execution Endpoints
+
+### POST /api/external/execute
+
+Execute a resource synchronously. The request waits for the resource to complete and returns the full result.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "success": true,
+  "data": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  }
+}
+```
+
+### POST /api/external/execute-async
+
+Execute a resource asynchronously. Returns immediately with an `executionId`. Poll `GET /executions/:resourceId/:executionId` to check status and retrieve output.
+
+**Request body:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "input": { "clientName": "Jane" }
+}
+```
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "running"
+}
+```
+
+### POST /api/external/executions/:resourceId/:executionId/cancel
+
+Cancel a running execution. If the execution is found in memory, sends a cancellation signal immediately. Falls back to a database status update if no in-memory signal is found.
+
+**Response:**
+
+```json
+{
+  "success": true
+}
+```
+
+---
+
+## Resource Endpoints
+
+### GET /api/external/resources
+
+List all resources registered to your organization. In production, only `status: 'prod'` resources are returned.
+
+**Response:**
+
+```json
+[
+  {
+    "resourceId": "onboard-client",
+    "resourceType": "workflow",
+    "name": "Onboard Client",
+    "status": "prod"
+  },
+  {
+    "resourceId": "email-assistant",
+    "resourceType": "agent",
+    "name": "Email Assistant",
+    "status": "prod"
+  }
+]
+```
+
+### GET /api/external/resources/:resourceId/definition
+
+Get the full definition for a single resource: metadata, input schema, and output schema.
+
+**Response:**
+
+```json
+{
+  "resourceId": "onboard-client",
+  "resourceType": "workflow",
+  "name": "Onboard Client",
+  "description": "Creates a client record and sends a welcome email",
+  "status": "prod",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "clientName": { "type": "string" },
+      "email": { "type": "string", "format": "email" }
+    },
+    "required": ["clientName", "email"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "success": { "type": "boolean" },
+      "clientId": { "type": "string" }
+    }
+  }
+}
+```
+
+Returns `404` if the resource is not found.
+
+---
+
+## Execution History Endpoints
+
+### GET /api/external/executions/:resourceId
+
+List execution history for a resource.
+
+**Query parameters:**
+
+| Parameter | Description                                                     |
+| --------- | --------------------------------------------------------------- |
+| `limit`   | Maximum number of results (default: 20)                         |
+| `status`  | Filter by status: `running`, `completed`, `failed`, `cancelled` |
+
+**Response:**
+
+```json
+[
+  {
+    "executionId": "550e8400-e29b-41d4-a716-446655440000",
+    "resourceId": "onboard-client",
+    "status": "completed",
+    "createdAt": "2026-02-25T14:32:01Z",
+    "durationMs": 1234
+  }
+]
+```
+
+### GET /api/external/executions/:resourceId/:executionId
+
+Get the full detail for a single execution including input, output, logs, and error.
+
+**Response:**
+
+```json
+{
+  "executionId": "550e8400-e29b-41d4-a716-446655440000",
+  "resourceId": "onboard-client",
+  "status": "completed",
+  "createdAt": "2026-02-25T14:32:01Z",
+  "durationMs": 1234,
+  "input": {
+    "clientName": "Jane",
+    "email": "jane@example.com"
+  },
+  "output": {
+    "success": true,
+    "clientId": "client_1708521600000",
+    "welcomeEmailSent": true
+  },
+  "logs": [
+    { "timestamp": "2026-02-25T14:32:01.123Z", "message": "Starting onboard-client workflow" },
+    { "timestamp": "2026-02-25T14:32:01.456Z", "message": "Created client record" }
+  ],
+  "error": null
+}
+```
+
+---
+
+## Deployment Endpoints
+
+### POST /api/external/deploy
+
+Upload a resource bundle and deploy it. Accepts a multipart request with the compiled bundle and resource metadata.
+
+**Response:**
+
+```json
+{
+  "deployId": "deploy_abc123",
+  "status": "active",
+  "resources": 4
+}
+```
+
+Use `elevasis-sdk deploy` from the CLI rather than calling this endpoint directly -- the CLI handles bundling, metadata generation, and status streaming automatically.
+
+### GET /api/external/deployments
+
+List all deployments for your organization.
+
+**Response:**
+
+```json
+[
+  {
+    "id": "deploy_abc123",
+    "status": "active",
+    "createdAt": "2026-02-25T14:00:00Z",
+    "resources": 4
+  },
+  {
+    "id": "deploy_abc122",
+    "status": "stopped",
+    "createdAt": "2026-02-24T09:30:00Z",
+    "resources": 3
+  }
+]
+```
+
+### GET /api/external/deployments/:id
+
+Get a single deployment by ID.
+
+**Response shape:** Same as a single item from `GET /deployments`.
+
+---
+
+## CLI Execution Commands
+
+The SDK CLI wraps all execution endpoints. Use these commands instead of calling the API directly during development:
+
+| Command                                                | API call                                     | Purpose                  |
+| ------------------------------------------------------ | -------------------------------------------- | ------------------------ |
+| `elevasis-sdk resources`                               | `GET /api/external/resources`                | List all resources       |
+| `elevasis-sdk describe <resource>`                   | `GET /api/external/resources/:id/definition` | Show resource definition |
+| `elevasis-sdk exec <resource> --input '...'`         | `POST /api/external/execute`                 | Execute synchronously    |
+| `elevasis-sdk exec <resource> --input '...' --async` | `POST /api/external/execute-async`           | Execute asynchronously   |
+| `elevasis-sdk executions <resource>`                 | `GET /api/external/executions/:id`           | List execution history   |
+| `elevasis-sdk execution <resource> <id>`           | `GET /api/external/executions/:id/:execId`   | Get execution detail     |
+| `elevasis-sdk deployments`                             | `GET /api/external/deployments`              | List deployments         |
+
+---
+
+**Last Updated:** 2026-02-25