@elevasis/sdk 0.4.5 → 0.4.7

package/reference/security/credentials.mdx

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

package/reference/templates/data-enrichment.mdx

@@ -0,0 +1,162 @@
+---
+title: "Template: Data Enrichment"
+description: "LLM-powered enrichment of existing database records -- read rows, enrich each with an LLM, write results back to Supabase"
+loadWhen: "Applying the data-enrichment workflow template"
+---
+
+**Category:** Data Processing
+
+**Platform Tools:** `llm` (text generation), `supabase` (select and update)
+
+**Credentials Required:**
+
+- `my-database` -- Supabase project URL and service role key
+- LLM API keys are resolved server-side from platform configuration (no credential name needed)
+
+---
+
+## What This Workflow Does
+
+Fetches records from a Supabase table that need enrichment, sends each record to an LLM with a custom prompt, and writes the enriched field back to the table. Supports batching to process multiple records per execution. Suitable for enriching leads with AI-generated summaries, classifying records, extracting structured data from text fields, or scoring records.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  table: z.string(),              // Supabase table to enrich
+  filter: z.record(z.string()).optional(), // Filter rows to enrich (PostgREST format)
+  sourceField: z.string(),        // Field to send to the LLM as input
+  targetField: z.string(),        // Field to write enriched output to
+  prompt: z.string(),             // LLM prompt template (use {value} as placeholder)
+  limit: z.number().optional(),   // Max rows to process (default: 20)
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  processed: z.number(),          // Rows successfully enriched
+  skipped: z.number(),            // Rows skipped (missing source field, LLM error)
+  errors: z.array(z.string()),    // Error messages for skipped rows
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { platform } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  table: z.string(),
+  filter: z.record(z.string()).optional(),
+  sourceField: z.string(),
+  targetField: z.string(),
+  prompt: z.string(),
+  limit: z.number().optional(),
+})
+const outputSchema = z.object({
+  processed: z.number(),
+  skipped: z.number(),
+  errors: z.array(z.string()),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const dataEnrichment: WorkflowDefinition = {
+  config: {
+    resourceId: 'data-enrichment',
+    name: 'Data Enrichment',
+    type: 'workflow',
+    description: 'Enriches database records using an LLM',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    enrich: {
+      id: 'enrich',
+      name: 'Enrich Records',
+      description: 'Fetch records, call LLM for each, write results back',
+      inputSchema,
+      outputSchema,
+      handler: async (input, context) => {
+        const { table, filter, sourceField, targetField, prompt, limit } = input as Input
+
+        // Fetch rows to enrich
+        const rows = await platform.call({
+          tool: 'supabase',
+          method: 'select',
+          credential: 'my-database',
+          params: { table, filter, limit: limit ?? 20 },
+        }) as Array<Record<string, unknown>>
+
+        let processed = 0
+        const errors: string[] = []
+
+        for (const row of rows) {
+          const sourceValue = row[sourceField]
+          if (!sourceValue || typeof sourceValue !== 'string') {
+            errors.push(`Row ${String(row.id)}: missing ${sourceField}`)
+            continue
+          }
+
+          try {
+            const enrichedPrompt = prompt.replace('{value}', sourceValue)
+            const result = await platform.call({
+              tool: 'llm',
+              method: 'generate',
+              params: {
+                provider: 'openai',
+                model: 'gpt-4o-mini',
+                messages: [{ role: 'user', content: enrichedPrompt }],
+              },
+            }) as string
+
+            await platform.call({
+              tool: 'supabase',
+              method: 'update',
+              credential: 'my-database',
+              params: {
+                table,
+                filter: { id: `eq.${String(row.id)}` },
+                data: { [targetField]: result },
+              },
+            })
+
+            context.logger.info('Enriched row', { id: row.id })
+            processed++
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err)
+            errors.push(`Row ${String(row.id)}: ${msg}`)
+          }
+        }
+
+        return { processed, skipped: errors.length, errors }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'enrich',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Credential name:** Replace `'my-database'` with the user's database credential name.
+- **LLM provider and model:** Default uses `openai` / `gpt-4o-mini`. Adapt to the user's preference or available providers.
+- **Prompt template:** The `{value}` placeholder is replaced with the source field's value at runtime. Adapt the prompt for the user's specific enrichment task.
+- **Batch size:** Default limit is 20 rows. Increase for bulk processing, decrease for expensive LLM calls.
+- **Skill adaptation:** For beginners, explain what "enrichment" means and give concrete examples (adding a summary field, scoring, categorizing) before generating code.
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/templates/email-sender.mdx

@@ -0,0 +1,135 @@
+---
+title: "Template: Email Sender"
+description: "Transactional email via Resend with template support -- send styled emails to one or multiple recipients"
+loadWhen: "Applying the email-sender workflow template"
+---
+
+**Category:** Communication
+
+**Platform Tools:** `resend` (send email)
+
+**Credentials Required:**
+
+- `my-resend` -- Resend API key (bearer type)
+
+---
+
+## What This Workflow Does
+
+Sends a transactional email to one or more recipients using the Resend email service. Supports plain text and HTML content, reply-to addresses, and CC/BCC. Suitable for welcome emails, notification emails, confirmation emails, and any triggered transactional communication.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  to: z.union([z.string(), z.array(z.string())]), // Recipient(s)
+  subject: z.string(),                             // Email subject
+  html: z.string().optional(),                     // HTML body
+  text: z.string().optional(),                     // Plain text body (fallback)
+  from: z.string().optional(),                     // Sender (defaults to workspace default)
+  replyTo: z.string().optional(),                  // Reply-to address
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  sent: z.boolean(),
+  messageId: z.string().optional(),
+  error: z.string().optional(),
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { platform, PlatformToolError } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  to: z.union([z.string(), z.array(z.string())]),
+  subject: z.string(),
+  html: z.string().optional(),
+  text: z.string().optional(),
+  from: z.string().optional(),
+  replyTo: z.string().optional(),
+})
+const outputSchema = z.object({
+  sent: z.boolean(),
+  messageId: z.string().optional(),
+  error: z.string().optional(),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const emailSender: WorkflowDefinition = {
+  config: {
+    resourceId: 'email-sender',
+    name: 'Email Sender',
+    type: 'workflow',
+    description: 'Sends transactional email via Resend',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    send: {
+      id: 'send',
+      name: 'Send Email',
+      description: 'Send the email via Resend',
+      inputSchema,
+      outputSchema,
+      handler: async (input, context) => {
+        const { to, subject, html, text, from, replyTo } = input as Input
+
+        try {
+          const result = await platform.call({
+            tool: 'resend',
+            method: 'sendEmail',
+            credential: 'my-resend',
+            params: {
+              to: Array.isArray(to) ? to : [to],
+              subject,
+              html: html ?? `<p>${text ?? ''}</p>`,
+              text,
+              from: from ?? 'noreply@yourdomain.com',
+              replyTo,
+            },
+          }) as { id: string }
+
+          context.logger.info('Email sent', { messageId: result.id, to })
+          return { sent: true, messageId: result.id }
+        } catch (err) {
+          if (err instanceof PlatformToolError) {
+            context.logger.error('Email send failed', { error: err.message, to })
+            return { sent: false, error: err.message }
+          }
+          throw err
+        }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'send',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Credential name:** Replace `'my-resend'` with the user's Resend credential name.
+- **From address:** Replace `'noreply@yourdomain.com'` with the user's verified sender address (must be verified in Resend).
+- **HTML vs text:** For beginners, suggest writing plain text first and adding HTML later. For developers, show both.
+- **Error handling:** The template returns `{ sent: false, error }` on failure rather than throwing, suitable for non-critical emails. For critical notifications, change to `throw err` so the execution fails visibly.
+- **Multi-step context:** This template is a single step, but it can be used as the last step of a multi-step workflow (e.g., "process data then send summary email").
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/templates/lead-scorer.mdx

@@ -0,0 +1,175 @@
+---
+title: "Template: Lead Scorer"
+description: "LLM-based lead scoring with Supabase storage -- receive a lead, score it with an LLM, store the result"
+loadWhen: "Applying the lead-scorer workflow template"
+---
+
+**Category:** CRM
+
+**Platform Tools:** `llm` (scoring), `supabase` (store score)
+
+**Credentials Required:**
+
+- `my-database` -- Supabase project URL and service role key
+- LLM API keys are resolved server-side from platform configuration (no credential name needed)
+
+---
+
+## What This Workflow Does
+
+Receives a lead with company and contact details, uses an LLM to score the lead on multiple criteria, and stores the scored lead in a Supabase table. The scoring criteria and output fields are customizable. Suitable for inbound lead qualification, prioritization queues, and sales routing.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  leadId: z.string(),
+  company: z.string(),
+  role: z.string().optional(),
+  email: z.string().optional(),
+  notes: z.string().optional(),      // Any additional context about the lead
+  scoringCriteria: z.string().optional(), // Custom scoring criteria (overrides default)
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  leadId: z.string(),
+  score: z.number(),                 // 0-100 overall score
+  tier: z.enum(['hot', 'warm', 'cold']),
+  reasoning: z.string(),             // LLM explanation of the score
+  stored: z.boolean(),
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { StepType } from '@elevasis/sdk'
+import { platform } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  leadId: z.string(),
+  company: z.string(),
+  role: z.string().optional(),
+  email: z.string().optional(),
+  notes: z.string().optional(),
+  scoringCriteria: z.string().optional(),
+})
+const outputSchema = z.object({
+  leadId: z.string(),
+  score: z.number(),
+  tier: z.enum(['hot', 'warm', 'cold']),
+  reasoning: z.string(),
+  stored: z.boolean(),
+})
+
+const DEFAULT_CRITERIA = `
+Score this lead from 0-100 based on:
+- Company fit (industry, size, budget signals) -- 40 points
+- Role relevance (decision-maker or influencer) -- 30 points
+- Engagement potential (any signals from notes) -- 30 points
+
+Return JSON: { "score": number, "tier": "hot"|"warm"|"cold", "reasoning": "..." }
+Hot = 70+, Warm = 40-69, Cold = below 40.
+`
+
+type Input = z.infer<typeof inputSchema>
+
+export const leadScorer: WorkflowDefinition = {
+  config: {
+    resourceId: 'lead-scorer',
+    name: 'Lead Scorer',
+    type: 'workflow',
+    description: 'Scores leads using an LLM and stores results in Supabase',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    score: {
+      id: 'score',
+      name: 'Score Lead',
+      description: 'Score the lead using an LLM',
+      inputSchema,
+      outputSchema: z.object({ leadId: z.string(), score: z.number(), tier: z.enum(['hot', 'warm', 'cold']), reasoning: z.string() }),
+      handler: async (input) => {
+        const { leadId, company, role, notes, scoringCriteria } = input as Input
+        const criteria = scoringCriteria ?? DEFAULT_CRITERIA
+
+        const result = await platform.call({
+          tool: 'llm',
+          method: 'generate',
+          params: {
+            provider: 'openai',
+            model: 'gpt-4o-mini',
+            messages: [{
+              role: 'user',
+              content: `${criteria}\n\nLead:\nCompany: ${company}\nRole: ${role ?? 'Unknown'}\nNotes: ${notes ?? 'None'}`,
+            }],
+            responseSchema: {
+              type: 'object',
+              properties: {
+                score: { type: 'number' },
+                tier: { type: 'string', enum: ['hot', 'warm', 'cold'] },
+                reasoning: { type: 'string' },
+              },
+            },
+          },
+        }) as { score: number; tier: 'hot' | 'warm' | 'cold'; reasoning: string }
+
+        return { leadId, score: result.score, tier: result.tier, reasoning: result.reasoning }
+      },
+      next: { type: StepType.LINEAR, target: 'store' },
+    },
+    store: {
+      id: 'store',
+      name: 'Store Score',
+      description: 'Save the lead score to Supabase',
+      inputSchema: z.object({ leadId: z.string(), score: z.number(), tier: z.enum(['hot', 'warm', 'cold']), reasoning: z.string() }),
+      outputSchema,
+      handler: async (input, context) => {
+        const { leadId, score, tier, reasoning } = input as { leadId: string; score: number; tier: 'hot' | 'warm' | 'cold'; reasoning: string }
+
+        await platform.call({
+          tool: 'supabase',
+          method: 'update',
+          credential: 'my-database',
+          params: {
+            table: 'leads',
+            filter: { id: `eq.${leadId}` },
+            data: { score, tier, scoring_reasoning: reasoning, scored_at: new Date().toISOString() },
+          },
+        })
+
+        context.logger.info('Lead scored and stored', { leadId, score, tier })
+        return { leadId, score, tier, reasoning, stored: true }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'score',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Credential name:** Replace `'my-database'` with the user's database credential name.
+- **Table name:** Replace `'leads'` with the user's actual table name. Check `data/schema.ts` if it exists.
+- **Scoring criteria:** Customize `DEFAULT_CRITERIA` based on the user's ICP (ideal customer profile). Ask the user what matters most for their scoring.
+- **Table columns:** The template writes `score`, `tier`, `scoring_reasoning`, `scored_at`. Ensure these columns exist or adapt the field names.
+- **LLM model:** Default uses `gpt-4o-mini`. For more nuanced scoring, suggest `gpt-4o`.
+
+---
+
+**Last Updated:** 2026-02-26