pi-cloudflare 0.1.0

package/skills/cloudflare/references/pages-functions/api.md

@@ -0,0 +1,143 @@
+# Function API
+
+## EventContext
+
+```typescript
+interface EventContext<Env = any> {
+  request: Request;              // Incoming request
+  functionPath: string;          // Request path
+  waitUntil(promise: Promise<any>): void;  // Background tasks (non-blocking)
+  passThroughOnException(): void;          // Fallback to static on error
+  next(input?: Request | string, init?: RequestInit): Promise<Response>;
+  env: Env;                      // Bindings, vars, secrets
+  params: Record<string, string | string[]>;  // Route params ([user] or [[catchall]])
+  data: any;                     // Middleware shared state
+}
+```
+
+**TypeScript:** See [configuration.md](./configuration.md) for `wrangler types` setup
+
+## Handlers
+
+```typescript
+// Generic (fallback for any method)
+export async function onRequest(ctx: EventContext): Promise<Response> {
+  return new Response('Any method');
+}
+
+// Method-specific (takes precedence over generic)
+export async function onRequestGet(ctx: EventContext): Promise<Response> {
+  return Response.json({ message: 'GET' });
+}
+
+export async function onRequestPost(ctx: EventContext): Promise<Response> {
+  const body = await ctx.request.json();
+  return Response.json({ received: body });
+}
+// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions
+```
+
+## Bindings Reference
+
+| Binding Type | Interface | Config Key | Use Case |
+|--------------|-----------|------------|----------|
+| KV | `KVNamespace` | `kv_namespaces` | Key-value cache, sessions, config |
+| D1 | `D1Database` | `d1_databases` | Relational data, SQL queries |
+| R2 | `R2Bucket` | `r2_buckets` | Large files, user uploads, assets |
+| Durable Objects | `DurableObjectNamespace` | `durable_objects.bindings` | Stateful coordination, websockets |
+| Workers AI | `Ai` | `ai.binding` | LLM inference, embeddings |
+| Vectorize | `VectorizeIndex` | `vectorize` | Vector search, embeddings |
+| Service Binding | `Fetcher` | `services` | Worker-to-worker RPC |
+| Analytics Engine | `AnalyticsEngineDataset` | `analytics_engine_datasets` | Event logging, metrics |
+| Environment Vars | `string` | `vars` | Non-sensitive config |
+
+See [configuration.md](./configuration.md) for wrangler.jsonc examples.
+
+## Bindings
+
+### KV
+
+```typescript
+interface Env { KV: KVNamespace; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  await ctx.env.KV.put('key', 'value', { expirationTtl: 3600 });
+  const val = await ctx.env.KV.get('key', { type: 'json' });
+  const keys = await ctx.env.KV.list({ prefix: 'user:' });
+  return Response.json({ val });
+};
+```
+
+### D1
+
+```typescript
+interface Env { DB: D1Database; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  const user = await ctx.env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(123).first();
+  return Response.json(user);
+};
+```
+
+### R2
+
+```typescript
+interface Env { BUCKET: R2Bucket; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  const obj = await ctx.env.BUCKET.get('file.txt');
+  if (!obj) return new Response('Not found', { status: 404 });
+  await ctx.env.BUCKET.put('file.txt', ctx.request.body);
+  return new Response(obj.body);
+};
+```
+
+### Durable Objects
+
+```typescript
+interface Env { COUNTER: DurableObjectNamespace; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  const stub = ctx.env.COUNTER.get(ctx.env.COUNTER.idFromName('global'));
+  return stub.fetch(ctx.request);
+};
+```
+
+### Workers AI
+
+```typescript
+interface Env { AI: Ai; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  const resp = await ctx.env.AI.run('@cf/meta/llama-3.1-8b-instruct', { prompt: 'Hello' });
+  return Response.json(resp);
+};
+```
+
+### Service Bindings & Env Vars
+
+```typescript
+interface Env { AUTH: Fetcher; API_KEY: string; }
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  // Service binding: forward to another Worker
+  return ctx.env.AUTH.fetch(ctx.request);
+  
+  // Environment variable
+  return Response.json({ key: ctx.env.API_KEY });
+};
+```
+
+## Advanced Mode (env.ASSETS)
+
+When using `_worker.js`, access static assets via `env.ASSETS.fetch()`:
+
+```typescript
+interface Env { ASSETS: Fetcher; KV: KVNamespace; }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith('/api/')) {
+      return Response.json({ data: await env.KV.get('key') });
+    }
+    return env.ASSETS.fetch(request); // Fallback to static
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+**See also:** [configuration.md](./configuration.md) for TypeScript setup and wrangler.jsonc | [patterns.md](./patterns.md) for middleware and auth patterns

package/skills/cloudflare/references/pages-functions/configuration.md

@@ -0,0 +1,122 @@
+# Configuration
+
+## TypeScript Setup
+
+**Generate types from wrangler.jsonc** (replaces deprecated `@cloudflare/workers-types`):
+
+```bash
+npx wrangler types
+```
+
+Creates `worker-configuration.d.ts` with typed `Env` interface based on your bindings.
+
+```typescript
+// functions/api.ts
+export const onRequest: PagesFunction<Env> = async (ctx) => {
+  // ctx.env.KV, ctx.env.DB, etc. are fully typed
+  return Response.json({ ok: true });
+};
+```
+
+**Manual types** (if not using wrangler types):
+
+```typescript
+interface Env {
+  KV: KVNamespace;
+  DB: D1Database;
+  API_KEY: string;
+}
+export const onRequest: PagesFunction<Env> = async (ctx) => { /* ... */ };
+```
+
+## wrangler.jsonc
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "name": "my-pages-app",
+  "pages_build_output_dir": "./dist",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  
+  "vars": { "API_URL": "https://api.example.com" },
+  "kv_namespaces": [{ "binding": "KV", "id": "abc123" }],
+  "d1_databases": [{ "binding": "DB", "database_name": "prod-db", "database_id": "xyz789" }],
+  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-bucket" }],
+  "durable_objects": { "bindings": [{ "name": "COUNTER", "class_name": "Counter", "script_name": "counter-worker" }] },
+  "services": [{ "binding": "AUTH", "service": "auth-worker" }],
+  "ai": { "binding": "AI" },
+  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }],
+  "analytics_engine_datasets": [{ "binding": "ANALYTICS" }]
+}
+```
+
+## Environment Overrides
+
+Top-level → local dev, `env.preview` → preview, `env.production` → production
+
+```jsonc
+{
+  "vars": { "API_URL": "http://localhost:8787" },
+  "env": {
+    "production": { "vars": { "API_URL": "https://api.example.com" } }
+  }
+}
+```
+
+**Note:** If overriding `vars`, `kv_namespaces`, `d1_databases`, etc., ALL must be redefined (non-inheritable)
+
+## Local Secrets (.dev.vars)
+
+**Local dev only** - NOT deployed:
+
+```bash
+# .dev.vars (add to .gitignore)
+SECRET_KEY="my-secret-value"
+```
+
+Accessed via `ctx.env.SECRET_KEY`. Set production secrets:
+```bash
+echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app
+```
+
+## Static Config Files
+
+**_routes.json** - Custom routing:
+```json
+{ "version": 1, "include": ["/api/*"], "exclude": ["/static/*"] }
+```
+
+**_headers** - Static headers:
+```
+/static/*
+  Cache-Control: public, max-age=31536000
+```
+
+**_redirects** - Redirects:
+```
+/old  /new  301
+```
+
+## Local Dev & Deployment
+
+```bash
+# Dev server
+npx wrangler pages dev ./dist
+
+# With bindings
+npx wrangler pages dev ./dist --kv=KV --d1=DB=db-id --r2=BUCKET
+
+# Durable Objects (2 terminals)
+cd do-worker && npx wrangler dev
+cd pages-project && npx wrangler pages dev ./dist --do COUNTER=Counter@do-worker
+
+# Deploy
+npx wrangler pages deploy ./dist
+npx wrangler pages deploy ./dist --branch preview
+
+# Download config
+npx wrangler pages download config my-project
+```
+
+**See also:** [api.md](./api.md) for binding usage examples

package/skills/cloudflare/references/pages-functions/gotchas.md

@@ -0,0 +1,94 @@
+# Gotchas & Debugging
+
+## Error Diagnosis
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| **Function not invoking** | Wrong `/functions` location, wrong extension, or `_routes.json` excludes path | Check `pages_build_output_dir`, use `.js`/`.ts`, verify `_routes.json` |
+| **`ctx.env.BINDING` undefined** | Binding not configured or name mismatch | Add to `wrangler.jsonc`, verify exact name (case-sensitive), redeploy |
+| **TypeScript errors on `ctx.env`** | Missing type definition | Run `wrangler types` or define `interface Env {}` |
+| **Middleware not running** | Wrong filename/location or missing `ctx.next()` | Name exactly `_middleware.js`, export `onRequest`, call `ctx.next()` |
+| **Secrets missing in production** | `.dev.vars` not deployed | `.dev.vars` is local only - set production secrets via dashboard or `wrangler secret put` |
+| **Type mismatch on binding** | Wrong interface type | See [api.md](./api.md) bindings table for correct types |
+| **"KV key not found" but exists** | Key in wrong namespace or env | Verify namespace binding, check preview vs production env |
+| **Function times out** | Synchronous wait or missing `await` | All I/O must be async/await, use `ctx.waitUntil()` for background tasks |
+
+## Common Errors
+
+### TypeScript type errors
+
+**Problem:** `ctx.env.MY_BINDING` shows type error  
+**Cause:** No type definition for `Env`  
+**Solution:** Run `npx wrangler types` or manually define:
+```typescript
+interface Env { MY_BINDING: KVNamespace; }
+export const onRequest: PagesFunction<Env> = async (ctx) => { /* ... */ };
+```
+
+### Secrets not available in production
+
+**Problem:** `ctx.env.SECRET_KEY` is undefined in production  
+**Cause:** `.dev.vars` is local-only, not deployed  
+**Solution:** Set production secrets:
+```bash
+echo "value" | npx wrangler pages secret put SECRET_KEY --project-name=my-app
+```
+
+## Debugging
+
+```typescript
+// Console logging
+export async function onRequest(ctx) {
+  console.log('Request:', ctx.request.method, ctx.request.url);
+  const res = await ctx.next();
+  console.log('Status:', res.status);
+  return res;
+}
+```
+
+```bash
+# Stream real-time logs
+npx wrangler pages deployment tail
+npx wrangler pages deployment tail --status error
+```
+
+```jsonc
+// Source maps (wrangler.jsonc)
+{ "upload_source_maps": true }
+```
+
+## Limits
+
+| Resource | Free | Paid |
+|----------|------|------|
+| CPU time | 10ms | 30s (default), 5min (max) |
+| Memory | 128 MB | 128 MB |
+| Script size | 10 MB compressed | 10 MB compressed |
+| Env vars | 5 KB per var, 64 max | 5 KB per var, 64 max |
+| Requests | 100k/day | Unlimited ($0.50/million) |
+
+## Best Practices
+
+**Performance:** Minimize deps (cold start), use KV for cache/D1 for relational/R2 for large files, set `Cache-Control` headers, batch DB ops, handle errors gracefully
+
+**Security:** Never commit secrets (use `.dev.vars` + gitignore), validate input, sanitize before DB, implement auth middleware, set CORS headers, rate limit per-IP
+
+## Migration
+
+**Workers → Pages Functions:**
+- `export default { fetch(req, env) {} }` → `export function onRequest(ctx) { const { request, env } = ctx; }`
+- Use `_worker.js` for complex routing: `env.ASSETS.fetch(request)` for static files
+
+**Other platforms → Pages:**
+- File-based routing: `/functions/api/users.js` → `/api/users`
+- Dynamic routes: `[param]` not `:param`
+- Replace Node.js deps with Workers APIs or add `nodejs_compat` flag
+
+## Resources
+
+- [Official Docs](https://developers.cloudflare.com/pages/functions/)
+- [Workers APIs](https://developers.cloudflare.com/workers/runtime-apis/)
+- [Examples](https://github.com/cloudflare/pages-example-projects)
+- [Discord](https://discord.gg/cloudflaredev)
+
+**See also:** [configuration.md](./configuration.md) for TypeScript setup | [patterns.md](./patterns.md) for middleware/auth | [api.md](./api.md) for bindings

package/skills/cloudflare/references/pages-functions/patterns.md

@@ -0,0 +1,137 @@
+# Common Patterns
+
+## Background Tasks (waitUntil)
+
+Non-blocking tasks after response sent (analytics, cleanup, webhooks):
+
+```typescript
+export async function onRequest(ctx: EventContext<Env>) {
+  const res = Response.json({ success: true });
+  
+  ctx.waitUntil(ctx.env.KV.put('last-visit', new Date().toISOString()));
+  ctx.waitUntil(Promise.all([
+    ctx.env.ANALYTICS.writeDataPoint({ event: 'view' }),
+    fetch('https://webhook.site/...', { method: 'POST' })
+  ]));
+  
+  return res; // Returned immediately
+}
+```
+
+## Middleware & Auth
+
+```typescript
+// functions/_middleware.js (global) or functions/users/_middleware.js (scoped)
+export async function onRequest(ctx) {
+  try { return await ctx.next(); } 
+  catch (err) { return new Response(err.message, { status: 500 }); }
+}
+
+// Chained: export const onRequest = [errorHandler, auth, logger];
+
+// Auth
+async function auth(ctx: EventContext<Env>) {
+  const token = ctx.request.headers.get('authorization')?.replace('Bearer ', '');
+  if (!token) return new Response('Unauthorized', { status: 401 });
+  const session = await ctx.env.KV.get(`session:${token}`);
+  if (!session) return new Response('Invalid', { status: 401 });
+  ctx.data.user = JSON.parse(session);
+  return ctx.next();
+}
+```
+
+## CORS & Rate Limiting
+
+```typescript
+// CORS middleware
+const cors = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Methods': 'GET, POST' };
+export async function onRequestOptions() { return new Response(null, { headers: cors }); }
+export async function onRequest(ctx) {
+  const res = await ctx.next();
+  Object.entries(cors).forEach(([k, v]) => res.headers.set(k, v));
+  return res;
+}
+
+// Rate limiting (KV-based)
+async function rateLimit(ctx: EventContext<Env>) {
+  const ip = ctx.request.headers.get('CF-Connecting-IP') || 'unknown';
+  const count = parseInt(await ctx.env.KV.get(`rate:${ip}`) || '0');
+  if (count >= 100) return new Response('Rate limited', { status: 429 });
+  await ctx.env.KV.put(`rate:${ip}`, (count + 1).toString(), { expirationTtl: 3600 });
+  return ctx.next();
+}
+```
+
+## Forms, Caching, Redirects
+
+```typescript
+// JSON & file upload
+export async function onRequestPost(ctx) {
+  const ct = ctx.request.headers.get('content-type') || '';
+  if (ct.includes('application/json')) return Response.json(await ctx.request.json());
+  if (ct.includes('multipart/form-data')) {
+    const file = (await ctx.request.formData()).get('file') as File;
+    await ctx.env.BUCKET.put(file.name, file.stream());
+    return Response.json({ uploaded: file.name });
+  }
+}
+
+// Cache API
+export async function onRequest(ctx) {
+  let res = await caches.default.match(ctx.request);
+  if (!res) {
+    res = new Response('Data');
+    res.headers.set('Cache-Control', 'public, max-age=3600');
+    ctx.waitUntil(caches.default.put(ctx.request, res.clone()));
+  }
+  return res;
+}
+
+// Redirects
+export async function onRequest(ctx) {
+  if (new URL(ctx.request.url).pathname === '/old') {
+    return Response.redirect(new URL('/new', ctx.request.url), 301);
+  }
+  return ctx.next();
+}
+```
+
+## Testing
+
+**Unit tests** (Vitest + cloudflare:test):
+```typescript
+import { env } from 'cloudflare:test';
+import { it, expect } from 'vitest';
+import { onRequest } from '../functions/api';
+
+it('returns JSON', async () => {
+  const req = new Request('http://localhost/api');
+  const ctx = { request: req, env, params: {}, data: {} } as EventContext;
+  const res = await onRequest(ctx);
+  expect(res.status).toBe(200);
+});
+```
+
+**Integration:** `wrangler pages dev` + Playwright/Cypress
+
+## Advanced Mode (_worker.js)
+
+Use `_worker.js` for complex routing (replaces `/functions`):
+
+```typescript
+interface Env { ASSETS: Fetcher; KV: KVNamespace; }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith('/api/')) {
+      return Response.json({ data: await env.KV.get('key') });
+    }
+    return env.ASSETS.fetch(request); // Static files
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+**When:** Existing Worker, framework-generated (Next.js/SvelteKit), custom routing logic
+
+**See also:** [api.md](./api.md) for `env.ASSETS.fetch()` | [gotchas.md](./gotchas.md) for debugging

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

@@ -0,0 +1,90 @@
+# Cloudflare Pipelines
+
+Streaming ingest: receive events over HTTP/Workers/Logpush, transform with SQL, write to R2 as Iceberg tables or Parquet/JSON files.
+
+## Documentation
+
+This reference is a fast-start with verified code and gotchas. For limits, settings, full SQL syntax, and pricing, **retrieve the live docs** — use the Cloudflare MCP `docs` tool if available, otherwise `webfetch` the URL. Docs are source of truth over this file.
+
+| Topic | URL |
+|-------|-----|
+| Overview / getting started | `https://developers.cloudflare.com/pipelines/getting-started/` |
+| Streams (write, manage, Logpush) | `https://developers.cloudflare.com/pipelines/streams/` |
+| Sinks | `https://developers.cloudflare.com/pipelines/sinks/` |
+| Pipelines & SQL transforms | `https://developers.cloudflare.com/pipelines/pipelines/` |
+| SQL reference (statements, types) | `https://developers.cloudflare.com/pipelines/sql-reference/` |
+| Wrangler commands | `https://developers.cloudflare.com/pipelines/reference/wrangler-commands/` |
+| Terraform | `https://developers.cloudflare.com/pipelines/reference/terraform/` |
+| Limits | `https://developers.cloudflare.com/pipelines/platform/limits/` |
+| Pricing | `https://developers.cloudflare.com/pipelines/platform/pricing/` |
+| Metrics (GraphQL) | `https://developers.cloudflare.com/pipelines/observability/metrics/` |
+
+## Three Components
+
+```
+Sources → Stream → Pipeline (SQL) → Sink → R2
+          ↑          ↓                 ↓
+   HTTP / Workers / Transform     Iceberg (Data Catalog)
+   Logpush          (row-level)   or Parquet/JSON files
+```
+
+| Component | Purpose |
+|-----------|---------|
+| **Stream** | Receives events (HTTP endpoint, Worker binding, or Logpush). Structured (schema-validated) or unstructured. |
+| **Pipeline** | SQL connecting a stream to a sink. Row-level transforms only — no GROUP BY/aggregation. |
+| **Sink** | Writes to R2 — Iceberg via Data Catalog, or raw Parquet/JSON. |
+
+**Status:** Open beta (Workers Paid for production). Pricing announced; verify billing status in docs.
+
+## Quick Start
+
+```bash
+# Interactive — creates stream + sink + pipeline, optionally bucket + catalog
+npx wrangler pipelines setup
+```
+
+Minimal Worker producer:
+```typescript
+interface Env { MY_STREAM: Pipeline; }
+
+export default {
+  async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    ctx.waitUntil(env.MY_STREAM.send([{ event_id: crypto.randomUUID(), amount: 29.99 }]));
+    return new Response("OK");
+  }
+} satisfies ExportedHandler<Env>;
+```
+
+## Which Sink Type?
+
+```
+Need SQL queries / ACID / time-travel on the data?
+  → R2 Data Catalog (Iceberg)   ✅ R2 SQL, schema evolution   ❌ more setup
+
+Just archival / external tools (Spark, Athena)?
+  → R2 raw files (Parquet/JSON) ✅ simple, partitioned files  ❌ no built-in SQL
+```
+
+## Critical Behaviors (read before building)
+
+These are non-obvious and prevent most failures — see [gotchas.md](gotchas.md) for detail.
+
+- **Everything is immutable after creation** — stream schema, pipeline SQL, sink config. To change, delete and recreate.
+- **Sinks create their own table** — they cannot target an existing Iceberg table.
+- **`__ingest_ts` is added automatically** (TIMESTAMP, partitioned by day). Don't define it in your schema.
+- **Data isn't queryable immediately** — first flush takes **3–7 minutes** (warm-up + table creation) even with a short roll interval.
+- **Schema validation is deferred** — invalid events are accepted then silently dropped. Monitor via GraphQL error metrics.
+- **Binding field renamed `pipeline` → `stream`** (June 2026); old field still accepted.
+
+## Reading Order
+
+1. [configuration.md](configuration.md) — schema, streams, sinks, pipelines (CLI + REST + Terraform), bindings
+2. [api.md](api.md) — `send()`, HTTP ingest, REST API, pipeline SQL, lifecycle states
+3. [patterns.md](patterns.md) — fire-and-forget, validation, Logpush, observability, end-to-end
+4. [gotchas.md](gotchas.md) — silent drops, immutability, REST≠CLI field names
+
+## See Also
+
+- [r2-data-catalog](../r2-data-catalog/) — Iceberg sink destination
+- [r2-sql](../r2-sql/) — query the ingested data
+- [r2](../r2/) · [queues](../queues/) · [workers](../workers/)