@elevasis/sdk 1.44.2 → 1.45.0

package/reference/sdk/templates/email-sender.mdx

@@ -1,135 +1,139 @@
----
-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
+---
+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
+
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
+```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
+
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
+```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: ${result.id} to ${JSON.stringify(to)}`)
+          return { sent: true, messageId: result.id }
+        } catch (err) {
+          if (err instanceof PlatformToolError) {
+            context.logger.error(`Email send failed for ${JSON.stringify(to)}: ${err.message}`)
+            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/sdk/templates/lead-scorer.mdx

@@ -23,6 +23,8 @@ Receives a lead with company and contact details, uses an LLM to score the lead
 
 ## Input Schema
 
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
 ```typescript
 z.object({
   leadId: z.string(),
@@ -36,6 +38,8 @@ z.object({
 
 ## Output Schema
 
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
 ```typescript
 z.object({
   leadId: z.string(),
@@ -150,7 +154,7 @@ export const leadScorer: WorkflowDefinition = {
           },
         })
 
-        context.logger.info('Lead scored and stored', { leadId, score, tier })
+        context.logger.info(`Lead ${leadId} scored ${score} (${tier}) and stored`)
         return { leadId, score, tier, reasoning, stored: true }
       },
       next: null,

package/reference/sdk/templates/pdf-generator.mdx

@@ -1,151 +1,155 @@
----
-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
+---
+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
+
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
+```typescript
+z.object({
+  templateHtml: z.string(),          // HTML template with {variable} placeholders
+  data: z.record(z.string(), 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
+
+{/* doc-snippet:skip: illustrative excerpt -- shows the schema shape in isolation, omits the `import { z } from 'zod'` shown in Workflow Code Pattern below */}
+
+```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.string(), 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: ${filename} at ${key}`)
+        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