pi-cloudflare 0.1.0

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

@@ -0,0 +1,112 @@
+# Email Workers Configuration
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "name": "email-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-27",
+  "send_email": [
+    { "name": "EMAIL" },                                    // Unrestricted
+    { "name": "EMAIL_LOGS", "destination_address": "logs@example.com" },  // Single dest
+    { "name": "EMAIL_TEAM", "allowed_destination_addresses": ["a@ex.com", "b@ex.com"] },
+    { "name": "EMAIL_NOREPLY", "allowed_sender_addresses": ["noreply@ex.com"] }
+  ],
+  "kv_namespaces": [{ "binding": "ARCHIVE", "id": "xxx" }],
+  "r2_buckets": [{ "binding": "ATTACHMENTS", "bucket_name": "email-attachments" }],
+  "vars": { "WEBHOOK_URL": "https://hooks.example.com" }
+}
+```
+
+## TypeScript Types
+
+```typescript
+interface Env {
+  EMAIL: SendEmail;
+  ARCHIVE: KVNamespace;
+  ATTACHMENTS: R2Bucket;
+  WEBHOOK_URL: string;
+}
+
+export default {
+  async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext) {}
+};
+```
+
+## Dependencies
+
+```bash
+npm install postal-mime mimetext
+npm install -D @cloudflare/workers-types wrangler typescript
+```
+
+Use postal-mime v2.x, mimetext v3.x.
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "ES2022", "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "moduleResolution": "bundler", "strict": true
+  }
+}
+```
+
+## Local Development
+
+```bash
+npx wrangler dev
+
+# Test receiving
+curl --request POST 'http://localhost:8787/cdn-cgi/handler/email' \
+  --url-query 'from=sender@example.com' --url-query 'to=recipient@example.com' \
+  --header 'Content-Type: text/plain' --data-raw 'Subject: Test\n\nHello'
+```
+
+Sent emails write to local `.eml` files.
+
+## Deployment Checklist
+
+- [ ] Enable Email Routing in dashboard
+- [ ] Verify destination addresses
+- [ ] Configure DMARC/SPF/DKIM for sending
+- [ ] Create KV/R2 resources if needed
+- [ ] Update wrangler.jsonc with production IDs
+
+```bash
+npx wrangler deploy
+npx wrangler deployments list
+```
+
+## Dashboard Setup
+
+1. **Email Routing:** Domain → Email → Enable Email Routing
+2. **Verify addresses:** Email → Destination addresses → Add & verify
+3. **Bind Worker:** Email → Email Workers → Create route → Select pattern & Worker
+4. **DMARC:** Add TXT `_dmarc.domain.com`: `v=DMARC1; p=quarantine;`
+
+## Secrets
+
+```bash
+npx wrangler secret put API_KEY
+# Access: env.API_KEY
+```
+
+## Monitoring
+
+```bash
+npx wrangler tail
+npx wrangler tail --status error
+npx wrangler tail --format json
+```
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| "Binding not found" | Check `send_email` name matches code |
+| "Invalid destination" | Verify in Email Routing dashboard |
+| Type errors | Install `@cloudflare/workers-types` |

package/skills/cloudflare/references/email-workers/gotchas.md

@@ -0,0 +1,125 @@
+# Email Workers Gotchas
+
+## Critical Issues
+
+### ReadableStream Single-Use
+
+```typescript
+// ❌ WRONG: Stream consumed twice
+const email = await PostalMime.parse(await new Response(message.raw).arrayBuffer());
+const rawText = await new Response(message.raw).text(); // EMPTY!
+
+// ✅ CORRECT: Buffer first
+const buffer = await new Response(message.raw).arrayBuffer();
+const email = await PostalMime.parse(buffer);
+const rawText = new TextDecoder().decode(buffer);
+```
+
+### ctx.waitUntil() Errors Silent
+
+```typescript
+// ❌ Errors dropped silently
+ctx.waitUntil(fetch(webhookUrl, { method: 'POST', body: data }));
+
+// ✅ Catch and log
+ctx.waitUntil(
+  fetch(webhookUrl, { method: 'POST', body: data })
+    .catch(err => env.ERROR_LOG.put(`error:${Date.now()}`, err.message))
+);
+```
+
+## Security
+
+### Envelope vs Header From (Spoofing)
+
+```typescript
+const envelopeFrom = message.from;               // SMTP MAIL FROM (trusted)
+const headerFrom = (await PostalMime.parse(buffer)).from?.address; // (untrusted)
+// Use envelope for security decisions
+```
+
+### Input Validation
+
+```typescript
+if (message.rawSize > 5_000_000) { message.setReject('Too large'); return; }
+if ((message.headers.get('Subject') || '').length > 1000) {
+  message.setReject('Invalid subject'); return;
+}
+```
+
+### DMARC for Replies
+
+Replies fail silently without DMARC. Verify: `dig TXT _dmarc.example.com`
+
+## Parsing
+
+### Address Parsing
+
+```typescript
+const email = await PostalMime.parse(buffer);
+const fromAddress = email.from?.address || 'unknown';
+const toAddresses = Array.isArray(email.to) ? email.to.map(t => t.address) : [email.to?.address];
+```
+
+### Character Encoding
+
+Let postal-mime handle decoding - `email.subject`, `email.text`, `email.html` are UTF-8.
+
+## API Behavior
+
+### setReject() vs throw
+
+```typescript
+// setReject() for SMTP rejection
+if (blockList.includes(message.from)) { message.setReject('Blocked'); return; }
+
+// throw for worker errors
+if (!env.KV) throw new Error('KV not configured');
+```
+
+### forward() Only X-* Headers
+
+```typescript
+headers.set('X-Processed-By', 'worker');  // ✅ Works
+headers.set('Subject', 'Modified');        // ❌ Dropped
+```
+
+### Reply Requires Verified Domain
+
+```typescript
+// Use same domain as receiving address
+const receivingDomain = message.to.split('@')[1];
+await message.reply(new EmailMessage(`noreply@${receivingDomain}`, message.from, rawMime));
+```
+
+## Performance
+
+### CPU Limit
+
+```typescript
+// Skip parsing large emails
+if (message.rawSize > 5_000_000) {
+  await message.forward('inbox@example.com');
+  return;
+}
+```
+
+Monitor: `npx wrangler tail`
+
+## Limits
+
+| Limit | Value |
+|-------|-------|
+| Max message size | 25 MiB |
+| Max rules/zone | 200 |
+| CPU time (free/paid) | 10ms / 30s default, 5min max |
+| Reply References | 100 |
+
+## Common Errors
+
+| Error | Fix |
+|-------|-----|
+| "Address not verified" | Add in Email Routing dashboard |
+| "Exceeded CPU time" | Use `ctx.waitUntil()` or upgrade |
+| "Stream is locked" | Buffer `message.raw` first |
+| Silent reply failure | Check DMARC records |

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

@@ -0,0 +1,102 @@
+# Email Workers Patterns
+
+## Parse Email
+
+```typescript
+import PostalMime from 'postal-mime';
+
+export default {
+  async email(message, env, ctx) {
+    const buffer = await new Response(message.raw).arrayBuffer();
+    const email = await PostalMime.parse(buffer);
+    console.log(email.from, email.subject, email.text, email.attachments.length);
+    await message.forward('inbox@example.com');
+  }
+};
+```
+
+## Filtering
+
+```typescript
+// Allowlist from KV
+const allowList = await env.ALLOWED_SENDERS.get('list', 'json') || [];
+if (!allowList.includes(message.from)) {
+  message.setReject('Not allowed');
+  return;
+}
+
+// Size check (avoid parsing large emails)
+if (message.rawSize > 5_000_000) {
+  await message.forward('inbox@example.com'); // Forward without parsing
+  return;
+}
+```
+
+## Auto-Reply with Threading
+
+```typescript
+import { EmailMessage } from 'cloudflare:email';
+import { createMimeMessage } from 'mimetext';
+
+const msg = createMimeMessage();
+msg.setSender({ 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.addMessage({ contentType: 'text/plain', data: 'Thank you. We will respond.' });
+
+await message.reply(new EmailMessage('support@example.com', message.from, msg.asRaw()));
+```
+
+## Rate-Limited Auto-Reply
+
+```typescript
+const rateKey = `rate:${message.from}`;
+if (!await env.RATE_LIMIT.get(rateKey)) {
+  // Send reply...
+  ctx.waitUntil(env.RATE_LIMIT.put(rateKey, '1', { expirationTtl: 3600 }));
+}
+```
+
+## Subject-Based Routing
+
+```typescript
+const subject = (message.headers.get('Subject') || '').toLowerCase();
+if (subject.includes('billing')) await message.forward('billing@example.com');
+else if (subject.includes('support')) await message.forward('support@example.com');
+else await message.forward('general@example.com');
+```
+
+## Multi-Tenant Routing
+
+```typescript
+// support+tenant123@example.com → tenant123
+const tenantId = message.to.split('@')[0].match(/\+(.+)$/)?.[1] || 'default';
+const config = await env.TENANT_CONFIG.get(tenantId, 'json');
+config?.forwardTo ? await message.forward(config.forwardTo) : message.setReject('Unknown');
+```
+
+## Archive & Extract Attachments
+
+```typescript
+// Archive to KV
+ctx.waitUntil(env.ARCHIVE.put(`email:${Date.now()}`, JSON.stringify({
+  from: message.from, subject: email.subject
+})));
+
+// Attachments to R2
+for (const att of email.attachments) {
+  ctx.waitUntil(env.R2.put(`${Date.now()}-${att.filename}`, att.content));
+}
+```
+
+## Webhook Integration
+
+```typescript
+ctx.waitUntil(
+  fetch(env.WEBHOOK_URL, {
+    method: 'POST',
+    body: JSON.stringify({ from: message.from, subject: message.headers.get('Subject') })
+  }).catch(err => console.error(err))
+);
+```

package/skills/cloudflare/references/flagship/README.md

@@ -0,0 +1,59 @@
+# Cloudflare Flagship
+
+Feature flag service for controlling feature visibility without redeploying code. Define flags with targeting rules and percentage-based rollouts, then evaluate them in Workers via a native binding or from any JavaScript runtime via the OpenFeature SDK.
+
+## When to Use
+
+| Need | Use Flagship? | Alternative |
+|------|--------------|-------------|
+| Feature toggles (on/off) | Yes | — |
+| Gradual rollouts (percentage-based) | Yes | — |
+| A/B testing with attribute targeting | Yes | — |
+| Multi-variant configuration delivery | Yes | — |
+| Environment-specific config (dev/staging/prod) | Consider | Wrangler environments, secrets |
+| Static config that never changes | No | `wrangler.jsonc` vars |
+| Per-request rate limiting | No | Rate Limiting rules |
+
+## Key Concepts
+
+- **Apps** — Top-level organizational unit. Maps to a project or service. Each account can have multiple apps.
+- **Flags** — Named feature toggles with a key, variations, targeting rules, and enabled/disabled state.
+- **Variations** — Possible values a flag returns. Types: boolean, string, number, JSON object. All variations on a flag must share the same type.
+- **Targeting rules** — Sequential, priority-ordered conditions that determine which variation to serve. First match wins; no match returns the default.
+- **Evaluation context** — Key-value attributes (`userId`, `country`, `plan`, etc.) passed at evaluation time for rule matching and rollout bucketing.
+- **Percentage rollouts** — Gradually release to a fraction of users. Consistent hashing on a configurable attribute ensures sticky bucketing.
+
+## Two Evaluation Paths
+
+| Path | Runtime | Package | Latency | Auth |
+|------|---------|---------|---------|------|
+| **Binding** (`env.FLAGS`) | Workers only | `@cloudflare/workers-types` | Lowest (no HTTP) | Automatic via binding |
+| **OpenFeature SDK** | Workers, Node.js, browser | `@cloudflare/flagship` + `@openfeature/server-sdk` or `@openfeature/web-sdk` | HTTP per eval (server) or prefetch (client) | API token or binding passthrough |
+
+**Recommendation:** Use the binding inside Workers. Use the SDK when running outside Workers or when you need OpenFeature vendor-neutrality.
+
+## Reading Order
+
+| Task | Read |
+|------|------|
+| Set up Flagship in a Worker | `configuration.md` → `api.md` |
+| Evaluate flags in code | `configuration.md` → `patterns.md` |
+| Manage flags via REST API | `api.md` → `patterns.md` |
+| Design targeting rules & rollouts | `patterns.md` → `gotchas.md` |
+| Debug flag evaluation issues | `gotchas.md` → `api.md` |
+
+REST API note: management endpoints use Cloudflare v4 envelopes (`result`, `result_info`, `errors`) and snake_case fields. The `/evaluate` endpoint is the exception: it is not enveloped and returns OpenFeature-style camelCase.
+
+## In This Reference
+
+- **[api.md](./api.md)** — REST API endpoints, binding methods, OpenFeature SDK, schemas
+- **[configuration.md](./configuration.md)** — Wrangler binding setup, SDK installation, TypeScript types
+- **[patterns.md](./patterns.md)** — Flag CRUD via API, targeting rules, rollouts, OpenFeature usage
+- **[gotchas.md](./gotchas.md)** — Common errors, limits, anti-patterns, troubleshooting
+
+## See Also
+
+- **[Flagship API reference](https://developers.cloudflare.com/api/resources/flagship/)** — Source of truth for REST API paths, envelopes, and response fields
+- **[../workers/](../workers/)** — Workers runtime (Flagship runs inside Workers)
+- **[../kv/](../kv/)** — KV storage (Flagship uses KV infrastructure for flag delivery)
+- **[../wrangler/](../wrangler/)** — Wrangler CLI for deployment and config