@elevasis/sdk 0.5.12 → 0.5.13

package/reference/deployment/index.mdx

@@ -1,153 +1,158 @@
----
-title: Deploying Resources
-description: How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup
-loadWhen: "Preparing to deploy or debugging deploy failures"
----
-
-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-sdk 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-sdk 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-sdk 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-sdk 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-sdk 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-sdk 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
+---
+title: Deploying Resources
+description: How to deploy your Elevasis SDK resources to the platform using elevasis-sdk deploy, including configuration, validation, and environment setup
+loadWhen: "Preparing to deploy or debugging deploy failures"
+---
+
+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-sdk 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-sdk 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-sdk 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-sdk 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-sdk 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-sdk 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.
+
+## Documentation
+
+- [Command Center](command-center.mdx) - Resource graph, relationships, node types, and post-deployment UI reference
+- [Execution API](api.mdx) - REST endpoints for executing resources and managing deployments
+
+---
+
+**Last Updated:** 2026-02-25