@elevasis/sdk 0.5.12 → 0.5.14

package/reference/deployment/command-center-ui.mdx

@@ -1,151 +0,0 @@
----
-title: Command Center UI
-description: Reference for the Elevasis Command Center -- what each page does, when to use it post-deployment, and how SDK concepts map to UI actions
-loadWhen: "User asks about the Command Center UI, post-deployment workflow, or monitoring deployed resources"
----
-
-The Command Center is the browser UI for interacting with deployed resources. After you run `elevasis-sdk deploy`, this is where you run workflows, monitor executions, manage approvals, schedule tasks, and review logs. This reference covers each page and how it connects to your SDK code.
-
----
-
-## Quick Reference
-
-| Task                                               | Page           | Path                    |
-| -------------------------------------------------- | -------------- | ----------------------- |
-| Browse deployed resources, view the resource graph | Command View   | `/command-view`         |
-| Approve or reject pending HITL requests            | Command Queue  | `/queue`                |
-| Browse deployed documentation                      | Knowledge Base | `/knowledge-base`       |
-| Search execution history across all resources      | Execution Logs | `/logs`                 |
-| Create API key and OAuth credentials               | Credentials    | `/settings/credentials` |
-| View deployment history and active version         | Deployments    | `/settings/deployments` |
-
----
-
-## Command View
-
-The Command View is a visual graph of your deployed resources. Each node is a resource (workflow, agent, trigger, integration). Edges are the relationships you declared in `OrganizationResources`.
-
-**What you can do here:**
-
-- See all deployed resources at a glance
-- Trace data flow between resources via declared relationships
-- Identify which resources depend on which integrations
-- Click a node to view resource details (ID, status, type)
-
-**Graph accuracy:** The graph reflects your `relationships` declarations, not runtime behavior. If your handler calls another resource without a declared relationship, the edge is missing from the graph. Keep declarations in sync with your code.
-
-For the full relationship model and what is enforced vs. decorative, see `reference/deployment/command-view.mdx`.
-
-> **SDK takeaway:** Declare relationships in `OrganizationResources` to keep the Command View accurate as your system grows.
-
----
-
-## Command Queue
-
-The Command Queue surfaces all pending Human-in-the-Loop (HITL) approval requests from running workflows.
-
-**What you can do here:**
-
-- View pending approval requests with context provided by the workflow
-- Filter by resource, status, or date
-- Approve or reject with an optional comment
-- See the history of past decisions
-
-**How it connects to your code:** Approval requests appear here when a workflow step calls `approval.requestApproval()`. The workflow pauses at that step and waits for a decision before continuing.
-
-```typescript
-import { approval } from '@elevasis/sdk/worker'
-
-const result = await approval.requestApproval({
-  title: 'Approve proposal before sending',
-  context: { dealId, proposalUrl },
-})
-
-if (result.approved) {
-  // continue
-}
-```
-
-> **SDK takeaway:** Use `approval.requestApproval()` to create approval gates that surface here. Provide rich `context` so reviewers have what they need to decide.
-
----
-
-## Knowledge Base
-
-The Knowledge Base renders the `docs/` directory of your deployed workspace as browsable documentation.
-
-**What you can do here:**
-
-- Browse pages you created in `docs/*.mdx`
-- Search across all documentation
-- Share links to specific pages with team members
-
-**How it connects to your code:** Every `.mdx` file in your workspace's `docs/` directory is bundled at deploy time and rendered here. Pages appear in the order defined by their `order` frontmatter field.
-
-> **SDK takeaway:** Write `docs/*.mdx` pages for your team -- business process docs, schema references, usage guides. They appear here automatically after each deploy.
-
----
-
-## Execution Logs
-
-The Execution Logs page shows the history of all executions across every deployed resource.
-
-**What you can do here:**
-
-- Search and filter by resource, status (completed/failed/running), date range
-- Click any execution to view full detail: input, output, step-level trace, duration
-- Identify failed executions and see error messages with stack traces
-- Navigate from a log entry directly to the resource in Command View
-
-**Filtering tips:**
-
-- Filter by resource name to debug a specific workflow
-- Filter by `failed` status to triage production issues
-- Use date range to narrow down incidents
-
-> **SDK takeaway:** Every `elevasis-sdk exec` and every scheduled run appears here. Use this page to verify behavior after deploy and to diagnose failures before opening code.
-
----
-
-## Credentials
-
-The Credentials page manages encrypted API keys and OAuth tokens used by your workflows at runtime.
-
-**What you can do here:**
-
-- Create API key and webhook-secret credentials via a form
-- Connect OAuth providers (Notion, Google Sheets, Dropbox) via browser flow
-- View existing credentials (values are never shown after creation)
-- Delete credentials that are no longer needed
-
-**Two credential types:**
-
-| Type                     | Created via                                  | Notes                                                  |
-| ------------------------ | -------------------------------------------- | ------------------------------------------------------ |
-| API key / webhook secret | CLI (`elevasis-sdk creds create`) or UI form | Either method works                                    |
-| OAuth                    | UI only                                      | Requires browser redirect -- cannot be created via CLI |
-
-**OAuth credentials require the UI.** When a workflow uses an OAuth-connected service, the user must complete the OAuth flow here first. The CLI `creds` skill handles API keys; redirect OAuth credential setup to this page.
-
-> **SDK takeaway:** Reference credentials in your code by name (`credential: 'my-cred-name'`). Create API keys via CLI or UI; OAuth credentials require this page.
-
----
-
-## Deployments
-
-The Deployments page shows the history of all deployments for your organization.
-
-**What you can do here:**
-
-- View a chronological list of past deployments
-- See which resources changed in each deployment
-- Identify the currently active version
-- Compare resource counts across deployments
-
-**How it connects to your code:** Each `elevasis-sdk deploy` run creates a new deployment entry. The platform activates the new version atomically -- in-flight executions complete against the previous version while new executions start against the new one.
-
-> **SDK takeaway:** Check this page after `elevasis-sdk deploy` to confirm your resources are active. If something behaves unexpectedly, look here to confirm the latest version is live.
-
----
-
-**Last Updated:** 2026-03-03

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