@elevasis/sdk 0.5.12 → 0.5.14

package/reference/platform-tools/index.mdx

@@ -1,195 +1,354 @@
----
-title: Platform Tools
-description: Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters with full autocomplete for all tools, plus platform.call() as a fallback
-loadWhen: "Connecting to external services"
----
-
-Your SDK workflows have access to 70+ tools -- 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.
-
-**Typed adapters** are the recommended way to call tools. They provide full TypeScript autocomplete, compile-time method checking, and eliminate boilerplate. Use `platform.call()` only for tools that don't have an adapter yet.
-
-## Usage
-
-**Preferred: Typed adapters** (available for all integration tools + key platform services)
-
-```typescript
-import { createResendAdapter, scheduler, llm } from '@elevasis/sdk/worker'
-
-// Integration tools: factory pattern (credential bound once)
-const resend = createResendAdapter('my-resend')
-await resend.sendEmail({ from: 'hi@app.com', to: 'user@example.com', subject: '...' })
-
-// Platform services: singleton (no credential needed)
-await scheduler.createSchedule({ ... })
-const result = await llm.generate({ messages: [...] })
-```
-
-**Fallback: `platform.call()`** (for tools without typed adapters)
-
-```typescript
-import { platform } from '@elevasis/sdk/worker'
-
-const result = await platform.call({
-  tool: 'lead',             // tool name
-  method: 'upsertDeal',     // method exposed by that tool
-  params: { ... },          // method-specific parameters
-})
-```
-
-Both patterns return 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 60+ tool methods covering third-party APIs. Pass the `credential` field with the name of the stored credential for that service. Supabase is listed separately under [Database Access](#database-access) below.
-
-| Adapter | Tools | Credential Shape |
-| --- | --- | --- |
-| Attio | 12 (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 | 2 (send/get email) | `{ apiKey }` |
-| SignatureAPI | 4 (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. All have typed singleton adapters imported from `@elevasis/sdk/worker`.
-
-| Tool Key | Methods | Purpose |
-| --- | --- | --- |
-| `lead` | 35 methods (CRUD + sync) | Lead management -- `lead` singleton adapter |
-| `email` | `send` | Send platform email to org members -- `email` singleton adapter |
-| `storage` | `upload`, `download`, `createSignedUrl`, `delete`, `list` | File storage -- `storage` singleton adapter |
-| `pdf` | `render`, `renderToBuffer` | PDF rendering -- `pdf` singleton adapter |
-| `notification` | `create` | In-app notifications -- `notifications` singleton adapter |
-| `approval` | `create`, `deleteByMetadata` | HITL approval gates -- `approval` singleton adapter |
-| `scheduler` | `createSchedule`, `updateAnchor`, `deleteSchedule`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`, `listSchedules`, `getSchedule`, `cancelSchedule`, `cancelSchedulesByMetadata` | Task scheduling -- `scheduler` singleton adapter |
-| `llm` | `generate` | LLM inference -- `llm` singleton adapter |
-| `execution` | `trigger` | Nested child execution -- `execution` singleton adapter |
-
-## LLM Tool
-
-Call any supported LLM from your workflow with no API keys required. Keys are resolved server-side from environment variables. Use the `llm` typed adapter for full autocomplete.
-
-```typescript
-import { llm } from '@elevasis/sdk/worker'
-
-const result = await llm.generate({
-  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
-import { execution } from '@elevasis/sdk/worker'
-
-const result = await execution.trigger({
-  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-sdk env` CLI to manage environment variables for your deployed workers:
-
-```bash
-elevasis-sdk env list
-elevasis-sdk env set KEY value
-elevasis-sdk 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
-
-- [Typed Adapters](adapters.mdx) - Type-safe wrappers for all 12 integrations + 9 platform services with full autocomplete (recommended)
-- [Integration Examples](examples.mdx) - Working code examples for email, CRM, PDF, LLM, and more
-
----
-
-**Last Updated:** 2026-03-02
+---
+title: Platform Tools
+description: Access 70+ tools across integration adapters and platform services from your SDK workflows -- typed adapters, credential security model, and working code examples
+loadWhen: "Connecting to external services"
+---
+
+Your SDK workflows have access to 70+ tools -- 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.
+
+**Typed adapters** are the recommended way to call tools. They provide full TypeScript autocomplete, compile-time method checking, and eliminate boilerplate. Use `platform.call()` only for tools that don't have an adapter yet.
+
+## Usage
+
+**Preferred: Typed adapters** (available for all integration tools + key platform services)
+
+```typescript
+import { createResendAdapter, scheduler, llm } from '@elevasis/sdk/worker'
+
+// Integration tools: factory pattern (credential bound once)
+const resend = createResendAdapter('my-resend')
+await resend.sendEmail({ from: 'hi@app.com', to: 'user@example.com', subject: '...' })
+
+// Platform services: singleton (no credential needed)
+await scheduler.createSchedule({ ... })
+const result = await llm.generate({ messages: [...] })
+```
+
+**Fallback: `platform.call()`** (for tools without typed adapters)
+
+```typescript
+import { platform } from '@elevasis/sdk/worker'
+
+const result = await platform.call({
+  tool: 'lead',             // tool name
+  method: 'upsertDeal',     // method exposed by that tool
+  params: { ... },          // method-specific parameters
+})
+```
+
+Both patterns return a Promise that resolves with the tool result or rejects with a `PlatformToolError` containing a message, error code, and a `retryable` flag.
+
+## Integration Adapters
+
+Eleven integration adapters give you access to 55+ tool methods covering third-party APIs. Pass the `credential` field with the name of the stored credential for that service. Supabase is listed separately under [Database Access](#database-access) below.
+
+| Adapter       | Tools                         | Credential Shape         |
+| ------------- | ----------------------------- | ------------------------ |
+| Attio         | 12 (CRUD + schema + notes)    | `{ apiKey }`             |
+| Google Sheets | 13 (read/write/filter/upsert) | OAuth2 / service account |
+| Notion        | 8 (pages + blocks)            | `{ token }`              |
+| Stripe        | 6 (payment links + checkout)  | `{ secretKey }`          |
+| Instantly     | 5 (email campaigns)           | `{ apiKey }`             |
+| Gmail         | 2 (send email)                | OAuth2 / service account |
+| Resend        | 2 (send/get email)            | `{ apiKey }`             |
+| SignatureAPI  | 4 (envelopes)                 | `{ apiKey }`             |
+| Dropbox       | 2 (upload/folder)             | `{ accessToken }`        |
+| Apify         | 1 (run actor)                 | `{ token }`              |
+| Mailso        | 1 (verify email)              | `{ apiKey }`             |
+
+## Credential Security
+
+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 or CLI) and are accessed through three controlled channels.
+
+### Layer 1: Platform Tools (Default)
+
+All platform tools resolve credentials server-side. The credential value never crosses 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: '...' },
+})
+```
+
+### Layer 2: HTTP Platform Tool
+
+For APIs without a dedicated adapter, use the `http` platform tool. Credentials are injected server-side before the outgoing 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' },
+  },
+})
+```
+
+**Supported 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                            |
+| Basic auth      | `{ type: 'basic', username: '...', password: '...' }`            | `Authorization: Basic base64(user:pass)` |
+| Query parameter | `{ type: 'query-param', param: 'api_key', value: 'ak_...' }`     | Appended to URL                          |
+| Body field      | `{ type: 'body-field', field: 'apiKey', value: 'ak_...' }`       | Merged into JSON body                    |
+| Custom header   | `{ type: 'custom-header', header: 'X-Custom', value: '...' }`    | Arbitrary header                         |
+
+### Layer 3: getCredential() (Explicit Opt-In)
+
+For third-party SDKs that require a raw key (e.g., `new Stripe(key)`), use `platform.getCredential()`. This explicitly causes the credential value to enter worker memory.
+
+```typescript
+import { platform } from '@elevasis/sdk/worker'
+
+const cred = await platform.getCredential('my-stripe-key')
+const stripe = new Stripe(cred.credentials.secretKey)
+```
+
+All `getCredential()` calls are logged. Use `platform.call()` with the `http` tool when possible.
+
+### Credential Setup
+
+Credentials are created in the command center UI: navigate to Credentials → Add Credential → select type → enter values → save. The name you give the credential is what you pass as `credential: 'my-cred-name'` in `platform.call()`. Credential names are case-sensitive -- a mismatch causes `PlatformToolError: credential not found`.
+
+### Choosing a Pattern
+
+| Situation                                              | Pattern                                 |
+| ------------------------------------------------------ | --------------------------------------- |
+| Using a supported adapter (Gmail, Attio, Stripe, etc.) | `platform.call()` with the adapter tool |
+| Calling an API not in the catalog                      | `platform.call()` with `tool: 'http'`   |
+| Third-party SDK that requires a raw key                | `platform.getCredential()`              |
+
+`.env` contains only `ELEVASIS_PLATFORM_KEY` for CLI authentication -- never integration credentials.
+
+---
+
+## Platform Services
+
+Nine built-in platform services are available without a `credential` field. All have typed singleton adapters imported from `@elevasis/sdk/worker`.
+
+| Tool Key       | Methods                                                                                                                                                                                     | Purpose                                                         |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `lead`         | 35 methods (CRUD + sync)                                                                                                                                                                    | Lead management -- `lead` singleton adapter                     |
+| `email`        | `send`                                                                                                                                                                                      | Send platform email to org members -- `email` singleton adapter |
+| `storage`      | `upload`, `download`, `createSignedUrl`, `delete`, `list`                                                                                                                                   | File storage -- `storage` singleton adapter                     |
+| `pdf`          | `render`, `renderToBuffer`                                                                                                                                                                  | PDF rendering -- `pdf` singleton adapter                        |
+| `notification` | `create`                                                                                                                                                                                    | In-app notifications -- `notifications` singleton adapter       |
+| `approval`     | `create`, `deleteByMetadata`                                                                                                                                                                | HITL approval gates -- `approval` singleton adapter             |
+| `scheduler`    | `createSchedule`, `updateAnchor`, `deleteSchedule`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`, `listSchedules`, `getSchedule`, `cancelSchedule`, `cancelSchedulesByMetadata` | Task scheduling -- `scheduler` singleton adapter                |
+| `llm`          | `generate`                                                                                                                                                                                  | LLM inference -- `llm` singleton adapter                        |
+| `execution`    | `trigger`                                                                                                                                                                                   | Nested child execution -- `execution` singleton adapter         |
+
+## LLM Tool
+
+Call any supported LLM from your workflow with no API keys required. Keys are resolved server-side from environment variables.
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+
+const result = await llm.generate({
+  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`, `model`, `messages` (`{ role, content }[]`), `responseSchema` (optional JSON Schema), `temperature` (optional).
+
+## Execution Tool
+
+Trigger another resource as a nested child of the current execution. The child runs synchronously and its result is returned. Maximum depth: 5 levels.
+
+```typescript
+import { execution } from '@elevasis/sdk/worker'
+
+const result = await execution.trigger({
+  resourceId: 'my-other-workflow',
+  input: { key: 'value' },
+})
+// result = { success: true, executionId: '...', output: { ... }, error: undefined }
+```
+
+The invoked resource must belong to the same organization.
+
+## Database Access
+
+Supabase is a first-class integration adapter for persistent storage. Pass the `credential` field with your stored Supabase credential name.
+
+**Methods:** `insert`, `select`, `update`, `delete`, `upsert`, `rpc`, `count`
+
+```typescript
+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,
+  },
+})
+```
+
+**Filter syntax** uses PostgREST 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` — config fields are `url` and `serviceRoleKey`. Workflows always use the service role key (server-side, no RLS).
+
+**`/database init`:** Guided setup that stores your Supabase credential, generates `data/schema.ts`, and creates `docs/database.mdx`.
+
+**`data/schema.ts`:** An agent-readable Zod schema documenting your table structure. Not deployed or executed — the agent reads it to understand your data model.
+
+---
+
+## Code Examples
+
+### Email via Resend
+
+```typescript
+import { createResendAdapter } from '@elevasis/sdk/worker'
+
+const resend = createResendAdapter('resend')
+await resend.sendEmail({
+  from: 'hello@yourapp.com',
+  to: 'customer@example.com',
+  subject: 'Your order is confirmed',
+  html: '\<p\>Thank you for your order!\</p\>',
+})
+```
+
+### CRM Record via 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
+```
+
+### PDF Generation
+
+```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' },
+})
+
+// Or render to buffer for inline processing
+const { buffer } = await pdf.renderToBuffer({ document: proposalDocument })
+await storage.upload({ bucket: 'invoices', path: 'invoice-1042.pdf', content: buffer, contentType: 'application/pdf' })
+```
+
+### LLM with Structured Output
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+
+interface TicketClassification {
+  priority: 'low' | 'medium' | 'high' | 'critical'
+  category: 'billing' | 'technical' | 'account' | 'other'
+  summary: string
+}
+
+const response = await llm.generate\<TicketClassification\>({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+  messages: [
+    { role: 'system', content: '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'] },
+      summary: { type: 'string' },
+    },
+    required: ['priority', 'category', 'summary'],
+  },
+  temperature: 0.1,
+})
+const { priority, category, summary } = response.output
+```
+
+### Triggering Another Resource
+
+```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}`)
+```
+
+### File Storage
+
+```typescript
+import { storage } from '@elevasis/sdk/worker'
+
+const reportPath = `exports/report-${Date.now()}.csv`
+await storage.upload({ bucket: 'exports', path: reportPath, content: csvContent, contentType: 'text/csv' })
+
+const { signedUrl } = await storage.createSignedUrl({ bucket: 'exports', path: reportPath })
+// signedUrl is valid for 1 hour (3600 seconds) -- share with user or include in email
+```
+
+---
+
+## Documentation
+
+- [Typed Adapters](adapters.mdx) - Type-safe wrappers for all 11 integrations + 9 platform services with full autocomplete (recommended)
+
+---
+
+**Last Updated:** 2026-03-06