@elevasis/sdk 0.4.4 → 0.4.6

package/reference/getting-started/project-structure.mdx

@@ -0,0 +1,148 @@
+---
+title: Project Structure
+description: Each file scaffolded by elevasis init and its purpose in the development workflow
+---
+
+`elevasis init` creates a complete project structure. This page explains what each file does and when you will interact with it.
+
+---
+
+## Source Files
+
+### `src/index.ts`
+
+Your resource definitions live here. This file must export an `OrganizationResources` object as its default export. The scaffolded file contains a working echo workflow that demonstrates the `z.infer` pattern for Zod schema types.
+
+Every resource you add -- workflows and agents -- is registered through this default export.
+
+### `elevasis.config.ts`
+
+Project-level configuration. The scaffolded file contains commented-out options (`defaultStatus`, `dev.port`) so you can discover available settings without having to look them up. Leave this file minimal; the platform provides sensible defaults.
+
+---
+
+## Documentation
+
+### `docs/index.mdx`
+
+The entry point for your project's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis deploy` and rendered in the Elevasis platform UI.
+
+Use MDX frontmatter to set page metadata:
+
+```yaml
+---
+title: Overview
+description: Documentation for this project
+order: 0
+---
+```
+
+Add more pages by creating additional `.mdx` files in `docs/`. Nested directories create sections: `docs/guides/setup.mdx` becomes a `guides/setup` page under your deployment's documentation.
+
+---
+
+## Configuration Files
+
+### `.env`
+
+Contains your `ELEVASIS_API_KEY`. This file is gitignored. Never commit it.
+
+### `.env.example`
+
+A git-safe template showing which variables are needed:
+
+```
+ELEVASIS_API_KEY=sk_your_key_here
+```
+
+Commit this file so collaborators know what to configure.
+
+### `.npmrc`
+
+Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
+
+### `tsconfig.json`
+
+App-focused TypeScript configuration. It does not include `declaration` or `declarationMap` settings because your project is a deployable application, not a library.
+
+### `.gitignore`
+
+Pre-configured to exclude:
+- `.env` -- API key
+- `__elevasis_worker.ts` -- temporary file generated during deployment
+- `.claude/settings.local.json` -- local Claude Code overrides
+- `.claude/profile.json` -- your personal onboarding profile
+
+---
+
+## Claude Code Integration
+
+The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and your project structure from the first session.
+
+### `CLAUDE.md`
+
+The most important file for AI-assisted development. It provides Claude Code with:
+
+- **Project orientation** -- what an Elevasis SDK project is and how it works
+- **Project structure** -- which files contain resources, documentation, and configuration
+- **SDK patterns** -- working code examples for resource definitions, Zod schemas, and the `OrganizationResources` export
+- **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
+- **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)
+
+Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that makes the slash commands work well.
+
+### `.claude/settings.json`
+
+Sets `autoCompact: false`. This prevents Claude Code from automatically compacting context during long sessions, which can lose important earlier context about your project.
+
+### `.claude/profile.json`
+
+Created automatically on your first Claude Code session. The agent runs a one-time onboarding flow asking about your organization, project goals, and experience level. Answers are stored here and used to personalize subsequent sessions.
+
+This file is gitignored -- it is personal to you and not shared with collaborators.
+
+---
+
+## Slash Commands
+
+The `.claude/commands/` directory contains three commands covering the core development loop. Invoke them in Claude Code with `/docs`, `/resource`, and `/deploy`.
+
+### `/docs` -- Documentation Assistant
+
+Helps you write and maintain documentation in `docs/`. Three operations:
+
+- **No arguments** -- Review existing `docs/` files, identify undocumented resources and gaps, suggest improvements
+- **`create <page-name>`** -- Scaffold a new documentation page with correct frontmatter, populated from your resource definitions
+- **`review`** -- Check all `docs/` files for accuracy against the actual code in `src/`, flag mismatches between documented schemas and implementation
+
+### `/resource` -- Resource Scaffolding
+
+Scaffolds new workflow definitions with proper types, Zod schemas, and step structure. Three operations:
+
+- **`workflow <name>`** -- Single-step workflow with Zod input/output schemas, config object, contract, step handler, and addition to the `OrganizationResources` export
+- **`multi-step <name>`** -- Multi-step workflow with `StepType.LINEAR` or `StepType.CONDITIONAL`, connected steps, and per-step schemas
+- **`tool-step <name>`** -- Step that calls a platform tool via `platform.call()` with `PlatformToolError` error handling and a credential note
+
+### `/deploy` -- Deployment Assistant
+
+Guides you through validation and deployment. Two operations:
+
+- **No arguments** -- Runs `elevasis check`, reports any validation errors, then runs `elevasis deploy` if check passes. Analyzes failure output and suggests fixes if the deploy fails
+- **`status`** -- Runs `elevasis deployments` and `elevasis resources` to show current deployment state
+
+---
+
+## File Reference
+
+| File | When You Edit It |
+|------|-----------------|
+| `src/index.ts` | Adding or modifying resources |
+| `docs/index.mdx` | Updating project documentation |
+| `elevasis.config.ts` | Changing project-level settings |
+| `.env` | Adding environment variables |
+| `CLAUDE.md` | Rarely -- only to add project-specific context |
+| `.claude/commands/*.md` | Rarely -- commands work well as scaffolded |
+
+---
+
+**Last Updated:** 2026-02-25

package/reference/index.mdx

@@ -0,0 +1,105 @@
+---
+title: Elevasis SDK
+description: Build and deploy workflows, agents, and resources with the Elevasis 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 12 integration adapters -- Gmail, Slack, HubSpot, 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
+
+### Reference
+
+- [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
+
+### Developer Tools
+
+- [Documentation](documentation/index.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,186 @@
+---
+title: Integration Examples
+description: Common platform.call() patterns for email, CRM, PDF, LLM inference, resource triggering, and storage
+---
+
+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,141 @@
+---
+title: Platform Tools
+description: Access 70+ integration adapters and platform services from your SDK workflows via platform.call()
+---
+
+`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
+
+Twelve integration adapters give you access to roughly 50 tool factories 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 }` |
+
+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`.
+
+## Documentation
+
+- [Integration Examples](examples.mdx) - Common `platform.call()` patterns with working code for email, CRM, PDF, LLM, and more
+
+---
+
+**Last Updated:** 2026-02-25