@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

@@ -0,0 +1,195 @@
+# Email Routing API Reference
+
+## Worker Runtime API
+
+### Email Handler Interface
+
+```typescript
+interface ExportedHandler<Env = unknown> {
+  email?(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): void | Promise<void>;
+}
+```
+
+### ForwardableEmailMessage
+
+Main interface for incoming emails:
+
+```typescript
+interface ForwardableEmailMessage {
+  readonly from: string;          // Envelope sender (e.g., "sender@example.com")
+  readonly to: string;             // Envelope recipient (e.g., "you@yourdomain.com")
+  readonly headers: Headers;       // Web API Headers object
+  readonly raw: ReadableStream;    // Raw MIME message stream
+  
+  setReject(reason: string): void;
+  forward(rcptTo: string, headers?: Headers): Promise<void>;
+}
+```
+
+**Key Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `from` | `string` | Envelope sender (MAIL FROM), not header From |
+| `to` | `string` | Envelope recipient (RCPT TO), not header To |
+| `headers` | `Headers` | Email headers (Subject, From, To, etc.) |
+| `raw` | `ReadableStream` | Raw MIME message (consume once only) |
+
+**Methods:**
+
+- `setReject(reason)`: Reject email with bounce message
+- `forward(rcptTo, headers?)`: Forward to verified destination, optionally add headers
+
+### Headers Object
+
+Standard Web API Headers interface:
+
+```typescript
+// Access headers
+const subject = message.headers.get("subject");
+const from = message.headers.get("from");
+const messageId = message.headers.get("message-id");
+
+// Check spam score
+const spamScore = parseFloat(message.headers.get("x-cf-spamh-score") || "0");
+if (spamScore > 5) {
+  message.setReject("Spam detected");
+}
+```
+
+### Common Headers
+
+`subject`, `from`, `to`, `x-cf-spamh-score` (spam score), `message-id` (deduplication), `dkim-signature` (auth)
+
+### Envelope vs Header Addresses
+
+**Critical distinction:**
+
+```typescript
+// Envelope addresses (routing, auth checks)
+message.from // "bounce@sender.com" (actual sender)
+message.to   // "you@yourdomain.com" (your address)
+
+// Header addresses (display, user-facing)
+message.headers.get("from") // "Alice <alice@sender.com>"
+message.headers.get("to")   // "Bob <you@yourdomain.com>"
+```
+
+**Use envelope addresses for:**
+- Authentication/SPF checks
+- Routing decisions
+- Bounce handling
+
+**Use header addresses for:**
+- Display to users
+- Reply-To logic
+- User-facing filtering
+
+## SendEmail Binding
+
+Outbound email API for transactional messages.
+
+### Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "send_email": [
+    { "name": "EMAIL" }
+  ]
+}
+```
+
+### TypeScript Types
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+}
+
+interface SendEmail {
+  send(message: EmailMessage): Promise<void>;
+}
+
+interface EmailMessage {
+  from: string | { name?: string; email: string };
+  to: string | { name?: string; email: string } | Array<string | { name?: string; email: string }>;
+  subject: string;
+  text?: string;
+  html?: string;
+  headers?: Headers;
+  reply_to?: string | { name?: string; email: string };
+}
+```
+
+### Send Email Example
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+}
+
+export default {
+  async fetch(request, env, ctx): Promise<Response> {
+    await env.EMAIL.send({
+      from: { name: "Acme Corp", email: "noreply@yourdomain.com" },
+      to: [
+        { name: "Alice", email: "alice@example.com" },
+        "bob@example.com"
+      ],
+      subject: "Your order #12345 has shipped",
+      text: "Track your package at: https://track.example.com/12345",
+      html: "<p>Track your package at: <a href='https://track.example.com/12345'>View tracking</a></p>",
+      reply_to: { name: "Support", email: "support@yourdomain.com" }
+    });
+    
+    return new Response("Email sent");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+### SendEmail Constraints
+
+- **From address**: Must be on verified domain (your domain with Email Routing enabled)
+- **Volume limits**: Transactional only, no bulk/marketing email
+- **Rate limits**: 100 emails/minute on Free plan, higher on Paid
+- **No attachments**: Use links to hosted files instead
+- **No DKIM control**: Cloudflare signs automatically
+
+## REST API Operations
+
+Base URL: `https://api.cloudflare.com/client/v4`
+
+### Authentication
+
+```bash
+curl -H "Authorization: Bearer $API_TOKEN" https://api.cloudflare.com/client/v4/...
+```
+
+### Key Endpoints
+
+| Operation | Method | Endpoint |
+|-----------|--------|----------|
+| Enable routing | POST | `/zones/{zone_id}/email/routing/enable` |
+| Disable routing | POST | `/zones/{zone_id}/email/routing/disable` |
+| List rules | GET | `/zones/{zone_id}/email/routing/rules` |
+| Create rule | POST | `/zones/{zone_id}/email/routing/rules` |
+| Verify destination | POST | `/zones/{zone_id}/email/routing/addresses` |
+| List destinations | GET | `/zones/{zone_id}/email/routing/addresses` |
+
+### Create Routing Rule Example
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/rules" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "enabled": true,
+    "name": "Forward sales",
+    "matchers": [{"type": "literal", "field": "to", "value": "sales@yourdomain.com"}],
+    "actions": [{"type": "forward", "value": ["alice@company.com"]}],
+    "priority": 0
+  }'
+```
+
+Matcher types: `literal` (exact match), `all` (catch-all).

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

@@ -0,0 +1,186 @@
+# Email Routing Configuration
+
+## Wrangler Configuration
+
+### Basic Email Worker
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "email-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01",
+  "send_email": [{ "name": "EMAIL" }]
+}
+```
+
+```typescript
+// src/index.ts
+export default {
+  async email(message, env, ctx) {
+    await message.forward("destination@example.com");
+  }
+} satisfies ExportedHandler;
+```
+
+### With Storage Bindings
+
+```jsonc
+{
+  "name": "email-processor",
+  "send_email": [{ "name": "EMAIL" }],
+  "kv_namespaces": [{ "binding": "KV", "id": "abc123" }],
+  "r2_buckets": [{ "binding": "R2", "bucket_name": "emails" }],
+  "d1_databases": [{ "binding": "DB", "database_id": "def456" }]
+}
+```
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+  KV: KVNamespace;
+  R2: R2Bucket;
+  DB: D1Database;
+}
+```
+
+## Local Development
+
+```bash
+npx wrangler dev
+
+# Test with curl
+curl -X POST 'http://localhost:8787/__email' \
+  --header 'content-type: message/rfc822' \
+  --data 'From: test@example.com
+To: you@yourdomain.com
+Subject: Test
+
+Body'
+```
+
+## Deployment
+
+```bash
+npx wrangler deploy
+```
+
+**Connect to Email Routing:**
+
+Dashboard: Email > Email Routing > [domain] > Settings > Email Workers > Select worker
+
+API:
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/settings" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -d '{"enabled": true, "worker": "email-worker"}'
+```
+
+## DNS (Auto-Created)
+
+```dns
+yourdomain.com. IN MX 1 isaac.mx.cloudflare.net.
+yourdomain.com. IN MX 2 linda.mx.cloudflare.net.
+yourdomain.com. IN MX 3 amir.mx.cloudflare.net.
+yourdomain.com. IN TXT "v=spf1 include:_spf.mx.cloudflare.net ~all"
+```
+
+## Secrets & Variables
+
+```bash
+# Secrets (encrypted)
+npx wrangler secret put API_KEY
+
+# Variables (plain)
+# wrangler.jsonc
+{ "vars": { "THRESHOLD": "5.0" } }
+```
+
+```typescript
+interface Env {
+  API_KEY: string;
+  THRESHOLD: string;
+}
+```
+
+## TypeScript Setup
+
+```bash
+npm install --save-dev @cloudflare/workers-types
+```
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "moduleResolution": "bundler",
+    "strict": true
+  }
+}
+```
+
+```typescript
+import type { ForwardableEmailMessage } from "@cloudflare/workers-types";
+
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> {
+    await message.forward("dest@example.com");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Dependencies
+
+```bash
+npm install postal-mime
+```
+
+```typescript
+import PostalMime from 'postal-mime';
+
+export default {
+  async email(message, env, ctx) {
+    const parser = new PostalMime();
+    const email = await parser.parse(await message.raw.arrayBuffer());
+    console.log(email.subject);
+    await message.forward("inbox@corp.com");
+  }
+} satisfies ExportedHandler;
+```
+
+## Multi-Environment
+
+```bash
+# wrangler.dev.jsonc
+{ "name": "worker-dev", "vars": { "ENV": "dev" } }
+
+# wrangler.prod.jsonc
+{ "name": "worker-prod", "vars": { "ENV": "prod" } }
+
+npx wrangler deploy --config wrangler.dev.jsonc
+npx wrangler deploy --config wrangler.prod.jsonc
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+      - run: npm ci
+      - run: npx wrangler deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+```

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

@@ -0,0 +1,196 @@
+# Gotchas & Troubleshooting
+
+## Critical Pitfalls
+
+### Stream Consumption (MOST COMMON)
+
+**Problem:** "stream already consumed" or worker hangs
+
+**Cause:** `message.raw` is `ReadableStream` - consume once only
+
+**Solution:**
+```typescript
+// ❌ WRONG
+const email1 = await parser.parse(await message.raw.arrayBuffer());
+const email2 = await parser.parse(await message.raw.arrayBuffer()); // FAILS
+
+// ✅ CORRECT
+const raw = await message.raw.arrayBuffer();
+const email = await parser.parse(raw);
+```
+
+Consume `message.raw` immediately before any async operations.
+
+### Destination Verification
+
+**Problem:** Emails not forwarding
+
+**Cause:** Destination unverified
+
+**Solution:** Add destination, check inbox for verification email, click link. Verify status: `GET /zones/{id}/email/routing/addresses`
+
+### Mail Authentication
+
+**Problem:** Legitimate emails rejected
+
+**Cause:** Missing SPF/DKIM/DMARC on sender domain
+
+**Solution:** Configure sender DNS:
+```dns
+example.com. IN TXT "v=spf1 include:_spf.example.com ~all"
+selector._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=..."
+_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine"
+```
+
+### Envelope vs Header
+
+**Problem:** Filtering on wrong address
+
+**Solution:**
+```typescript
+// Routing/auth: envelope
+if (message.from === "trusted@example.com") { }
+
+// Display: headers
+const display = message.headers.get("from");
+```
+
+### SendEmail Limits
+
+| Issue | Limit | Solution |
+|-------|-------|----------|
+| From domain | Must own | Use Email Routing domain |
+| Volume | ~100/min Free | Upgrade or throttle |
+| Attachments | Not supported | Link to R2 |
+| Type | Transactional | No bulk |
+
+## Common Errors
+
+### CPU Time Exceeded
+
+**Cause:** Heavy parsing, large emails
+
+**Solution:**
+```typescript
+const size = parseInt(message.headers.get("content-length") || "0") / 1024 / 1024;
+if (size > 20) {
+  message.setReject("Too large");
+  return;
+}
+
+ctx.waitUntil(expensiveWork());
+await message.forward("dest@example.com");
+```
+
+### Rule Not Triggering
+
+**Causes:** Priority conflict, matcher error, catch-all override
+
+**Solution:** Check priority (lower=first), verify exact match, confirm destination verified
+
+### Undefined Property
+
+**Cause:** Missing header
+
+**Solution:**
+```typescript
+// ❌ WRONG
+const subj = message.headers.get("subject").toLowerCase();
+
+// ✅ CORRECT
+const subj = message.headers.get("subject")?.toLowerCase() || "";
+```
+
+## Limits
+
+| Resource | Free | Paid |
+|----------|------|------|
+| Email size | 25 MB | 25 MB |
+| Rules | 200 | 200 |
+| Destinations | 200 | 200 |
+| CPU time | 10ms | 50ms |
+| SendEmail | ~100/min | Higher |
+
+## Debugging
+
+### Local
+
+```bash
+npx wrangler dev
+
+curl -X POST 'http://localhost:8787/__email' \
+  --header 'content-type: message/rfc822' \
+  --data 'From: test@example.com
+To: you@yourdomain.com
+Subject: Test
+
+Body'
+```
+
+### Production
+
+```bash
+npx wrangler tail
+```
+
+### Pattern
+
+```typescript
+export default {
+  async email(message, env, ctx) {
+    try {
+      console.log("From:", message.from);
+      await process(message, env);
+    } catch (err) {
+      console.error(err);
+      message.setReject(err.message);
+    }
+  }
+} satisfies ExportedHandler;
+```
+
+## Auth Troubleshooting
+
+### Check Status
+
+```typescript
+const auth = message.headers.get("authentication-results") || "";
+console.log({
+  spf: auth.includes("spf=pass"),
+  dkim: auth.includes("dkim=pass"),
+  dmarc: auth.includes("dmarc=pass")
+});
+
+if (!auth.includes("pass")) {
+  message.setReject("Failed auth");
+  return;
+}
+```
+
+### SPF Issues
+
+**Causes:** Forwarding breaks SPF, too many lookups (>10), missing includes
+
+**Solution:**
+```dns
+; ✅ Good
+example.com. IN TXT "v=spf1 include:_spf.google.com ~all"
+
+; ❌ Bad - too many
+example.com. IN TXT "v=spf1 include:a.com include:b.com ... ~all"
+```
+
+### DMARC Alignment
+
+**Cause:** From domain must match SPF/DKIM domain
+
+## Best Practices
+
+1. Consume `message.raw` immediately
+2. Verify destinations
+3. Handle missing headers (`?.`)
+4. Use envelope for routing
+5. Check spam scores
+6. Test locally first
+7. Use `ctx.waitUntil` for background work
+8. Size-check early