@elevasis/sdk 0.4.4 → 0.4.6

package/reference/deployment/api.mdx

@@ -0,0 +1,296 @@
+---
+title: Execution API
+description: REST endpoints for executing resources, querying execution history, and managing deployments via the Elevasis external API
+---
+
+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 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 resources` | `GET /api/external/resources` | List all resources |
+| `elevasis describe <resource>` | `GET /api/external/resources/:id/definition` | Show resource definition |
+| `elevasis exec <resource> --input '...'` | `POST /api/external/execute` | Execute synchronously |
+| `elevasis exec <resource> --input '...' --async` | `POST /api/external/execute-async` | Execute asynchronously |
+| `elevasis executions <resource>` | `GET /api/external/executions/:id` | List execution history |
+| `elevasis execution <resource> <id>` | `GET /api/external/executions/:id/:execId` | Get execution detail |
+| `elevasis deployments` | `GET /api/external/deployments` | List deployments |
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/deployment/index.mdx

@@ -0,0 +1,152 @@
+---
+title: Deploying Resources
+description: How to deploy your Elevasis SDK resources to the platform using elevasis deploy, including configuration, validation, and environment setup
+---
+
+Deploying your resources makes them live on the Elevasis platform and immediately available for execution. The deploy process validates your resource definitions, bundles your code into a single self-contained file, and uploads it to the platform -- no server-side dependency installation required.
+
+---
+
+## How Deployment Works
+
+When you run `elevasis deploy`, the CLI performs these steps in order:
+
+1. **Authenticate** -- calls the API with your `ELEVASIS_API_KEY` to verify credentials and resolve your organization name
+2. **Validate** -- runs your `src/index.ts` through `ResourceRegistry`, catching the same errors as the platform
+3. **Bundle** -- uses esbuild to produce a single self-contained `dist/bundle.js` file (~50-200 KB) containing your code and all dependencies
+4. **Upload** -- sends the bundle and resource metadata to the platform via `POST /api/external/deploy`
+5. **Go live** -- the platform registers your resources; they are immediately available for execution
+
+There is no local dev server and no separate staging environment. Deployed resources run directly on the platform. Local testing uses `tsc --noEmit` and Vitest with direct handler calls.
+
+---
+
+## Running a Deploy
+
+```bash
+elevasis deploy
+```
+
+**Successful deploy output:**
+
+```
+  Authenticating...          done (acme-corp)
+  Validating...              done (4 resources, 0 errors)
+  Bundling...                done (142 KB)
+  Uploading...               done
+
+  Deployed! 4 resources live.
+  Deployment: deploy_abc123
+```
+
+Each deploy creates a new deployment record. The previous active deployment is automatically stopped. You can view all deployments with `elevasis deployments`.
+
+---
+
+## Validation
+
+The CLI validates your resources before bundling. Validation uses the same `ResourceRegistry` as the platform, so errors caught locally are the same errors that would be caught at deploy time.
+
+**Validation checks:**
+
+- Duplicate `resourceId` within your organization
+- Invalid model configuration (temperature and token bounds out of range)
+- `ExecutionInterface` form fields not matching `inputSchema`
+- Broken workflow step chains (`next` referencing a step that does not exist)
+- Relationship declarations referencing resources that do not exist
+
+**Validation failure output:**
+
+```
+  Authenticating...          done (acme-corp)
+  Validating...
+    ERROR  Duplicate resource ID 'onboard-client' in organization 'Acme Corp'
+    ERROR  Workflow step 'send-email' references non-existent next step 'notify'
+
+  2 errors. Deploy aborted.
+```
+
+Run `elevasis check` at any time to validate without deploying.
+
+---
+
+## Configuration
+
+The CLI reads `elevasis.config.ts` from your project root. All fields are optional -- the organization name is resolved from your API key, not from config.
+
+```typescript
+// elevasis.config.ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {} satisfies ElevasConfig
+```
+
+The `ElevasConfig` type is exported from `@elevasis/sdk`. You can leave the config empty or extend it as options are added in future SDK versions.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+| -------- | -------- | ----------- |
+| `ELEVASIS_API_KEY` | Yes | Your `sk_...` API key. Used for authentication and organization resolution. |
+| `ELEVASIS_API_URL` | No | Override the API base URL. Useful for pointing at a staging environment. |
+
+The CLI also accepts a `--api-url` flag on every command, which takes priority over `ELEVASIS_API_URL`.
+
+**API URL resolution order:**
+
+1. `--api-url` flag (highest priority)
+2. `ELEVASIS_API_URL` environment variable
+3. `NODE_ENV`-based default (production: `https://api.elevasis.io`, development: localhost)
+
+**Setting `ELEVASIS_API_KEY` via `.env` file:**
+
+```
+ELEVASIS_API_KEY=sk_***
+```
+
+Place `.env` in your project root. The CLI reads it automatically. Never commit this file.
+
+---
+
+## Deployment Lifecycle
+
+Each call to `elevasis deploy` creates a new deployment. The platform tracks all deployments for your organization.
+
+| Status | Meaning |
+| ------ | ------- |
+| `deploying` | Bundle is being processed and resources are being registered |
+| `active` | Resources are live and available for execution |
+| `stopped` | Superseded by a newer deployment |
+| `failed` | Deploy did not complete (validation or bundle error) |
+
+Only one deployment can be `active` at a time. Deploying again automatically moves the previous active deployment to `stopped`.
+
+**View deployment history:**
+
+```bash
+elevasis deployments
+```
+
+```
+  deploy_abc123   active    2026-02-25 14:00:00   4 resources
+  deploy_abc122   stopped   2026-02-24 09:30:00   3 resources
+  deploy_abc121   stopped   2026-02-23 11:15:00   3 resources
+```
+
+---
+
+## Bundle Details
+
+The deploy bundle is a single CJS file produced by esbuild. It includes:
+
+- Your resource definitions from `src/index.ts`
+- The `@elevasis/sdk/worker` runtime that handles execution messages from the platform
+- All your npm dependencies (fully self-contained, no `node_modules` needed on the server)
+
+The bundle is stored on the platform for durability and restart recovery. If the platform API restarts, it re-downloads your bundle and re-registers your resources automatically -- no action required on your part.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/documentation/index.mdx

@@ -0,0 +1,91 @@
+---
+title: Resource Documentation
+description: Write and deploy MDX documentation alongside your Elevasis resources
+---
+
+`elevasis deploy` ships your code and your documentation atomically -- one command, no version drift. Documentation files live in a `docs/` directory at your project root and render in the Elevasis platform UI for operators using your resources.
+
+## Directory Structure
+
+Create `.mdx` files inside a `docs/` directory at your project root. `elevasis init` scaffolds a starter structure:
+
+```
+my-project/
+├── docs/
+│   └── index.mdx          # Resource overview (scaffolded by init)
+├── src/
+│   └── index.ts            # Resource definitions
+├── elevasis.config.ts
+└── ...
+```
+
+A missing `docs/` directory is silently ignored -- documentation is optional. If the directory exists, its contents are included in the deploy payload alongside resource schemas.
+
+## Frontmatter Schema
+
+Every documentation file supports a frontmatter block at the top:
+
+```yaml
+---
+title: string       # Page title (required)
+description: string # Short description (optional)
+order: number       # Sort order within directory (optional, default: 0)
+---
+```
+
+## Naming Conventions
+
+- `docs/index.mdx` is the root documentation page and is always rendered first
+- Nested directories create sections: `docs/guides/getting-started.mdx`
+- File names become URL slugs: `setup-guide.mdx` renders at `/docs/setup-guide`
+- Arbitrary nesting is supported -- there is no depth limit
+
+## Size Limits
+
+- 100KB per file
+- 1MB total across all files in a deployment
+
+These limits are enforced by the CLI before the deploy request is sent. Validation errors include the file name and size.
+
+## Starter Template
+
+`elevasis init` writes this starter file to `docs/index.mdx`:
+
+```mdx
+---
+title: Overview
+description: Documentation for this Elevasis project
+---
+
+# Overview
+
+Welcome to the documentation for this project.
+
+## Resources
+
+Describe your workflows and agents here. This documentation is deployed alongside your
+code and rendered in the Elevasis platform UI.
+
+## Getting Started
+
+\`\`\`bash
+elevasis check    # Validate resources
+elevasis deploy   # Deploy to platform
+elevasis exec <resourceId> --input '{"key": "value"}'
+\`\`\`
+```
+
+## Deploy Behavior
+
+When you run `elevasis deploy`:
+
+1. The CLI scans `docs/` recursively for `.mdx` files
+2. Each file's frontmatter (title, description, order) is parsed and stripped from the content
+3. Total size is validated against the 1MB limit and individual files against 100KB
+4. The documentation array is included in the deploy metadata alongside your resource schemas
+
+Documentation and code ship in the same transaction. There is no separate upload step and no way for documentation to drift out of sync with the deployed version.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/getting-started/index.mdx

@@ -0,0 +1,124 @@
+---
+title: Getting Started
+description: Install the Elevasis SDK, scaffold a project, and run your first deployment
+---
+
+This guide takes you from a fresh install to a running deployment in four steps: install, scaffold, deploy, and execute.
+
+## Installation
+
+Install the SDK and its peer dependency:
+
+```bash
+npm install @elevasis/sdk zod
+# or
+pnpm add @elevasis/sdk zod
+```
+
+The `.npmrc` file scaffolded by `elevasis init` sets `auto-install-peers = true`, so peer dependencies are handled automatically on subsequent installs.
+
+---
+
+## Scaffold a Project
+
+Run `elevasis init` to create a new project directory with all required files:
+
+```bash
+elevasis init my-project
+cd my-project
+```
+
+The command scaffolds 18 files covering configuration, source, documentation, and Claude Code integration:
+
+```
+my-project/
+├── CLAUDE.md                       # Project instructions for Claude Code
+├── .claude/
+│   ├── settings.json               # autoCompact: false
+│   ├── profile.json                # Created on first session (gitignored)
+│   └── commands/
+│       ├── docs.md                 # Documentation assistant
+│       ├── resource.md             # Resource scaffolding
+│       ├── deploy.md               # Deployment assistant
+│       ├── inspect.md              # Deployment health + execution debugging
+│       └── env.md                  # Platform env var management
+├── src/
+│   └── index.ts                    # Echo workflow starter
+├── docs/
+│   └── index.mdx                   # Starter documentation page
+├── elevasis.config.ts              # Config with commented-out options
+├── package.json                    # check-types + deploy scripts
+├── tsconfig.json                   # TypeScript config (app-focused)
+├── pnpm-workspace.yaml             # Standalone project workspace
+├── .env                            # API key only
+├── .env.example                    # Git-safe template
+├── .npmrc                          # auto-install-peers
+├── .gitignore                      # Excludes worker temp file, claude files
+└── README.md                       # Setup and CLI reference
+```
+
+### Set Up Your API Key
+
+Open `.env` and set your API key:
+
+```
+ELEVASIS_API_KEY=sk_your_key_here
+```
+
+The `.env.example` file provides the same template and is safe to commit. The actual `.env` is gitignored.
+
+**Note:** Do not add `NODE_ENV` to your `.env`. The SDK treats `undefined` as production by default, which means your project connects to the hosted Elevasis API. Adding `NODE_ENV=development` is the most common setup mistake.
+
+---
+
+## First Deployment
+
+Validate your resources and deploy:
+
+```bash
+elevasis check    # Validate resource definitions
+elevasis deploy   # Bundle and deploy to the platform
+```
+
+`elevasis check` runs validation without deploying. Fix any errors it reports before running `elevasis deploy`.
+
+`elevasis deploy` bundles your `src/` code and `docs/` documentation into a single deployment transaction. Both ship atomically -- there is no separate upload step for documentation.
+
+After a successful deploy, confirm the resources are live:
+
+```bash
+elevasis resources       # List deployed resources
+elevasis deployments     # Show deployment history
+```
+
+---
+
+## First Execution
+
+Execute the scaffolded echo workflow to verify end-to-end connectivity:
+
+```bash
+elevasis exec echo-workflow --input '{"message": "hello"}'
+```
+
+View the execution result:
+
+```bash
+elevasis executions echo-workflow    # Execution history
+elevasis execution echo-workflow \<execution-id\>  # Full detail for one execution
+```
+
+Replace `<execution-id>` with the ID returned from the executions list.
+
+---
+
+## Next Steps
+
+- [Project Structure](project-structure.mdx) -- Understand each scaffolded file
+- [Resources](../resources/index.mdx) -- Define workflows and agents
+- [CLI Reference](../cli/index.mdx) -- Full command reference with flags
+- [Deployment](../deployment/index.mdx) -- Deployment lifecycle and environment variables
+
+---
+
+**Last Updated:** 2026-02-25