@elevasis/sdk 0.4.5 → 0.4.7

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

package/reference/templates/text-classifier.mdx

@@ -0,0 +1,147 @@
+---
+title: "Template: Text Classifier"
+description: "Multi-label text classification with structured output -- classify text into predefined categories using an LLM with JSON output"
+loadWhen: "Applying the text-classifier workflow template"
+---
+
+**Category:** AI
+
+**Platform Tools:** `llm` (structured generation)
+
+**Credentials Required:**
+
+- LLM API keys are resolved server-side from platform configuration (no credential name needed)
+
+---
+
+## What This Workflow Does
+
+Classifies input text into one or more predefined categories using an LLM. Returns structured output with category assignments and confidence reasoning. Suitable for ticket categorization, email routing, content tagging, sentiment analysis, and any text classification task where the categories are known in advance.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  text: z.string(),                        // Text to classify
+  categories: z.array(z.string()),         // Available category labels
+  multiLabel: z.boolean().optional(),      // Allow multiple categories (default: false)
+  instructions: z.string().optional(),     // Additional instructions for the LLM
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  categories: z.array(z.string()),         // Assigned category labels
+  reasoning: z.string(),                   // LLM explanation of classification
+  confidence: z.enum(['high', 'medium', 'low']),
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { platform } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  text: z.string(),
+  categories: z.array(z.string()),
+  multiLabel: z.boolean().optional(),
+  instructions: z.string().optional(),
+})
+const outputSchema = z.object({
+  categories: z.array(z.string()),
+  reasoning: z.string(),
+  confidence: z.enum(['high', 'medium', 'low']),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const textClassifier: WorkflowDefinition = {
+  config: {
+    resourceId: 'text-classifier',
+    name: 'Text Classifier',
+    type: 'workflow',
+    description: 'Classifies text into predefined categories using an LLM',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    classify: {
+      id: 'classify',
+      name: 'Classify Text',
+      description: 'Use LLM to classify the input text',
+      inputSchema,
+      outputSchema,
+      handler: async (input) => {
+        const { text, categories, multiLabel, instructions } = input as Input
+        const mode = multiLabel ? 'one or more' : 'exactly one'
+        const categoryList = categories.map(c => `- ${c}`).join('\n')
+
+        const prompt = `Classify the following text into ${mode} of these categories:
+${categoryList}
+${instructions ? `\nAdditional instructions: ${instructions}` : ''}
+
+Text to classify:
+"${text}"
+
+Return JSON with:
+- categories: array of matching category names (from the list above only)
+- reasoning: brief explanation of your classification
+- confidence: "high" (very clear match), "medium" (reasonable but uncertain), or "low" (ambiguous)`
+
+        const result = await platform.call({
+          tool: 'llm',
+          method: 'generate',
+          params: {
+            provider: 'openai',
+            model: 'gpt-4o-mini',
+            messages: [{ role: 'user', content: prompt }],
+            responseSchema: {
+              type: 'object',
+              properties: {
+                categories: { type: 'array', items: { type: 'string' } },
+                reasoning: { type: 'string' },
+                confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+              },
+            },
+          },
+        }) as { categories: string[]; reasoning: string; confidence: 'high' | 'medium' | 'low' }
+
+        // Validate that returned categories are from the allowed list
+        const validCategories = result.categories.filter(c => categories.includes(c))
+
+        return {
+          categories: validCategories,
+          reasoning: result.reasoning,
+          confidence: result.confidence,
+        }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'classify',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Category design:** Help the user define clear, mutually exclusive category names. Ambiguous categories produce inconsistent results.
+- **Multi-label use:** Enable `multiLabel: true` when a single piece of text can legitimately belong to multiple categories (e.g., a support ticket about "billing AND account access").
+- **Confidence routing:** Common pattern: use the output with `StepType.CONDITIONAL` routing. High confidence routes to automated processing; low confidence routes to human review.
+- **Model selection:** `gpt-4o-mini` is fast and cost-effective for classification. For complex or nuanced categorization, suggest `gpt-4o`.
+- **Skill adaptation:** For beginners, explain what "structured output" means and why the LLM returns JSON instead of free text.
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/templates/web-scraper.mdx

@@ -0,0 +1,135 @@
+---
+title: "Template: Web Scraper"
+description: "Apify-based web scraper that stores results in Supabase -- fetch structured data from any website via Apify actors"
+loadWhen: "Applying the web-scraper workflow template"
+---
+
+**Category:** Data Collection
+
+**Platform Tools:** `apify` (run actor), `supabase` (insert results)
+
+**Credentials Required:**
+
+- `apify` -- Apify API token (bearer type)
+- `my-database` -- Supabase project URL and service role key
+
+---
+
+## What This Workflow Does
+
+Runs an Apify actor to scrape structured data from a URL, then stores the scraped results in a Supabase table. The actor and table names are configurable. Suitable for extracting product listings, job postings, contact information, or any structured web content.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  actorId: z.string(),          // Apify actor ID (e.g., 'apify/web-scraper')
+  startUrls: z.array(z.string()), // URLs to scrape
+  tableName: z.string(),        // Supabase table to store results in
+  maxItems: z.number().optional(), // Maximum number of items to collect (default: 100)
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  itemsScraped: z.number(),     // Total items scraped
+  itemsInserted: z.number(),    // Items successfully inserted into Supabase
+  runId: z.string(),            // Apify run ID for reference
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { StepType } from '@elevasis/sdk'
+import { platform, PlatformToolError } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  actorId: z.string(),
+  startUrls: z.array(z.string()),
+  tableName: z.string(),
+  maxItems: z.number().optional(),
+})
+const outputSchema = z.object({
+  itemsScraped: z.number(),
+  itemsInserted: z.number(),
+  runId: z.string(),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const webScraper: WorkflowDefinition = {
+  config: {
+    resourceId: 'web-scraper',
+    name: 'Web Scraper',
+    type: 'workflow',
+    description: 'Scrapes structured data via Apify and stores in Supabase',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    scrape: {
+      id: 'scrape',
+      name: 'Run Apify Actor',
+      description: 'Execute the Apify actor and collect results',
+      inputSchema,
+      outputSchema: z.object({ items: z.array(z.unknown()), runId: z.string() }),
+      handler: async (input) => {
+        const { actorId, startUrls, maxItems } = input as Input
+        const result = await platform.call({
+          tool: 'apify',
+          method: 'runActor',
+          credential: 'apify',
+          params: { actorId, input: { startUrls: startUrls.map(url => ({ url })), maxItems: maxItems ?? 100 } },
+        }) as { items: unknown[]; runId: string }
+        return { items: result.items, runId: result.runId }
+      },
+      next: { type: StepType.LINEAR, target: 'store' },
+    },
+    store: {
+      id: 'store',
+      name: 'Store Results',
+      description: 'Insert scraped items into Supabase',
+      inputSchema: z.object({ items: z.array(z.unknown()), runId: z.string(), tableName: z.string() }),
+      outputSchema,
+      handler: async (input, context) => {
+        const { items, runId, tableName } = input as { items: unknown[]; runId: string; tableName: string }
+        const data = items.map(item => ({ ...(item as Record<string, unknown>), scraped_at: new Date().toISOString() }))
+        await platform.call({
+          tool: 'supabase',
+          method: 'insert',
+          credential: 'my-database',
+          params: { table: tableName, data },
+        })
+        context.logger.info('Stored scraped items', { count: data.length, table: tableName })
+        return { itemsScraped: items.length, itemsInserted: data.length, runId }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'scrape',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Credential names:** Replace `'apify'` and `'my-database'` with the credential names the user configured in the command center.
+- **Table schema:** Ensure the Supabase table exists and has columns that match the scraped data fields. The agent should check `data/schema.ts` if it exists.
+- **Actor selection:** Apify has hundreds of public actors. Common choices: `apify/web-scraper` (generic), `apify/cheerio-scraper` (fast HTML parsing), specialized actors for LinkedIn, Amazon, etc.
+- **Error handling:** Add try/catch for `PlatformToolError` if partial failure tolerance is needed.
+- **Skill adaptation:** For beginners, explain what Apify is and walk through actor selection before generating code.
+
+---
+
+**Last Updated:** 2026-02-26