@elevasis/sdk 0.5.12 → 0.5.13

package/reference/deployment/command-view.mdx

@@ -1,154 +0,0 @@
----
-title: Command View
-description: How the Command View graph works -- node types, relationships, what is enforced vs decorative, and what the platform needs to render your resource graph
-loadWhen: "Deploying resources or building resources that invoke other resources"
----
-
-The Command View is a visual graph in the Elevasis command center that shows how your organization's resources connect. Nodes are resources (workflows, agents, integrations). Edges are relationships you declare between them. The graph helps operators understand how automation flows through the system at a glance.
-
----
-
-## Node Types
-
-Every resource you deploy becomes a node in the Command View. Some nodes are executable (the platform runs them); others are visual-only (they exist for the graph but have no runtime behavior).
-
-### Executable Nodes
-
-| Type | What It Does | Deployed By |
-| ---- | ------------ | ----------- |
-| Workflow | Runs step handlers in sequence or branching paths | `elevasis-sdk deploy` |
-| Agent | Autonomous LLM-powered resource with tools | `elevasis-sdk deploy` |
-
-### Visual-Only Nodes
-
-These exist solely for the Command View graph. They have no runtime behavior -- the platform does not execute them.
-
-| Type | What It Represents | Why It Exists |
-| ---- | ------------------ | ------------- |
-| Trigger | A webhook or schedule that starts a workflow | Shows how executions begin |
-| Integration | A credential reference (provider + credential name) | Shows which external services a resource uses |
-| External Resource | A third-party automation (n8n, Make, Zapier) | Documents automations outside the platform |
-| Human Checkpoint | A point where a human makes a decision | Shows where HITL approval gates exist |
-
-Visual-only nodes are declarations. A `TriggerDefinition` does not set up actual trigger routing -- the webhook gateway routes independently. An `IntegrationDefinition` does not configure or connect to anything -- it is a visual node referencing a credential.
-
----
-
-## Relationships
-
-Relationships are edges in the Command View graph. You declare them in `OrganizationResources` to tell the platform how resources connect.
-
-### Declaring Relationships
-
-```typescript
-const org: OrganizationResources = {
-  workflows: {
-    'score-lead': scoreLeadWorkflow,
-    'send-proposal': sendProposalWorkflow,
-  },
-  agents: {
-    'research-agent': researchAgent,
-  },
-  relationships: {
-    'score-lead': {
-      triggers: {
-        workflows: ['send-proposal'],  // score-lead triggers send-proposal
-        agents: ['research-agent'],     // score-lead triggers research-agent
-      },
-      uses: {
-        integrations: ['attio-integration'],  // score-lead uses Attio
-      },
-    },
-  },
-};
-```
-
-### Relationship Fields
-
-| Field | Type | Meaning |
-| ----- | ---- | ------- |
-| `triggers.workflows` | `string[]` | Workflows this resource starts |
-| `triggers.agents` | `string[]` | Agents this resource starts |
-| `uses.integrations` | `string[]` | Integrations this resource depends on |
-
-All referenced IDs must exist in the same organization. Missing targets cause a validation error at deploy time.
-
-### Relationships Are Declarations, Not Routing
-
-Relationships tell the Command View what edges to draw. They do **not** create execution paths. If you declare that workflow A triggers workflow B, the platform does not automatically route A's output to B. Your handler code must explicitly invoke B using the `execution` adapter or `platform.call()`.
-
-This means the graph can drift from reality:
-
-- If your code invokes resource B but you forgot to declare the relationship, the edge is **missing** from the graph
-- If you declared a relationship to resource B but your code never invokes it, the edge is **stale** in the graph
-
----
-
-## What Is Enforced vs Decorative
-
-| Category | Validated at Deploy | Matches Runtime | Status |
-| -------- | ------------------- | --------------- | ------ |
-| Resource IDs unique | Yes | Yes | **Enforced** |
-| Input schema matches execution interface | Yes | Yes | **Enforced** |
-| Relationship targets exist | Yes | No -- invocations are hardcoded strings in handlers | **Decorative** |
-| Trigger routing | No | No -- webhook handlers route independently | **Decorative** |
-| Tool availability per agent | No | No -- tools built dynamically at runtime | **Decorative** |
-| Model config | Yes (provider + model valid) | No -- runtime uses environment config | **Decorative** |
-| Integration usage | Partial (IDs checked) | No -- credentials resolved at runtime | **Decorative** |
-
-**Enforced** means the platform rejects invalid state. **Decorative** means the platform trusts your declaration but does not verify it matches what the code actually does.
-
-### What This Means for You
-
-- Keep relationships in sync with your handler code. When you add an `execution.trigger('other-resource')` call, add the corresponding relationship declaration.
-- When you remove an invocation, remove the relationship.
-- The Command View is only as accurate as your declarations.
-
----
-
-## Deploy-Time Validation
-
-When you run `elevasis-sdk deploy` or `elevasis-sdk check`, the SDK validates your resource definitions locally using the same `ResourceRegistry` the platform uses.
-
-### What Gets Checked
-
-- **Duplicate resource IDs** -- two resources with the same key in `workflows` or `agents`
-- **Relationship targets exist** -- every ID in `triggers` and `uses` must match a resource or integration in the same `OrganizationResources`
-- **Model configuration** -- agent model params (provider, model name, temperature bounds) are valid
-- **Step chains** -- `next.target` values in multi-step workflows point to existing step names
-
-### What Does Not Get Checked
-
-- Whether your handler code actually invokes the resources you declared in relationships
-- Whether your handler code invokes resources you did **not** declare in relationships
-- Whether triggers route to the workflows you declared
-- Whether agents use the tools you expect
-
-These are the decorative gaps listed above. The graph is a best-effort representation that depends on you keeping declarations in sync with code.
-
-### Validation Error Examples
-
-```
-ERROR  Relationship target 'send-proposal' not found in organization resources
-  Resource: score-lead
-  Field: relationships.triggers.workflows
-
-ERROR  Duplicate resource ID 'score-lead' in organization
-```
-
-Fix relationship errors by checking that the target resource ID is spelled correctly and exists in your `OrganizationResources` export. If the resource was renamed or removed, update the relationship to match.
-
----
-
-## Graph Serialization
-
-The platform converts your resource definitions and relationships into a visual graph using two data structures:
-
-- **`CommandViewNode`** -- one per resource (workflow, agent, trigger, integration, etc.). Contains the resource ID, type, name, status, and metadata.
-- **`CommandViewEdge`** -- one per relationship. Contains source node, target node, and edge type (triggers, uses).
-
-The `buildEdges()` function in the platform registry reads your `relationships` declarations and produces `CommandViewEdge[]`. This is a pure transformation -- it does not add or remove edges based on runtime behavior.
-
----
-
-**Last Updated:** 2026-03-02

package/reference/framework/documentation.mdx

@@ -1,92 +0,0 @@
----
-title: Resource Documentation
-description: Write and deploy MDX documentation alongside your Elevasis resources
-loadWhen: "Writing or updating project documentation"
----
-
-`elevasis-sdk 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-sdk 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-sdk 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-sdk check    # Validate resources
-elevasis-sdk deploy   # Deploy to platform
-elevasis-sdk exec <resourceId> --input '{"key": "value"}'
-\`\`\`
-```
-
-## Deploy Behavior
-
-When you run `elevasis-sdk 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/platform-tools/examples.mdx

@@ -1,170 +0,0 @@
----
-title: Integration Examples
-description: Working code examples for email, CRM, PDF, LLM inference, resource triggering, and storage using typed adapters and platform.call()
-loadWhen: "Implementing a platform tool call in a workflow step"
----
-
-Working code examples for common tool integrations. All tools shown here have [typed adapters](adapters.mdx) that provide full autocomplete and compile-time checking -- prefer adapters in new code. The `platform.call()` patterns below are kept as reference and for tools without adapters yet (supabase).
-
-## Sending Email via Resend
-
-Send a transactional email through your Resend account. Store your Resend API key as a credential named `resend` using the [Elevasis CLI](../cli/index.mdx).
-
-```typescript
-import { createResendAdapter } from '@elevasis/sdk/worker'
-
-const resend = createResendAdapter('resend')
-const result = await resend.sendEmail({
-  from: 'hello@yourapp.com',
-  to: 'customer@example.com',
-  subject: 'Your order is confirmed',
-  html: '\<p\>Thank you for your order!\</p\>',
-})
-```
-
-The `credential` value must match the name you used when storing the API key. Resend supports `{ apiKey }` as its credential shape.
-
-## Creating a CRM Record via Attio
-
-Create a contact or company record in Attio. Store your Attio API key as a credential named `attio`.
-
-```typescript
-import { createAttioAdapter } from '@elevasis/sdk/worker'
-
-const attio = createAttioAdapter('attio')
-const result = await attio.createRecord({
-  object: 'people',
-  values: {
-    name: [{ full_name: 'Jane Smith' }],
-    email_addresses: [{ email_address: 'jane@example.com' }],
-  },
-})
-
-const recordId = result.data.id
-```
-
-Attio exposes 12 methods covering CRUD operations, schema inspection, and notes. See the [typed adapter reference](adapters.mdx#attio-crm-adapter) for the full method list.
-
-## Generating a PDF
-
-Render a PDF from a document structure or template. No credential required -- PDF generation is a built-in platform service.
-
-```typescript
-import { pdf, storage } from '@elevasis/sdk/worker'
-
-// Render to storage directly
-const result = await pdf.render({
-  document: proposalDocument,
-  storage: { bucket: 'invoices', path: 'invoice-1042.pdf' },
-})
-console.log(result.pdfUrl)
-
-// Or render to buffer for inline processing
-const { buffer } = await pdf.renderToBuffer({
-  document: proposalDocument,
-})
-
-// Then upload manually if needed
-await storage.upload({
-  bucket: 'invoices',
-  path: 'invoice-1042.pdf',
-  content: buffer,
-  contentType: 'application/pdf',
-})
-```
-
-## Making an LLM Call with Structured Output
-
-Use the `llm` adapter to call any supported model with a JSON Schema for structured output. No API keys are needed in your code -- keys are resolved server-side.
-
-```typescript
-import { llm } from '@elevasis/sdk/worker'
-
-interface TicketClassification {
-  priority: 'low' | 'medium' | 'high' | 'critical'
-  category: 'billing' | 'technical' | 'account' | 'other'
-  sentiment: 'positive' | 'neutral' | 'negative'
-  summary: string
-}
-
-const response = await llm.generate\<TicketClassification\>({
-  provider: 'anthropic',
-  model: 'claude-sonnet-4-5',
-  messages: [
-    { role: 'system', content: 'You extract structured data from support tickets.' },
-    { role: 'user', content: ticketText },
-  ],
-  responseSchema: {
-    type: 'object',
-    properties: {
-      priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-      category: { type: 'string', enum: ['billing', 'technical', 'account', 'other'] },
-      sentiment: { type: 'string', enum: ['positive', 'neutral', 'negative'] },
-      summary: { type: 'string' },
-    },
-    required: ['priority', 'category', 'sentiment', 'summary'],
-  },
-  temperature: 0.1,
-})
-
-// response.output is typed as TicketClassification
-const { priority, category, summary } = response.output
-```
-
-Supported providers: `google`, `openai`, `anthropic`, `openrouter`. See [Platform Tools](index.mdx) for the full model list.
-
-## Triggering Another Resource
-
-Trigger a separate workflow or agent as a nested child execution. The call is synchronous -- your workflow waits for the child to complete and receives its output.
-
-```typescript
-import { execution } from '@elevasis/sdk/worker'
-
-const outcome = await execution.trigger({
-  resourceId: 'send-welcome-sequence',
-  input: {
-    userId: newUser.id,
-    email: newUser.email,
-    plan: 'pro',
-  },
-})
-
-if (!outcome.success) {
-  throw new Error(`Child workflow failed: ${outcome.error}`)
-}
-
-// outcome = { success: true, executionId: '...', output: { emailsSent: 3 }, error: undefined }
-```
-
-Nested executions are tracked with depth up to a maximum of 5 levels. Both the calling workflow and the child must belong to the same organization.
-
-## Uploading to Storage
-
-Upload a file to Elevasis-managed storage and generate a signed URL for temporary access. No credential required.
-
-```typescript
-import { storage } from '@elevasis/sdk/worker'
-
-// Upload a processed file
-const reportPath = `exports/report-${Date.now()}.csv`
-await storage.upload({
-  bucket: 'exports',
-  path: reportPath,
-  content: csvContent,
-  contentType: 'text/csv',
-})
-
-// Generate a signed URL valid for 1 hour (3600 seconds)
-const { signedUrl } = await storage.createSignedUrl({
-  bucket: 'exports',
-  path: reportPath,
-})
-
-// Share signedUrl with the user or include in an email
-```
-
-Storage also supports `download`, `delete`, and `list` operations. Use `list` to enumerate files under a path prefix.
-
----
-
-**Last Updated:** 2026-03-02

package/reference/runtime/limits.mdx

@@ -1,75 +0,0 @@
----
-title: Resource Limits & Quotas
-description: Memory limits, execution timeouts, scale quotas, networking constraints, and v1 platform limitations for SDK resources
-loadWhen: "Hitting resource limits or planning for scale"
----
-
-This page documents the hard limits enforced on all SDK resources running on the Elevasis platform. These limits exist to ensure platform stability and fair resource usage across all organizations.
-
----
-
-## Resource Limits
-
-Limits enforced per worker thread at runtime:
-
-| Resource | Value |
-| -------- | ----- |
-| Memory (V8 heap) | 256MB per worker |
-| Disk | Bundle file only (ephemeral, not persistent across deploys) |
-
-- **Memory:** Enforced by the platform. Exceeding 256MB crashes the worker. The platform catches the error; other tenants are unaffected. If your workflow processes large datasets, consider streaming or batching to stay within the limit.
-- **Disk:** Your bundle is written to disk during deploy and available to the worker at execution time. It is not a persistent write surface -- do not write files to disk from within your handler expecting them to persist.
-
----
-
-## Scale Limits & Quotas
-
-Hard limits to prevent abuse and ensure platform stability:
-
-| Limit | Value |
-| ----- | ----- |
-| Max execution duration (workflows) | 300s (5 min) |
-| Max execution duration (agents) | 600s (10 min) |
-| Max log volume | 100MB/day |
-| Max deploy frequency | 60/day |
-
-- **Execution duration:** Executions exceeding the timeout are terminated by the platform. The execution is marked failed with a timeout reason.
-- **Log volume:** Total log output across all executions is capped at 100MB per day. Logs beyond this threshold may be truncated.
-- **Deploy frequency:** 60 deploys per day is generous for normal development. This limit prevents accidental deploy loops (for example, a CI pipeline misconfigured to deploy on every commit).
-
----
-
-## Networking
-
-- **Outbound:** Unrestricted. Your handlers can call any external API (OpenAI, Twilio, Stripe, etc.) from within the worker.
-- **Inbound:** Workers receive input from the platform coordinator via internal message passing -- they are not exposed to the network directly.
-- **No ports:** Workers communicate with the platform via zero-network-overhead message passing. No port allocation occurs.
-- **Isolation:** Workers have no access to other organizations' data or platform credentials by default. Supabase credentials are not present in the worker environment.
-
----
-
-## Platform Maintenance
-
-- **Rolling updates:** Platform upgrades re-register all active deployments on startup. No executions are lost.
-- **Node.js updates:** When the server's Node.js version is updated, worker threads pick up the new version on the next execution with no action required from you.
-- **Advance notice:** 24-hour advance notice is provided for breaking maintenance windows. These are rare and reserved for major infrastructure changes.
-
----
-
-## v1 Limitations
-
-| Limitation | Reason | Future path |
-| ---------- | ------ | ----------- |
-| **No nested execution from external resources** | External resources cannot call back to the platform's execution coordinator to trigger other resources as sub-executions. | A callback API endpoint that external processes can call to trigger nested executions (requires auth token forwarding). |
-| **No streaming logs** | Execution logs are returned in the response body after completion. There is no real-time SSE streaming from within the worker. | SSE/WebSocket push from external processes to the platform log system. |
-| **Static resource priority conflicts** | If your organization has a static (monorepo) resource with the same ID as a resource in your SDK bundle, the deploy will fail. Static definitions always take priority and cannot be overridden. | Conflict detection is surfaced in the CLI with a clear error message. |
-
----
-
-## Organization Provisioning
-
-Organization creation is currently admin-only. If you need a new organization provisioned for SDK access, contact the Elevasis team. Self-serve organization creation and API key generation is on the roadmap.
-
----
-
-**Last Updated:** 2026-03-03

package/reference/security/credentials.mdx

@@ -1,141 +0,0 @@
----
-title: "Credential Security"
-description: "Three-layer credential model: platform tools (server-side injection), http tool (arbitrary APIs), getCredential() (explicit opt-in raw access) -- .env scope and security boundaries"
-loadWhen: "Setting up integrations or configuring tool access"
----
-
-This reference covers the Elevasis credential security model. Read it when helping a user connect to an external service, set up platform tools, or understand why environment variables are not used in workflows.
-
----
-
-## The Core Rule
-
-Integration credentials are never stored in `.env` and never available via `process.env` inside worker threads.
-
-Credentials live in the platform credential system, created via the command center UI. Worker threads access credentials only through controlled channels: `platform.call()` (server-side injection) or `platform.getCredential()` (explicit opt-in).
-
-`.env` contains only `ELEVASIS_API_KEY`, used by the CLI for authentication. It is never uploaded to the platform and never injected into workers.
-
----
-
-## Three-Layer Model
-
-### Layer 1: Platform Tools (Default)
-
-All platform tools resolve credentials server-side. The tool dispatcher in the API process looks up the credential by name, injects it into the service call, and returns only the result. Credential values never cross the postMessage boundary into the worker.
-
-```typescript
-// Credential 'my-gmail' is resolved server-side -- value never enters worker memory
-const result = await platform.call({
-  tool: 'gmail',
-  method: 'sendEmail',
-  credential: 'my-gmail',
-  params: { to: '...', subject: '...', body: '...' },
-})
-```
-
-This is the default pattern for all integrations that have a platform adapter (Gmail, Attio, Stripe, Resend, etc.).
-
-### Layer 2: HTTP Platform Tool
-
-For APIs without a dedicated platform adapter, use the `http` platform tool. Credentials are resolved and injected server-side before the outgoing HTTP request.
-
-```typescript
-const result = await platform.call({
-  tool: 'http',
-  method: 'request',
-  credential: 'my-custom-api',
-  params: {
-    url: 'https://api.example.com/v1/data',
-    method: 'GET',
-    headers: { 'Content-Type': 'application/json' },
-  },
-})
-// result = { status: 200, headers: {...}, body: {...} }
-```
-
-**Supported credential injection patterns:**
-
-| Pattern | Credential Config | How Injected |
-| --- | --- | --- |
-| Bearer token | `{ type: 'bearer', token: 'sk_...' }` | `Authorization: Bearer sk_...` header |
-| API key header | `{ type: 'api-key-header', header: 'X-API-Key', key: 'ak_...' }` | Custom header with key value |
-| Basic auth | `{ type: 'basic', username: '...', password: '...' }` | `Authorization: Basic base64(user:pass)` header |
-| Query parameter | `{ type: 'query-param', param: 'api_key', value: 'ak_...' }` | Appended to URL query string |
-| Body field | `{ type: 'body-field', field: 'apiKey', value: 'ak_...' }` | Merged into JSON request body |
-| Custom header | `{ type: 'custom-header', header: 'X-Custom', value: '...' }` | Arbitrary header with value |
-
-The credential type is selected when creating the credential in the command center UI.
-
-### Layer 3: getCredential() (Explicit Opt-In)
-
-For cases where a third-party SDK must be initialized with a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This is an explicit opt-in that causes the credential value to enter worker memory.
-
-```typescript
-import { platform } from '@elevasis/sdk/worker'
-
-// Explicit opt-in -- secret enters worker memory for duration of execution
-const cred = await platform.getCredential('my-stripe-key')
-const stripe = new Stripe(cred.credentials.secretKey)
-```
-
-`getCredential()` returns `{ provider: string, credentials: Record<string, string> }`. The fields in `credentials` depend on the credential type stored in the command center.
-
-**Security guardrails:**
-
-- All `getCredential()` calls are logged with credential name, deployment ID, and execution ID
-- Workers are ephemeral (destroyed after each execution) -- no credential persistence
-- Use `platform.call()` with the `http` tool instead when possible
-
----
-
-## Credential Setup
-
-Credentials are created in the command center UI:
-
-1. Open the Elevasis command center
-2. Navigate to Credentials
-3. Click "Add Credential"
-4. Enter a name (e.g., `my-gmail`, `production-attio`, `custom-api`)
-5. Select the credential type (bearer, api-key-header, basic, etc.)
-6. Enter the secret values
-7. Save
-
-The credential name is what you pass as `credential: 'my-gmail'` in `platform.call()`.
-
-Credential names are case-sensitive. A mismatch causes a `PlatformToolError` with the message "credential not found."
-
----
-
-## .env Scope
-
-`.env` in your workspace contains only:
-
-```
-ELEVASIS_API_KEY=sk_your_key_here
-```
-
-This key authenticates CLI operations (`elevasis-sdk deploy`, `elevasis-sdk check`, `elevasis-sdk exec`). It is never uploaded to the platform and never injected into workers.
-
-Do not put integration API keys in `.env`. They will not be available inside workflows.
-
----
-
-## Choosing a Credential Pattern
-
-| Situation | Pattern |
-| --- | --- |
-| Using a supported platform tool (Gmail, Attio, Stripe, etc.) | `platform.call()` with the tool name |
-| Calling an API not in the tool catalog | `platform.call()` with `tool: 'http'` |
-| Third-party SDK that requires a raw key | `platform.getCredential()` |
-| CLI authentication | `ELEVASIS_API_KEY` in `.env` only |
-
----
-
-## Migrating from elevasis-sdk env
-
-If you previously set integration credentials via `elevasis-sdk env set`, that command no longer exists. Use `elevasis-sdk env list` to see what was set, then recreate each entry as a platform credential in the command center. Update workflow code from `process.env.KEY` to `platform.call({ tool: 'http', credential: '...', ... })` or `platform.getCredential('...')`, then redeploy. The `.env` file remains but is scoped to `ELEVASIS_API_KEY` only.
-
----
-
-**Last Updated:** 2026-02-26