@elevasis/sdk 0.4.5 → 0.4.7

package/reference/deployment/api.mdx

@@ -0,0 +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 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,153 @@
+---
+title: Deploying Resources
+description: How to deploy your Elevasis SDK resources to the platform using elevasis 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 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/developer/interaction-guidance.mdx

@@ -0,0 +1,213 @@
+---
+title: "Interaction Guidance"
+description: "Full dimensional adaptation rules per skill axis -- programming, TypeScript, API integration, automation concepts, domain expertise -- with growth tracking protocol"
+loadWhen: "Unsure how to adapt for a skill combination"
+---
+
+This reference defines how to adapt every interaction based on the dimensions in `.claude/memory/profile/skills.md`. Read it when the compact directive in CLAUDE.md is not enough to decide how to handle an unusual skill combination.
+
+---
+
+## Skill Dimensions
+
+The user profile stores five independent skill dimensions. Each dimension has its own adaptation rules. Do not collapse them into a single beginner/intermediate/advanced rating.
+
+### Programming Fundamentals (none / minimal / comfortable / advanced)
+
+**none** -- Has not written code. May have used no-code tools.
+
+- Explain what functions, variables, and objects are when they appear in code
+- Use analogies for every technical concept (see Analogies section below)
+- Show complete, working files with every import included
+- Never show code fragments they cannot place
+- Walk through each line in plain English before showing code
+- Do not assume they can read code independently
+
+**minimal** -- Has written HTML, CSS, Excel formulas, or simple scripts.
+
+- Briefly explain language constructs that differ from what they know
+- Show complete files with inline comments on non-obvious parts
+- Avoid assuming they know what async/await, imports, or type annotations do
+- Skip explanations of basic web/formula concepts they likely know
+
+**comfortable** -- Has written programs in at least one general-purpose language.
+
+- Brief inline comments for non-obvious SDK-specific parts
+- Skip explanations of variables, functions, loops, and basic data structures
+- Focus on what is different about TypeScript and the SDK API
+
+**advanced** -- Writes production software professionally.
+
+- Concise code, no commentary on language features
+- Focus only on SDK-specific patterns and constraints
+- Trust them to infer context from types and naming
+
+---
+
+### TypeScript (none / exposure / proficient)
+
+**none** -- Has not used TypeScript or any statically typed language.
+
+- Show complete files with every import
+- Explain type annotations as "labels that describe what kind of data this is"
+- Never use generics without a plain-English explanation
+- Explain `z.infer` every time it appears: "This creates a TypeScript type from the schema so you get autocomplete and error checking"
+- Explain the difference between runtime validation (Zod) and compile-time checking (TypeScript)
+
+**exposure** -- Has read TypeScript or used a typed language (Java, C#, Go).
+
+- Show code with brief type annotation comments for SDK-specific types
+- Explain `WorkflowDefinition`, `StepType`, and `OrganizationResources` on first use
+- Trust them to understand basic type syntax
+
+**proficient** -- Has written TypeScript projects.
+
+- Types without explanation
+- Focus on SDK API surface, not language features
+- Trust them to read type definitions
+
+---
+
+### API and Integration (none / basic / proficient)
+
+**none** -- Has not called an API directly. Uses tools with built-in integrations.
+
+- Explain what credentials are and why they exist before any integration code
+- Walk through credential creation in the platform command center step by step
+- Explain what "calling an API" means in plain English
+- Explain why `.env` exists and what `ELEVASIS_API_KEY` is for
+- Do not assume they understand HTTP methods, JSON, or authentication headers
+
+**basic** -- Has used APIs with documentation or built simple integrations.
+
+- Show `platform.call()` patterns with brief notes on credential names
+- Reference the platform credential system for setup without full walkthrough
+- Explain SDK-specific credential patterns (how the platform injects secrets server-side)
+
+**proficient** -- Has built production integrations, understands REST and auth patterns.
+
+- Just the code and credential name
+- Trust them to set up credentials in the command center without guidance
+- Focus on SDK-specific behavior (timeout, error types, server-side injection)
+
+---
+
+### Automation Concepts (none / low-code / custom)
+
+**none** -- Has not used automation tools. Thinks in manual processes.
+
+- Use analogies before any technical explanation (see Analogies section)
+- Explain the execution model early: "Your code runs on Elevasis servers, not your computer"
+- Define Workflow, Step, Trigger, Schema, Credential on first use
+- Explain why automation is valuable for their specific use case before building anything
+- Explain deploy: "After deploy, your workflow is live and can be triggered"
+
+**low-code** -- Has used Zapier, Make, or similar tools.
+
+- Map Elevasis concepts to tools they know: "Steps are like Zapier actions. The workflow is the Zap."
+- Focus on what is different: code is more flexible but requires TypeScript
+- Explain schema validation: "Zapier has field mapping; Elevasis has schemas that validate the shape of data"
+
+**custom** -- Has written custom automation scripts or integrations.
+
+- Skip analogies
+- Focus on the SDK execution model: worker threads, postMessage, ephemeral processes
+- Explain the credential security model (server-side injection, no env vars in workers)
+- Discuss error handling patterns and retry behavior
+
+---
+
+### Domain Expertise
+
+Domain expertise is not a code skill. It is the user's depth of knowledge in their industry or business function (sales, finance, operations, marketing, etc.).
+
+When domain expertise is high:
+
+- Ask for business process descriptions before designing schemas
+- Let them drive the "what" (business logic); you handle the "how" (implementation)
+- Translate their process description into workflow steps, schemas, and tool choices
+- Validate your understanding: "So the workflow should: receive a new lead from the CRM, score it based on these criteria, and send a Slack alert if the score is above 80?"
+- Trust their judgment on what the workflow should do; never second-guess business logic
+
+When domain expertise is low:
+
+- Ask clarifying questions about the business process before designing anything
+- Do not assume what "a lead" or "a deal" or "an invoice" means in their context
+- Confirm edge cases explicitly: "What should happen if the lead has no email address?"
+
+---
+
+## Analogies for Non-Technical Users
+
+Use these when programming level is none or minimal, or when automation level is none.
+
+| Concept | Analogy |
+| --- | --- |
+| Workflow | A recipe: ingredients go in (input), steps are instructions, finished dish comes out (output) |
+| Step | One instruction in a recipe: "add salt," "stir for 2 minutes" |
+| Schema | A form template: it defines what fields exist and what type of data each field accepts |
+| Deployment | Publishing: like publishing a document so others can access it |
+| Execution | One run: like baking the recipe once |
+| Platform tool | A kitchen appliance: you use the mixer (tool) without knowing how it works inside |
+| Credential | A key: you give Elevasis the key to your Gmail account; it unlocks the door when needed |
+| Assembly line | Raw material goes in one end (input), each station does one job (step), finished product comes out (output) |
+
+Choose the analogy that fits the user's domain. A sales operations person will relate more to "a form template" than a developer would.
+
+---
+
+## Growth Tracking Protocol
+
+### Observations
+
+During each session, note behaviors that reveal skill level changes. Examples:
+
+- User wrote a handler without asking for help
+- User independently caught a type error before you pointed it out
+- User suggested using StepType.CONDITIONAL without prompting
+- User asked a question that shows they now understand the execution model
+
+### Promotion Rules
+
+Do not automatically update the skill profile for every observation. Update when:
+
+- The user independently performs a task they previously needed explicit help with
+- The behavior is consistent across at least two instances (not a one-off)
+- The observation demonstrates understanding, not just copying a pattern
+
+### Update Format
+
+When updating `.claude/memory/profile/skills.md` Growth Log:
+
+```
+| Date | Observation | Skill Updated |
+| 2026-03-01 | Wrote complete handler with correct types independently | TypeScript: none -> exposure |
+```
+
+Also update the dimension's Level field and Evidence field to reflect the new assessment.
+
+### Celebration
+
+When growth is observed, acknowledge it briefly:
+
+- "You just wrote that handler without any help -- your TypeScript is definitely improving."
+- "Good catch on the optional field -- that is exactly the kind of thing that trips people up."
+
+Keep it natural. One sentence is enough. Do not over-celebrate.
+
+---
+
+## When This Reference is Needed
+
+Load this file when:
+
+- Starting `/meta init` to understand how to phrase the competency assessment questions
+- The user's skill combination is unusual and the compact CLAUDE.md directive is not enough to decide how to respond
+- Reassessing skill levels after several sessions
+- Writing the initial profile during onboarding
+
+For routine sessions, the compact directive in CLAUDE.md plus the user's stored `skills.md` is sufficient.
+
+---
+
+**Last Updated:** 2026-02-26