memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,187 @@
+# 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/references/email-routing/gotchas.md

@@ -0,0 +1,203 @@
+# 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

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

@@ -0,0 +1,241 @@
+# 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      |