@elevasis/sdk 0.4.6 → 0.4.8

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

package/reference/templates/pdf-generator.mdx

@@ -0,0 +1,151 @@
+---
+title: "Template: PDF Generator"
+description: "PDF generation from structured data with platform storage upload -- render a PDF from a template and upload to platform storage"
+loadWhen: "Applying the pdf-generator workflow template"
+---
+
+**Category:** Documents
+
+**Platform Tools:** `pdf` (render), `storage` (upload)
+
+**Credentials Required:**
+
+- None required (pdf and storage are platform services, not integrations)
+
+---
+
+## What This Workflow Does
+
+Receives structured data, renders a PDF using an HTML template, uploads the result to platform storage, and returns a signed URL for download. Suitable for invoices, reports, certificates, contracts, and any document that needs to be generated on demand and delivered as a downloadable file.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  templateHtml: z.string(),          // HTML template with {variable} placeholders
+  data: z.record(z.unknown()),        // Data to inject into the template
+  filename: z.string(),               // Output filename (without .pdf extension)
+  expiresInSeconds: z.number().optional(), // Signed URL expiry (default: 3600)
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  downloadUrl: z.string(),           // Signed URL for the generated PDF
+  storageKey: z.string(),            // Storage key for future reference
+  expiresAt: z.string(),             // ISO timestamp when URL expires
+})
+```
+
+---
+
+## 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({
+  templateHtml: z.string(),
+  data: z.record(z.unknown()),
+  filename: z.string(),
+  expiresInSeconds: z.number().optional(),
+})
+const outputSchema = z.object({
+  downloadUrl: z.string(),
+  storageKey: z.string(),
+  expiresAt: z.string(),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+function renderTemplate(html: string, data: Record<string, unknown>): string {
+  return html.replace(/\{(\w+)\}/g, (_, key) => String(data[key] ?? ''))
+}
+
+export const pdfGenerator: WorkflowDefinition = {
+  config: {
+    resourceId: 'pdf-generator',
+    name: 'PDF Generator',
+    type: 'workflow',
+    description: 'Generates a PDF from HTML template and uploads to storage',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    render: {
+      id: 'render',
+      name: 'Render PDF',
+      description: 'Render HTML template to PDF buffer',
+      inputSchema,
+      outputSchema: z.object({ buffer: z.string(), filename: z.string(), expiresInSeconds: z.number() }),
+      handler: async (input) => {
+        const { templateHtml, data, filename, expiresInSeconds } = input as Input
+        const html = renderTemplate(templateHtml, data)
+
+        const result = await platform.call({
+          tool: 'pdf',
+          method: 'renderToBuffer',
+          params: { html },
+        }) as { buffer: string } // base64-encoded buffer
+
+        return { buffer: result.buffer, filename, expiresInSeconds: expiresInSeconds ?? 3600 }
+      },
+      next: { type: StepType.LINEAR, target: 'upload' },
+    },
+    upload: {
+      id: 'upload',
+      name: 'Upload PDF',
+      description: 'Upload rendered PDF to platform storage and get signed URL',
+      inputSchema: z.object({ buffer: z.string(), filename: z.string(), expiresInSeconds: z.number() }),
+      outputSchema,
+      handler: async (input, context) => {
+        const { buffer, filename, expiresInSeconds } = input as { buffer: string; filename: string; expiresInSeconds: number }
+        const key = `documents/${filename}-${Date.now()}.pdf`
+
+        await platform.call({
+          tool: 'storage',
+          method: 'upload',
+          params: {
+            key,
+            content: buffer,
+            contentType: 'application/pdf',
+          },
+        })
+
+        const urlResult = await platform.call({
+          tool: 'storage',
+          method: 'createSignedUrl',
+          params: { key, expiresIn: expiresInSeconds },
+        }) as { signedUrl: string; expiresAt: string }
+
+        context.logger.info('PDF generated and uploaded', { key, filename })
+        return { downloadUrl: urlResult.signedUrl, storageKey: key, expiresAt: urlResult.expiresAt }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'render',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Template format:** The simple `{variable}` placeholder system handles most cases. For complex documents, suggest the user write a more complete HTML template with inline CSS.
+- **Filename:** The template appends a timestamp to avoid collisions. Adapt naming to the user's convention (e.g., `invoice-{invoiceId}`).
+- **Expiry:** Default is 1 hour. For document delivery workflows, increase to 24-72 hours.
+- **Data structure:** Ask the user what fields their document needs before defining the `data` schema. For typed use cases (invoices, reports), define a stricter input schema.
+- **Skill adaptation:** For beginners, show a complete example HTML template and explain what "template variables" are.
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/templates/recurring-job.mdx

@@ -0,0 +1,189 @@
+---
+title: "Template: Recurring Job"
+description: "Scheduler-triggered periodic workflow -- run a task on a schedule (daily, weekly, hourly, or custom cron)"
+loadWhen: "Applying the recurring-job workflow template"
+---
+
+**Category:** Scheduling
+
+**Platform Tools:** `scheduler` (create/manage schedule)
+
+**Credentials Required:**
+
+- None required (scheduler is a platform service, not an integration)
+
+---
+
+## What This Workflow Does
+
+Two-part pattern for recurring jobs:
+
+1. **Setup workflow** (`recurring-job-setup`): Creates a schedule entry that triggers the main job workflow on a recurring basis. Run once to activate.
+2. **Main job workflow** (`recurring-job`): The actual work executed on each scheduled trigger.
+
+The job workflow and setup workflow share a schedule key for idempotent schedule management.
+
+---
+
+## Input Schema (Setup)
+
+```typescript
+z.object({
+  cronExpression: z.string(),           // Cron expression (e.g., '0 9 * * 1-5' for weekdays at 9am)
+  timezone: z.string().optional(),      // Timezone (default: 'UTC')
+  jobInput: z.record(z.unknown()).optional(), // Input to pass to each job execution
+})
+```
+
+## Input Schema (Job)
+
+```typescript
+z.object({
+  scheduledAt: z.string(),              // ISO timestamp of the scheduled trigger
+  jobInput: z.record(z.unknown()).optional(), // Passed through from schedule creation
+})
+```
+
+## Output Schema (Job)
+
+```typescript
+z.object({
+  completed: z.boolean(),
+  processedAt: z.string(),
+  summary: z.string(),
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { platform } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+// Setup workflow -- run once to create the schedule
+export const recurringJobSetup: WorkflowDefinition = {
+  config: {
+    resourceId: 'recurring-job-setup',
+    name: 'Recurring Job Setup',
+    type: 'workflow',
+    description: 'Creates or updates the schedule for the recurring job',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: {
+    inputSchema: z.object({
+      cronExpression: z.string(),
+      timezone: z.string().optional(),
+      jobInput: z.record(z.unknown()).optional(),
+    }),
+    outputSchema: z.object({
+      scheduleId: z.string(),
+      active: z.boolean(),
+    }),
+  },
+  steps: {
+    createSchedule: {
+      id: 'createSchedule',
+      name: 'Create Schedule',
+      description: 'Set up the recurring schedule',
+      inputSchema: z.object({ cronExpression: z.string(), timezone: z.string().optional(), jobInput: z.record(z.unknown()).optional() }),
+      outputSchema: z.object({ scheduleId: z.string(), active: z.boolean() }),
+      handler: async (input, context) => {
+        const { cronExpression, timezone, jobInput } = input as { cronExpression: string; timezone?: string; jobInput?: Record<string, unknown> }
+
+        const result = await platform.call({
+          tool: 'scheduler',
+          method: 'createSchedule',
+          params: {
+            resourceId: 'recurring-job',
+            cronExpression,
+            timezone: timezone ?? 'UTC',
+            input: { scheduledAt: new Date().toISOString(), jobInput: jobInput ?? {} },
+            idempotencyKey: 'recurring-job-schedule',
+          },
+        }) as { id: string }
+
+        context.logger.info('Schedule created', { scheduleId: result.id, cronExpression })
+        return { scheduleId: result.id, active: true }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'createSchedule',
+}
+
+// Main job workflow -- triggered by the scheduler on each run
+export const recurringJob: WorkflowDefinition = {
+  config: {
+    resourceId: 'recurring-job',
+    name: 'Recurring Job',
+    type: 'workflow',
+    description: 'Executes on each scheduled trigger',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: {
+    inputSchema: z.object({
+      scheduledAt: z.string(),
+      jobInput: z.record(z.unknown()).optional(),
+    }),
+    outputSchema: z.object({
+      completed: z.boolean(),
+      processedAt: z.string(),
+      summary: z.string(),
+    }),
+  },
+  steps: {
+    run: {
+      id: 'run',
+      name: 'Run Job',
+      description: 'Execute the recurring job logic',
+      inputSchema: z.object({ scheduledAt: z.string(), jobInput: z.record(z.unknown()).optional() }),
+      outputSchema: z.object({ completed: z.boolean(), processedAt: z.string(), summary: z.string() }),
+      handler: async (input, context) => {
+        const { scheduledAt, jobInput } = input as { scheduledAt: string; jobInput?: Record<string, unknown> }
+
+        context.logger.info('Recurring job started', { scheduledAt, jobInput })
+
+        // === REPLACE THIS SECTION WITH THE ACTUAL JOB LOGIC ===
+        // Example: fetch data, process it, send a report
+        const summary = `Job completed at ${new Date().toISOString()}`
+        // ======================================================
+
+        return { completed: true, processedAt: new Date().toISOString(), summary }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'run',
+}
+```
+
+---
+
+## Common Cron Expressions
+
+| Schedule | Expression | Notes |
+| --- | --- | --- |
+| Every day at 9am (weekdays) | `0 9 * * 1-5` | Monday-Friday |
+| Every day at midnight | `0 0 * * *` | UTC unless timezone set |
+| Every hour | `0 * * * *` | On the hour |
+| Every Monday at 8am | `0 8 * * 1` | |
+| First of each month | `0 0 1 * *` | Midnight UTC |
+| Every 15 minutes | `*/15 * * * *` | Frequent polling |
+
+---
+
+## Adaptation Notes
+
+- **Job logic:** Replace the placeholder comment in the `run` handler with the actual job logic. Ask the user what the job should do before generating the full workflow.
+- **Both workflows needed:** Remind the user to add both `recurringJob` and `recurringJobSetup` to their `src/index.ts` registry. Run `setup` once to activate; only `recurring-job` runs automatically thereafter.
+- **Idempotency key:** The `recurring-job-schedule` key ensures re-running setup does not create duplicate schedules.
+- **Timezone:** Always ask the user their preferred timezone. Defaults to UTC which may cause unexpected run times.
+
+---
+
+**Last Updated:** 2026-02-26