@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/email-routing/patterns.md

@@ -0,0 +1,229 @@
+# Common Patterns
+
+## 1. Allowlist/Blocklist
+
+```typescript
+// Allowlist
+const allowed = ["user@example.com", "trusted@corp.com"];
+if (!allowed.includes(message.from)) {
+  message.setReject("Not allowed");
+  return;
+}
+await message.forward("inbox@corp.com");
+```
+
+## 2. Parse Email Body
+
+```typescript
+import PostalMime from 'postal-mime';
+
+export default {
+  async email(message, env, ctx) {
+    // CRITICAL: Consume stream immediately
+    const raw = await message.raw.arrayBuffer();
+    
+    const parser = new PostalMime();
+    const email = await parser.parse(raw);
+    
+    console.log({
+      subject: email.subject,
+      text: email.text,
+      html: email.html,
+      from: email.from.address,
+      attachments: email.attachments.length
+    });
+    
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler;
+```
+
+## 3. Spam Filter
+
+```typescript
+const score = parseFloat(message.headers.get("x-cf-spamh-score") || "0");
+if (score > 5) {
+  message.setReject("Spam detected");
+  return;
+}
+await message.forward("inbox@corp.com");
+```
+
+## 4. Archive to R2
+
+```typescript
+interface Env { R2: R2Bucket; }
+
+export default {
+  async email(message, env, ctx) {
+    const raw = await message.raw.arrayBuffer();
+    
+    const key = `${new Date().toISOString()}-${message.from}.eml`;
+    await env.R2.put(key, raw, { 
+      httpMetadata: { contentType: "message/rfc822" }
+    });
+    
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## 5. Store Metadata in KV
+
+```typescript
+import PostalMime from 'postal-mime';
+
+interface Env { KV: KVNamespace; }
+
+export default {
+  async email(message, env, ctx) {
+    const raw = await message.raw.arrayBuffer();
+    const parser = new PostalMime();
+    const email = await parser.parse(raw);
+    
+    const metadata = {
+      from: email.from.address,
+      subject: email.subject,
+      timestamp: new Date().toISOString(),
+      size: raw.byteLength
+    };
+    
+    await env.KV.put(`email:${Date.now()}`, JSON.stringify(metadata));
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## 6. Subject-Based Routing
+
+```typescript
+export default {
+  async email(message, env, ctx) {
+    const subject = message.headers.get("subject")?.toLowerCase() || "";
+    
+    if (subject.includes("[urgent]")) {
+      await message.forward("oncall@corp.com");
+    } else if (subject.includes("[billing]")) {
+      await message.forward("billing@corp.com");
+    } else if (subject.includes("[support]")) {
+      await message.forward("support@corp.com");
+    } else {
+      await message.forward("general@corp.com");
+    }
+  }
+} satisfies ExportedHandler;
+```
+
+## 7. Auto-Reply
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+  REPLIED: KVNamespace;
+}
+
+export default {
+  async email(message, env, ctx) {
+    const msgId = message.headers.get("message-id");
+    
+    if (msgId && await env.REPLIED.get(msgId)) {
+      await message.forward("archive@corp.com");
+      return;
+    }
+    
+    ctx.waitUntil((async () => {
+      await env.EMAIL.send({
+        from: "noreply@yourdomain.com",
+        to: message.from,
+        subject: "Re: " + (message.headers.get("subject") || ""),
+        text: "Thank you. We'll respond within 24h."
+      });
+      if (msgId) await env.REPLIED.put(msgId, "1", { expirationTtl: 604800 });
+    })());
+    
+    await message.forward("support@corp.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## 8. Extract Attachments
+
+```typescript
+import PostalMime from 'postal-mime';
+
+interface Env { ATTACHMENTS: R2Bucket; }
+
+export default {
+  async email(message, env, ctx) {
+    const parser = new PostalMime();
+    const email = await parser.parse(await message.raw.arrayBuffer());
+    
+    for (const att of email.attachments) {
+      const key = `${Date.now()}-${att.filename}`;
+      await env.ATTACHMENTS.put(key, att.content, {
+        httpMetadata: { contentType: att.mimeType }
+      });
+    }
+    
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## 9. Log to D1
+
+```typescript
+import PostalMime from 'postal-mime';
+
+interface Env { DB: D1Database; }
+
+export default {
+  async email(message, env, ctx) {
+    const parser = new PostalMime();
+    const email = await parser.parse(await message.raw.arrayBuffer());
+    
+    ctx.waitUntil(
+      env.DB.prepare("INSERT INTO log (ts, from_addr, subj) VALUES (?, ?, ?)")
+        .bind(new Date().toISOString(), email.from.address, email.subject || "")
+        .run()
+    );
+    
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## 10. Multi-Tenant
+
+```typescript
+interface Env { TENANTS: KVNamespace; }
+
+export default {
+  async email(message, env, ctx) {
+    const subdomain = message.to.split("@")[1].split(".")[0];
+    const config = await env.TENANTS.get(subdomain, "json") as { forward: string } | null;
+    
+    if (!config) {
+      message.setReject("Unknown tenant");
+      return;
+    }
+    
+    await message.forward(config.forward);
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Summary
+
+| Pattern | Use Case | Storage |
+|---------|----------|---------|
+| Allowlist | Security | None |
+| Parse | Body/attachments | None |
+| Spam Filter | Reduce spam | None |
+| R2 Archive | Email storage | R2 |
+| KV Meta | Analytics | KV |
+| Subject Route | Dept routing | None |
+| Auto-Reply | Support | KV |
+| Attachments | Doc mgmt | R2 |
+| D1 Log | Audit trail | D1 |
+| Multi-Tenant | SaaS | KV |

package/skills/cloudflare-deploy/references/email-workers/README.md

@@ -0,0 +1,151 @@
+# Cloudflare Email Workers
+
+Process incoming emails programmatically using Cloudflare Workers runtime.
+
+## Overview
+
+Email Workers enable custom email processing logic at the edge. Build spam filters, auto-responders, ticket systems, notification handlers, and more using the same Workers runtime you use for HTTP requests.
+
+**Key capabilities**:
+- Process inbound emails with full message access
+- Forward to verified destinations
+- Send replies with proper threading
+- Parse MIME content and attachments
+- Integrate with KV, R2, D1, and external APIs
+
+## Quick Start
+
+### Minimal ES Modules Handler
+
+```typescript
+export default {
+  async email(message, env, ctx) {
+    // Reject spam
+    if (message.from.includes('spam.com')) {
+      message.setReject('Blocked');
+      return;
+    }
+    
+    // Forward to inbox
+    await message.forward('inbox@example.com');
+  }
+};
+```
+
+### Core Operations
+
+| Operation | Method | Use Case |
+|-----------|--------|----------|
+| Forward | `message.forward(to, headers?)` | Route to verified destination |
+| Reject | `message.setReject(reason)` | Block with SMTP error |
+| Reply | `message.reply(emailMessage)` | Auto-respond with threading |
+| Parse | postal-mime library | Extract subject, body, attachments |
+
+## Reading Order
+
+For comprehensive understanding, read files in this order:
+
+1. **README.md** (this file) - Overview and quick start
+2. **configuration.md** - Setup, deployment, bindings
+3. **api.md** - Complete API reference
+4. **patterns.md** - Real-world implementation examples
+5. **gotchas.md** - Critical pitfalls and debugging
+
+## In This Reference
+
+| File | Description | Key Topics |
+|------|-------------|------------|
+| [api.md](./api.md) | Complete API reference | ForwardableEmailMessage, SendEmail bindings, reply() method, postal-mime/mimetext APIs |
+| [configuration.md](./configuration.md) | Setup and configuration | wrangler.jsonc, bindings, deployment, dependencies |
+| [patterns.md](./patterns.md) | Real-world examples | Allowlists from KV, auto-reply with threading, attachment extraction, webhook notifications |
+| [gotchas.md](./gotchas.md) | Pitfalls and debugging | Stream consumption, ctx.waitUntil errors, security, limits |
+
+## Architecture
+
+```
+Incoming Email → Email Routing → Email Worker
+                                    ↓
+                              Process + Decide
+                                    ↓
+                    ┌───────────────┼───────────────┐
+                    ↓               ↓               ↓
+                Forward          Reply          Reject
+```
+
+**Event flow**:
+1. Email arrives at your domain
+2. Email Routing matches route (e.g., `support@example.com`)
+3. Bound Email Worker receives `ForwardableEmailMessage`
+4. Worker processes and takes action (forward/reply/reject)
+5. Email delivered or rejected based on worker logic
+
+## Key Concepts
+
+### Envelope vs Headers
+
+- **Envelope addresses** (`message.from`, `message.to`): SMTP transport addresses (trusted)
+- **Header addresses** (parsed from body): Display addresses (can be spoofed)
+
+Use envelope addresses for security decisions.
+
+### Single-Use Streams
+
+`message.raw` is a ReadableStream that can only be read once. Buffer to ArrayBuffer for multiple uses.
+
+```typescript
+// Buffer first
+const buffer = await new Response(message.raw).arrayBuffer();
+const email = await PostalMime.parse(buffer);
+```
+
+See [gotchas.md](./gotchas.md#readablestream-can-only-be-consumed-once) for details.
+
+### Verified Destinations
+
+`forward()` only works with addresses verified in the Cloudflare Email Routing dashboard. Add destinations before deployment.
+
+## Use Cases
+
+- **Spam filtering**: Block based on sender, content, or reputation
+- **Auto-responders**: Send acknowledgment replies with threading
+- **Ticket creation**: Parse emails and create support tickets
+- **Email archival**: Store in KV, R2, or D1
+- **Notification routing**: Forward to Slack, Discord, or webhooks
+- **Attachment processing**: Extract files to R2 storage
+- **Multi-tenant routing**: Route based on recipient subdomain
+- **Size filtering**: Reject oversized attachments
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max message size | 25 MiB |
+| Max routing rules | 200 |
+| Max destinations | 200 |
+| CPU time (free tier) | 10ms |
+| CPU time (paid tier) | 50ms |
+
+See [gotchas.md](./gotchas.md#limits-reference) for complete limits table.
+
+## Prerequisites
+
+Before deploying Email Workers:
+
+1. **Enable Email Routing** in Cloudflare dashboard for your domain
+2. **Verify destination addresses** for forwarding
+3. **Configure DMARC/SPF** for sending domains (required for replies)
+4. **Set up wrangler.jsonc** with SendEmail binding
+
+See [configuration.md](./configuration.md) for detailed setup.
+
+## Service Worker Syntax (Deprecated)
+
+Modern projects should use ES modules format shown above. Service Worker syntax (`addEventListener('email', ...)`) is deprecated but still supported.
+
+## See Also
+
+- [Email Routing Documentation](https://developers.cloudflare.com/email-routing/)
+- [Workers Platform](https://developers.cloudflare.com/workers/)
+- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
+- [postal-mime on npm](https://www.npmjs.com/package/postal-mime)
+- [mimetext on npm](https://www.npmjs.com/package/mimetext)

package/skills/cloudflare-deploy/references/email-workers/api.md

@@ -0,0 +1,237 @@
+# Email Workers API Reference
+
+Complete API reference for Cloudflare Email Workers runtime.
+
+## ForwardableEmailMessage Interface
+
+The main interface passed to email handlers.
+
+```typescript
+interface ForwardableEmailMessage {
+  readonly from: string;        // Envelope MAIL FROM (SMTP sender)
+  readonly to: string;          // Envelope RCPT TO (SMTP recipient)
+  readonly headers: Headers;    // Web-standard Headers object
+  readonly raw: ReadableStream; // Raw MIME message (single-use stream)
+  readonly rawSize: number;     // Total message size in bytes
+  
+  setReject(reason: string): void;
+  forward(rcptTo: string, headers?: Headers): Promise<void>;
+  reply(message: EmailMessage): Promise<void>;
+}
+```
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `from` | string | Envelope sender (SMTP MAIL FROM) - use for security |
+| `to` | string | Envelope recipient (SMTP RCPT TO) |
+| `headers` | Headers | Message headers (Subject, Message-ID, etc.) |
+| `raw` | ReadableStream | Raw MIME message (**single-use**, buffer first) |
+| `rawSize` | number | Message size in bytes |
+
+### Methods
+
+#### setReject(reason: string): void
+
+Reject with permanent SMTP 5xx error. Email not delivered, sender may receive bounce.
+
+```typescript
+if (blockList.includes(message.from)) {
+  message.setReject('Sender blocked');
+}
+```
+
+#### forward(rcptTo: string, headers?: Headers): Promise<void>
+
+Forward to verified destination. Only `X-*` custom headers allowed.
+
+```typescript
+await message.forward('inbox@example.com');
+
+// With custom headers
+const h = new Headers();
+h.set('X-Processed-By', 'worker');
+await message.forward('inbox@example.com', h);
+```
+
+#### reply(message: EmailMessage): Promise<void>
+
+Send a reply to the original sender (March 2025 feature).
+
+```typescript
+import { EmailMessage } from 'cloudflare:email';
+import { createMimeMessage } from 'mimetext';
+
+const msg = createMimeMessage();
+msg.setSender({ name: 'Support', addr: 'support@example.com' });
+msg.setRecipient(message.from);
+msg.setSubject(`Re: ${message.headers.get('Subject')}`);
+msg.setHeader('In-Reply-To', message.headers.get('Message-ID'));
+msg.setHeader('References', message.headers.get('References') || '');
+msg.addMessage({
+  contentType: 'text/plain',
+  data: 'Thank you for your message.'
+});
+
+await message.reply(new EmailMessage(
+  'support@example.com',
+  message.from,
+  msg.asRaw()
+));
+```
+
+**Requirements**:
+- Incoming email needs valid DMARC
+- Reply once per event, recipient = `message.from`
+- Sender domain = receiving domain, with DMARC/SPF/DKIM
+- Max 100 `References` entries
+- Threading: `In-Reply-To` (original Message-ID), `References`, new `Message-ID`
+
+## EmailMessage Constructor
+
+```typescript
+import { EmailMessage } from 'cloudflare:email';
+
+new EmailMessage(from: string, to: string, raw: ReadableStream | string)
+```
+
+Used for sending emails (replies or via SendEmail binding). Domain must be verified.
+
+## SendEmail Interface
+
+```typescript
+interface SendEmail {
+  send(message: EmailMessage): Promise<void>;
+}
+
+// Usage
+await env.EMAIL.send(new EmailMessage(from, to, mimeContent));
+```
+
+## SendEmail Binding Types
+
+```jsonc
+{
+  "send_email": [
+    { "name": "EMAIL" },  // Type 1: Any verified address
+    { "name": "LOGS", "destination_address": "logs@example.com" },  // Type 2: Single dest
+    { "name": "TEAM", "allowed_destination_addresses": ["a@ex.com", "b@ex.com"] },  // Type 3: Dest allowlist
+    { "name": "NOREPLY", "allowed_sender_addresses": ["noreply@ex.com"] }  // Type 4: Sender allowlist
+  ]
+}
+```
+
+## postal-mime Parsed Output
+
+postal-mime v2.7.3 parses incoming emails into structured data.
+
+```typescript
+interface ParsedEmail {
+  headers: Array<{ key: string; value: string }>;
+  from: { name: string; address: string } | null;
+  to: Array<{ name: string; address: string }> | { name: string; address: string } | null;
+  cc: Array<{ name: string; address: string }> | null;
+  bcc: Array<{ name: string; address: string }> | null;
+  subject: string;
+  messageId: string | null;
+  inReplyTo: string | null;
+  references: string | null;
+  date: string | null;
+  html: string | null;
+  text: string | null;
+  attachments: Array<{
+    filename: string;
+    mimeType: string;
+    disposition: string | null;
+    related: boolean;
+    contentId: string | null;
+    content: Uint8Array;
+  }>;
+}
+```
+
+### Usage
+
+```typescript
+import PostalMime from 'postal-mime';
+
+const buffer = await new Response(message.raw).arrayBuffer();
+const email = await PostalMime.parse(buffer);
+
+console.log(email.subject);
+console.log(email.from?.address);
+console.log(email.text);
+console.log(email.attachments.length);
+```
+
+## mimetext API Quick Reference
+
+mimetext v3.0.27 composes outgoing emails.
+
+```typescript
+import { createMimeMessage } from 'mimetext';
+
+const msg = createMimeMessage();
+
+// Sender
+msg.setSender({ name: 'John Doe', addr: 'john@example.com' });
+
+// Recipients
+msg.setRecipient('alice@example.com');
+msg.setRecipients(['bob@example.com', 'carol@example.com']);
+msg.setCc('manager@example.com');
+msg.setBcc(['audit@example.com']);
+
+// Headers
+msg.setSubject('Meeting Notes');
+msg.setHeader('In-Reply-To', '<previous-message-id>');
+msg.setHeader('References', '<msg1> <msg2>');
+msg.setHeader('Message-ID', `<${crypto.randomUUID()}@example.com>`);
+
+// Content
+msg.addMessage({
+  contentType: 'text/plain',
+  data: 'Plain text content'
+});
+
+msg.addMessage({
+  contentType: 'text/html',
+  data: '<p>HTML content</p>'
+});
+
+// Attachments
+msg.addAttachment({
+  filename: 'report.pdf',
+  contentType: 'application/pdf',
+  data: pdfBuffer // Uint8Array or base64 string
+});
+
+// Generate raw MIME
+const raw = msg.asRaw(); // Returns string
+```
+
+## TypeScript Types
+
+```typescript
+import { 
+  ForwardableEmailMessage,
+  EmailMessage 
+} from 'cloudflare:email';
+
+interface Env {
+  EMAIL: SendEmail;
+  EMAIL_ARCHIVE: KVNamespace;
+  ALLOWED_SENDERS: KVNamespace;
+}
+
+export default {
+  async email(
+    message: ForwardableEmailMessage,
+    env: Env,
+    ctx: ExecutionContext
+  ): Promise<void> {
+    // Fully typed
+  }
+};
+```