@elevasis/sdk 0.4.5 → 0.4.7

package/reference/getting-started/index.mdx

@@ -0,0 +1,148 @@
+---
+title: Getting Started
+description: Install the Elevasis SDK, scaffold a project, and run your first deployment
+loadWhen: "Setting up a new project or onboarding"
+---
+
+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 23 files covering configuration, source, documentation, and Claude Code integration:
+
+```
+my-project/
+├── CLAUDE.md                       # Project instructions for Claude Code
+├── .claude/
+│   ├── settings.json               # autoCompact: false
+│   └── commands/
+│       ├── docs.md                 # Documentation lifecycle
+│       ├── resource.md             # Resource scaffolding
+│       ├── meta.md                 # Project lifecycle (init, deploy, health, develop)
+│       ├── help.md                 # Command tree and navigation
+│       ├── database.md             # Database setup and management
+│       ├── agent.md                # Agent development
+│       ├── templates.md            # Workflow templates
+│       ├── tutorial.md             # Progressive learning
+│       └── profile.md              # View and update user profile
+├── src/
+│   ├── index.ts                    # Registry entry point
+│   └── workflows/
+│       └── echo.ts                 # Starter workflow
+├── docs/
+│   ├── index.mdx                   # Starter documentation page
+│   └── in-progress/
+│       └── .gitkeep                # Work-in-progress docs directory
+├── elevasis.config.ts              # Config with templateVersion and 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
+```
+
+The scaffolded `elevasis.config.ts` includes a `templateVersion` field that tracks which template generation your project uses. Leave it as-is -- it is managed automatically by `elevasis update`:
+
+```ts
+import type { ElevasConfig } from '@elevasis/sdk'
+
+export default {
+  templateVersion: 4,
+} satisfies ElevasConfig
+```
+
+### 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.
+
+### Guided Setup with Claude Code
+
+After scaffolding, open the project in Claude Code and run `/meta init`. This command installs dependencies, walks you through `.env` setup, creates your developer profile in `.claude/memory/`, and optionally runs your first deploy -- all in one guided flow.
+
+---
+
+## 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 --input '{"message": "hello"}'
+```
+
+View the execution result:
+
+```bash
+elevasis executions echo    # Execution history
+elevasis execution echo \<execution-id\>  # Full detail for one execution
+```
+
+Replace `<execution-id>` with the ID returned from the executions list.
+
+---
+
+## Next Steps
+
+- **Run `/meta init` in Claude Code** -- Guided setup that installs deps, configures `.env`, and creates your developer profile in `.claude/memory/`
+- [Development Framework](../framework/index.mdx) -- How Claude Code helps you build
+- [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
+
+When a new SDK version is released, run `elevasis update` to bring your project's managed files (CLAUDE.md, slash commands, `.gitignore`) up to date. The command adds missing files and flags any files that differ from the new template for agent-assisted review.
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/index.mdx

@@ -0,0 +1,113 @@
+---
+title: Elevasis SDK
+description: Build and deploy workflows, agents, and resources with the Elevasis SDK
+loadWhen: "First session or new to the SDK"
+---
+
+`@elevasis/sdk` lets you build workflows, agents, and resources in TypeScript and deploy them to the Elevasis platform with a single command. The developer experience is Vercel-style: write TypeScript, validate locally, deploy -- the platform handles execution, tool access, and observability. You never manage infrastructure. Zod 4.1 is the only peer dependency.
+
+## Quick Start
+
+```bash
+npm install @elevasis/sdk
+elevasis init
+elevasis deploy
+```
+
+After `elevasis init`, your project is scaffolded with a working echo workflow, config file, TypeScript setup, and a `CLAUDE.md` that gives Claude Code full awareness of the SDK. After `elevasis deploy`, your resources appear in AI Studio and are available to run immediately.
+
+Here is a minimal workflow definition:
+
+```ts
+import { WorkflowDefinition, OrganizationResources } from '@elevasis/sdk';
+import { z } from 'zod';
+
+const greetInput = z.object({ name: z.string() });
+const greetOutput = z.object({ message: z.string() });
+
+type GreetInput = z.infer<typeof greetInput>;
+type GreetOutput = z.infer<typeof greetOutput>;
+
+const greetWorkflow: WorkflowDefinition = {
+  id: 'greet',
+  name: 'Greet',
+  inputSchema: greetInput,
+  outputSchema: greetOutput,
+  steps: [
+    {
+      id: 'greet-step',
+      name: 'Build greeting',
+      handler: async (input: GreetInput): Promise<GreetOutput> => {
+        return { message: `Hello, ${input.name}!` };
+      },
+      next: null,
+    },
+  ],
+};
+
+export const resources: OrganizationResources = {
+  workflows: [greetWorkflow],
+};
+```
+
+## What You Can Build
+
+- **Workflows** -- Step-based automation with typed inputs and outputs. Steps can be linear, conditional, or branching. Each step is a plain async function. Workflows are the primary resource type and are fully supported.
+- **Agents** -- Autonomous AI resources with access to platform tools. Agent definitions are accepted by the SDK and appear in the registry, but autonomous agent execution (multi-turn tool use loops) is deferred -- see Known Limitations below.
+
+## Platform Tools
+
+Inside any workflow step, import `platform` from `@elevasis/sdk/worker` to call platform tools:
+
+```ts
+import { platform } from '@elevasis/sdk/worker';
+
+const result = await platform.call({
+  tool: 'gmail',
+  method: 'send',
+  params: { to: 'user@example.com', subject: 'Hello', body: 'World' },
+  credential: 'my-gmail-credential',
+});
+```
+
+The platform exposes 70+ tools across 13 integration adapters -- Gmail, Stripe, Google Sheets, Notion, and more. Credentials are managed server-side; API keys never cross the execution boundary. LLM calls are also available via `platform.call({ tool: 'llm', ... })` with API keys resolved from platform environment variables.
+
+See [Platform Tools](platform-tools/index.mdx) for the full catalog.
+
+## Known Limitations
+
+- **Agent execution is deferred** -- The worker runtime returns a failed status for agent resources. LLM calls are available via `platform.call`, but autonomous multi-turn agent loops are not yet supported.
+- **No streaming logs** -- Execution logs are returned in the response body after completion. Real-time log streaming is not available.
+
+## Documentation
+
+### Getting Started
+
+- [Getting Started](getting-started/index.mdx) - Installation, authentication, first workflow, and project structure
+
+### Core Concepts
+
+- [Resources](resources/index.mdx) - Workflow and agent definition patterns, Zod schemas, step types, and routing
+- [Platform Tools](platform-tools/index.mdx) - Full catalog of 70+ tools, integration adapters, and credential management
+- [Security](security/credentials.mdx) - Three-layer credential model, HTTP tool patterns, and credential management
+
+### Reference
+
+- [Concepts](concepts/index.mdx) - Plain-English concept explanations, glossary, Zod guide, execution model, and common errors
+- [Templates](templates/index.mdx) - 7 workflow templates: web-scraper, data-enrichment, email-sender, lead-scorer, and more
+- [CLI Reference](cli/index.mdx) - All CLI commands: check, deploy, exec, resources, executions, env, and more
+- [Deployment](deployment/index.mdx) - Deploy pipeline, versioning, bundle upload, and registry registration
+- [Runtime](runtime/index.mdx) - Worker execution model, concurrency, timeouts, cancellation, and resource limits
+
+### Framework
+
+- [Development Framework](framework/index.mdx) - How Claude Code helps you build: project structure, agent integration, memory, and documentation
+
+### Developer Tools
+
+- [Documentation](framework/documentation.mdx) - Writing and deploying MDX documentation alongside your resources
+- [Roadmap](roadmap/index.mdx) - Planned features including agent execution, streaming logs, and SDK testing utilities
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/platform-tools/examples.mdx

@@ -0,0 +1,187 @@
+---
+title: Integration Examples
+description: Common platform.call() patterns for email, CRM, PDF, LLM inference, resource triggering, and storage
+loadWhen: "Implementing a platform tool call in a workflow step"
+---
+
+Common `platform.call()` patterns ready to use in your SDK workflows. Each example shows the complete invocation including tool name, method, params, and credential (where required).
+
+## 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
+const result = await platform.call({
+  tool: 'resend',
+  method: 'sendEmail',
+  credential: 'resend',
+  params: {
+    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
+const result = await platform.call({
+  tool: 'attio',
+  method: 'createRecord',
+  credential: 'attio',
+  params: {
+    objectType: 'people',
+    attributes: {
+      name: [{ full_name: 'Jane Smith' }],
+      email_addresses: [{ email_address: 'jane@example.com' }],
+      company: 'Acme Corp'
+    }
+  }
+})
+
+// result.data.id is the new record ID
+const recordId = result.data.id
+```
+
+Attio exposes 11 tools covering CRUD operations, schema inspection, and notes. See the Attio adapter documentation for the full method list.
+
+## Generating a PDF
+
+Render a PDF from an HTML string or a registered template. No credential required -- PDF generation is a built-in platform service.
+
+```typescript
+const pdfBuffer = await platform.call({
+  tool: 'pdf',
+  method: 'renderToBuffer',
+  params: {
+    html: `
+      <h1>Invoice #1042</h1>
+      <p>Customer: Jane Smith</p>
+      <p>Amount due: $450.00</p>
+    `,
+    options: {
+      format: 'A4',
+      margin: { top: '20mm', bottom: '20mm', left: '15mm', right: '15mm' }
+    }
+  }
+})
+
+// Upload the buffer to storage for later retrieval
+await platform.call({
+  tool: 'storage',
+  method: 'upload',
+  params: {
+    path: 'invoices/invoice-1042.pdf',
+    data: pdfBuffer,
+    contentType: 'application/pdf'
+  }
+})
+```
+
+## Making an LLM Call with Structured Output
+
+Use the `llm` tool 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
+const classification = await platform.call({
+  tool: 'llm',
+  method: 'generate',
+  params: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5',
+    messages: [
+      {
+        role: 'system',
+        content: 'You extract structured data from support tickets. Return valid JSON matching the schema.'
+      },
+      {
+        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
+  }
+})
+
+// classification = { priority: 'high', category: 'technical', sentiment: 'negative', summary: '...' }
+```
+
+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
+const outcome = await platform.call({
+  tool: 'execution',
+  method: 'trigger',
+  params: {
+    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
+// Upload a processed file
+await platform.call({
+  tool: 'storage',
+  method: 'upload',
+  params: {
+    path: `exports/${organizationSlug}/report-${Date.now()}.csv`,
+    data: csvContent,
+    contentType: 'text/csv'
+  }
+})
+
+// Generate a signed URL valid for 1 hour (3600 seconds)
+const { signedUrl } = await platform.call({
+  tool: 'storage',
+  method: 'createSignedUrl',
+  params: {
+    path: `exports/${organizationSlug}/report-${Date.now()}.csv`,
+    expiresIn: 3600
+  }
+})
+
+// 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-02-25

package/reference/platform-tools/index.mdx

@@ -0,0 +1,182 @@
+---
+title: Platform Tools
+description: Access 70+ tools across integration adapters and platform services from your SDK workflows via platform.call()
+loadWhen: "Connecting to external services"
+---
+
+`platform.call()` gives your SDK workflows access to the same 70+ tools that internal Elevasis agents use -- Gmail, Stripe, Google Sheets, PDF generation, human-in-the-loop approvals, storage, scheduling, and more. Credentials are managed server-side and never appear in your code. You pass a tool name, method, and parameters; Elevasis handles credential lookup, rate limiting, and retry transparently.
+
+All tools share the same interface regardless of type: integration adapters (third-party APIs) and platform services (built-in Elevasis capabilities) are both called the same way.
+
+## Usage
+
+```typescript
+const result = await platform.call({
+  tool: 'resend',          // tool name (integration adapter or platform service)
+  method: 'sendEmail',     // method exposed by that tool
+  params: { ... },         // method-specific parameters
+  credential: 'my-resend'  // credential name (integration tools only)
+})
+```
+
+`platform.call()` returns a Promise that resolves with the tool result or rejects with a `PlatformToolError` containing a message, error code, and a `retryable` flag.
+
+## Integration Adapters
+
+Thirteen integration adapters give you access to 70+ tool methods covering third-party APIs. Pass the `credential` field with the name of the stored credential for that service.
+
+| Adapter | Tools | Credential Shape |
+| --- | --- | --- |
+| Attio | 11 (CRUD + schema + notes) | `{ apiKey }` |
+| Google Sheets | 13 (read/write/filter/upsert) | OAuth2 / service account |
+| Trello | 10 (cards/lists/checklists) | `{ apiKey, token }` |
+| Notion | 8 (pages + blocks) | `{ token }` |
+| Stripe | 6 (payment links + checkout) | `{ secretKey }` |
+| Instantly | 5 (email campaigns) | `{ apiKey }` |
+| Gmail | 2 (send email) | OAuth2 / service account |
+| Resend | 3 (send/get email) | `{ apiKey }` |
+| SignatureAPI | 3 (envelopes) | `{ apiKey }` |
+| Dropbox | 2 (upload/folder) | `{ accessToken }` |
+| Apify | 1 (run actor) | `{ token }` |
+| Mailso | 1 (verify email) | `{ apiKey }` |
+| Supabase | 7 (insert/select/update/delete/upsert/rpc/count) | `{ url, serviceRoleKey }` |
+
+Credentials are stored in the Elevasis credentials table and injected server-side. The credential name you pass in `credential` must match the name you set when storing the credential.
+
+## Platform Services
+
+Nine built-in platform services are available without a `credential` field. These are Elevasis-managed capabilities.
+
+| Tool Key | Methods | Purpose |
+| --- | --- | --- |
+| `email` | `send` | Send transactional email via Elevasis email service |
+| `storage` | `upload`, `download`, `createSignedUrl`, `delete`, `list` | File storage operations |
+| `pdf` | `render`, `renderToBuffer` | Generate PDFs from templates or HTML |
+| `notification` | `create` | Create in-app notifications |
+| `approval` | `create`, `deleteByMetadata` | Human-in-the-loop approval gates |
+| `scheduler` | `createSchedule`, `updateAnchor`, `deleteSchedule`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`, `listSchedules`, `getSchedule`, `cancelSchedule`, `cancelSchedulesByMetadata` | Task scheduling |
+| `lead` | Dynamic (all methods) | Lead management operations |
+| `llm` | `generate` | LLM inference across multiple providers |
+| `execution` | `trigger` | Trigger another resource as a nested child execution |
+
+## LLM Tool
+
+Call any supported LLM from your workflow with no API keys required. Keys are resolved server-side from environment variables.
+
+```typescript
+const result = await platform.call({
+  tool: 'llm',
+  method: 'generate',
+  params: {
+    provider: 'google',
+    model: 'gemini-3-flash-preview',
+    messages: [
+      { role: 'system', content: 'Classify this email reply.' },
+      { role: 'user', content: emailText }
+    ],
+    responseSchema: {
+      type: 'object',
+      properties: {
+        category: { type: 'string', enum: ['interested', 'not-interested', 'bounced'] },
+        confidence: { type: 'number', minimum: 0, maximum: 1 }
+      },
+      required: ['category', 'confidence']
+    },
+    temperature: 0.2
+  }
+})
+```
+
+**Supported models:**
+
+| Provider | Models |
+| --- | --- |
+| `google` | `gemini-3-flash-preview` |
+| `openai` | `gpt-5`, `gpt-5-mini` |
+| `anthropic` | `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5` |
+| `openrouter` | `openrouter/anthropic/claude-sonnet-4.5`, `openrouter/deepseek/deepseek-v3.2`, `openrouter/x-ai/grok-4.1-fast` |
+
+**Key params:**
+
+- `provider` -- one of `google`, `openai`, `anthropic`, `openrouter`
+- `model` -- model identifier from the table above
+- `messages` -- array of `{ role, content }` objects
+- `responseSchema` -- optional JSON Schema for structured output
+- `temperature` -- optional, controls output randomness
+
+## Execution Tool
+
+Trigger another resource (workflow or agent) as a nested child of the current execution. The child runs synchronously and its result is returned. Depth is tracked automatically up to a maximum of 5 levels to prevent infinite recursion.
+
+```typescript
+const result = await platform.call({
+  tool: 'execution',
+  method: 'trigger',
+  params: {
+    resourceId: 'my-other-workflow',
+    input: { key: 'value' }
+  }
+})
+// result = { success: true, executionId: '...', output: { ... }, error: undefined }
+```
+
+The invoked resource must belong to the same organization. The `organizationId` is always taken from the parent execution context -- you cannot invoke resources across organizations.
+
+## Managing Environment Variables
+
+Use the `elevasis env` CLI to manage environment variables for your deployed workers:
+
+```bash
+elevasis env list
+elevasis env set KEY value
+elevasis env remove KEY
+```
+
+Environment variables set this way are injected into your worker process at startup and are available via `process.env`.
+
+## Database Access
+
+Supabase is a first-class integration adapter that gives your workflows persistent storage using the same `platform.call()` interface as every other tool. Pass the `credential` field with the name of your stored Supabase credential.
+
+**Methods:** `insert`, `select`, `update`, `delete`, `upsert`, `rpc`, `count`
+
+```typescript
+// Select rows with filters
+const qualified = await platform.call({
+  tool: 'supabase',
+  credential: 'my-database',
+  method: 'select',
+  params: {
+    table: 'leads',
+    filter: { status: 'eq.qualified', score: 'gte.80' },
+    order: { column: 'score', ascending: false },
+    limit: 50,
+  },
+})
+// Returns: [{ id: '...', name: 'Jane Doe', score: 92, ... }, ...]
+```
+
+**Filter syntax** uses PostgREST string format (`operator.value`):
+
+| Filter | Example | Meaning |
+| --- | --- | --- |
+| `eq` | `{ status: 'eq.qualified' }` | Equals |
+| `neq` | `{ status: 'neq.lost' }` | Not equals |
+| `gt`, `gte`, `lt`, `lte` | `{ score: 'gte.80' }` | Comparisons |
+| `like`, `ilike` | `{ name: 'ilike.%jane%' }` | Pattern match |
+| `in` | `{ status: 'in.(new,contacted)' }` | In set |
+| `is` | `{ deleted_at: 'is.null' }` | Null check |
+
+**Credential setup:** Create a credential with provider `supabase` in the command center. The config fields are `url` (your Supabase project URL) and `serviceRoleKey` (the service role key from Settings > API). Workflows always use the service role key -- server-side execution, no RLS.
+
+**`/database init`:** A guided setup command that stores your Supabase credential, generates `data/schema.ts`, and creates `docs/database.mdx`.
+
+**`data/schema.ts`:** An agent-readable Zod schema that documents your table structure. It is NOT deployed and NOT executed -- the agent reads it to understand your data model when writing workflow steps or generating queries.
+
+## Documentation
+
+- [Integration Examples](examples.mdx) - Common `platform.call()` patterns with working code for email, CRM, PDF, LLM, and more
+
+---
+
+**Last Updated:** 2026-02-25