pi-cloudflare 0.1.0

package/skills/cloudflare/references/hyperdrive/patterns.md

@@ -0,0 +1,190 @@
+# Patterns
+
+See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md).
+
+## High-Traffic Read-Heavy
+
+```typescript
+const sql = postgres(env.HYPERDRIVE.connectionString, {max: 5, prepare: true});
+
+// Cacheable: popular content
+const posts = await sql`SELECT * FROM posts WHERE published = true ORDER BY views DESC LIMIT 20`;
+
+// Cacheable: user profiles
+const [user] = await sql`SELECT id, username, bio FROM users WHERE id = ${userId}`;
+```
+
+**Benefits:** Trending/profiles cached (60s), connection pooling handles spikes.
+
+## Mixed Read/Write
+
+```typescript
+interface Env {
+  HYPERDRIVE_CACHED: Hyperdrive;    // max_age=120
+  HYPERDRIVE_REALTIME: Hyperdrive;  // caching disabled
+}
+
+// Reads: cached
+if (req.method === "GET") {
+  const sql = postgres(env.HYPERDRIVE_CACHED.connectionString, {prepare: true});
+  const products = await sql`SELECT * FROM products WHERE category = ${cat}`;
+}
+
+// Writes: no cache (immediate consistency)
+if (req.method === "POST") {
+  const sql = postgres(env.HYPERDRIVE_REALTIME.connectionString, {prepare: true});
+  await sql`INSERT INTO orders ${sql(data)}`;
+}
+```
+
+## Analytics Dashboard
+
+```typescript
+const client = new Client({connectionString: env.HYPERDRIVE.connectionString});
+await client.connect();
+
+// Aggregate queries cached (use fixed timestamps for caching)
+const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+const dailyStats = await client.query(`
+  SELECT DATE(created_at) as date, COUNT(*) as orders, SUM(amount) as revenue
+  FROM orders WHERE created_at >= $1
+  GROUP BY DATE(created_at) ORDER BY date DESC
+`, [thirtyDaysAgo]);
+
+const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+const topProducts = await client.query(`
+  SELECT p.name, COUNT(oi.id) as count, SUM(oi.quantity * oi.price) as revenue
+  FROM order_items oi JOIN products p ON oi.product_id = p.id
+  WHERE oi.created_at >= $1
+  GROUP BY p.id, p.name ORDER BY revenue DESC LIMIT 10
+`, [sevenDaysAgo]);
+```
+
+**Benefits:** Expensive aggregations cached (avoid NOW() for cacheability), dashboard instant, reduced DB load.
+
+## Multi-Tenant
+
+```typescript
+const tenantId = req.headers.get("X-Tenant-ID");
+const sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});
+
+// Tenant-scoped queries cached separately
+const docs = await sql`
+  SELECT * FROM documents 
+  WHERE tenant_id = ${tenantId} AND deleted_at IS NULL
+  ORDER BY updated_at DESC LIMIT 50
+`;
+```
+
+**Benefits:** Per-tenant caching, shared connection pool, protects DB from multi-tenant load.
+
+## Geographically Distributed
+
+```typescript
+// Worker runs at edge nearest user
+// Connection setup at edge (fast), pooling near DB (efficient)
+const sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});
+const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`;
+
+return Response.json({
+  user,
+  serverRegion: req.cf?.colo,  // Edge location
+});
+```
+
+**Benefits:** Edge setup + DB pooling = global → single-region DB without replication.
+
+## Multi-Query + Smart Placement
+
+For Workers making **multiple queries** per request, enable Smart Placement to execute near DB:
+
+```jsonc
+// wrangler.jsonc
+{
+  "placement": {"mode": "smart"},
+  "hyperdrive": [{"binding": "HYPERDRIVE", "id": "<ID>"}]
+}
+```
+
+```typescript
+const sql = postgres(env.HYPERDRIVE.connectionString, {prepare: true});
+
+// Multiple queries benefit from Smart Placement
+const [user] = await sql`SELECT * FROM users WHERE id = ${userId}`;
+const orders = await sql`SELECT * FROM orders WHERE user_id = ${userId} ORDER BY created_at DESC LIMIT 10`;
+const stats = await sql`SELECT COUNT(*) as total, SUM(amount) as spent FROM orders WHERE user_id = ${userId}`;
+
+return Response.json({user, orders, stats});
+```
+
+**Benefits:** Worker executes near DB → reduces latency for each query. Without Smart Placement, each query round-trips from edge.
+
+## Connection Pooling
+
+Operates in **transaction mode**: connection acquired per transaction, `RESET` on return.
+
+**SET statements:**
+```typescript
+// ✅ Within transaction
+await client.query("BEGIN");
+await client.query("SET work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");  // Uses SET
+await client.query("COMMIT");  // RESET after
+
+// ✅ Single statement
+await client.query("SET work_mem = '256MB'; SELECT * FROM large_table");
+
+// ❌ Across queries (may get different connection)
+await client.query("SET work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");  // SET not applied
+```
+
+**Best practices:**
+```typescript
+// ❌ Long transactions block pooling
+await client.query("BEGIN");
+await processThousands();  // Connection held entire time
+await client.query("COMMIT");
+
+// ✅ Short transactions
+await client.query("BEGIN");
+await client.query("UPDATE users SET status = $1 WHERE id = $2", [status, id]);
+await client.query("COMMIT");
+
+// ✅ SET LOCAL within transaction
+await client.query("BEGIN");
+await client.query("SET LOCAL work_mem = '256MB'");
+await client.query("SELECT * FROM large_table");
+await client.query("COMMIT");
+```
+
+## Performance Tips
+
+**Enable prepared statements (required for caching):**
+```typescript
+const sql = postgres(connectionString, {prepare: true});  // Default, enables caching
+```
+
+**Optimize connection settings:**
+```typescript
+const sql = postgres(connectionString, {
+  max: 5,             // Stay under Workers' 6 connection limit
+  fetch_types: false, // Reduce latency if not using arrays
+  idle_timeout: 60,   // Match Worker lifetime
+});
+```
+
+**Write cache-friendly queries:**
+```typescript
+// ✅ Cacheable (deterministic)
+await sql`SELECT * FROM products WHERE category = 'electronics' LIMIT 10`;
+
+// ❌ Not cacheable (volatile NOW())
+await sql`SELECT * FROM logs WHERE created_at > NOW()`;
+
+// ✅ Cacheable (parameterized timestamp)
+const ts = Date.now();
+await sql`SELECT * FROM logs WHERE created_at > ${ts}`;
+```
+
+See [gotchas.md](./gotchas.md) for limits, troubleshooting.

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

@@ -0,0 +1,61 @@
+# Cloudflare Images Skill Reference
+
+**Cloudflare Images** is an end-to-end image management solution providing storage, transformation, optimization, and delivery at scale via Cloudflare's global network.
+
+## Quick Decision Tree
+
+**Need to:**
+- **Transform in Worker?** → [api.md](api.md#workers-binding-api-2026-primary-method) (Workers Binding API)
+- **Upload from Worker?** → [api.md](api.md#upload-from-worker) (REST API)
+- **Upload from client?** → [patterns.md](patterns.md#upload-from-client-direct-creator-upload) (Direct Creator Upload)
+- **Set up variants?** → [configuration.md](configuration.md#variants-configuration)
+- **Serve responsive images?** → [patterns.md](patterns.md#responsive-images)
+- **Add watermarks?** → [patterns.md](patterns.md#watermarking)
+- **Fix errors?** → [gotchas.md](gotchas.md#common-errors)
+
+## Reading Order
+
+**For building image upload/transform feature:**
+1. [configuration.md](configuration.md) - Setup Workers binding
+2. [api.md](api.md#workers-binding-api-2026-primary-method) - Learn transform API
+3. [patterns.md](patterns.md#upload-from-client-direct-creator-upload) - Direct upload pattern
+4. [gotchas.md](gotchas.md) - Check limits and errors
+
+**For URL-based transforms:**
+1. [configuration.md](configuration.md#variants-configuration) - Create variants
+2. [api.md](api.md#url-transform-api) - URL syntax
+3. [patterns.md](patterns.md#responsive-images) - Responsive patterns
+
+**For troubleshooting:**
+1. [gotchas.md](gotchas.md#common-errors) - Error messages
+2. [gotchas.md](gotchas.md#limits) - Size/format limits
+
+## Core Methods
+
+| Method | Use Case | Location |
+|--------|----------|----------|
+| `env.IMAGES.input().transform()` | Transform in Worker | [api.md:11](api.md) |
+| REST API `/images/v1` | Upload images | [api.md:57](api.md) |
+| Direct Creator Upload | Client-side upload | [api.md:127](api.md) |
+| URL transforms | Static image delivery | [api.md:112](api.md) |
+
+## In This Reference
+
+- **[api.md](api.md)** - Complete API: Workers binding, REST endpoints, URL transforms
+- **[configuration.md](configuration.md)** - Setup: wrangler.toml, variants, auth, signed URLs
+- **[patterns.md](patterns.md)** - Patterns: responsive images, watermarks, format negotiation, caching
+- **[gotchas.md](gotchas.md)** - Troubleshooting: limits, errors, best practices
+
+## Key Features
+
+- **Automatic Optimization** - AVIF/WebP format negotiation
+- **On-the-fly Transforms** - Resize, crop, blur, sharpen via URL or API
+- **Workers Binding** - Transform images in Workers (2026 primary method)
+- **Direct Upload** - Secure client-side uploads without backend proxy
+- **Global Delivery** - Cached at 300+ Cloudflare data centers
+- **Watermarking** - Overlay images programmatically
+
+## See Also
+
+- [Official Docs](https://developers.cloudflare.com/images/)
+- [Workers Examples](https://developers.cloudflare.com/images/tutorials/)

package/skills/cloudflare/references/images/api.md

@@ -0,0 +1,96 @@
+# API Reference
+
+## Workers Binding API
+
+```toml
+# wrangler.toml
+[images]
+binding = "IMAGES"
+```
+
+### Transform Images
+
+```typescript
+const imageResponse = await env.IMAGES
+  .input(fileBuffer)
+  .transform({ width: 800, height: 600, fit: "cover", quality: 85, format: "avif" })
+  .output();
+return imageResponse.response();
+```
+
+### Transform Options
+
+```typescript
+interface TransformOptions {
+  width?: number;        height?: number;
+  fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
+  quality?: number;      // 1-100
+  format?: "avif" | "webp" | "jpeg" | "png";
+  dpr?: number;          // 1-3
+  gravity?: "auto" | "left" | "right" | "top" | "bottom" | "face" | string;
+  sharpen?: number;      // 0-10
+  blur?: number;         // 1-250
+  rotate?: 90 | 180 | 270;
+  background?: string;   // CSS color for pad
+  metadata?: "none" | "copyright" | "keep";
+  brightness?: number;   contrast?: number;   gamma?: number;  // 0-2
+}
+```
+
+### Draw/Watermark
+
+```typescript
+await env.IMAGES.input(baseImage)
+  .draw(env.IMAGES.input(watermark).transform({ width: 100 }), { top: 10, left: 10, opacity: 0.8 })
+  .output();
+```
+
+## REST API
+
+### Upload Image
+
+```bash
+curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  -H "Authorization: Bearer {token}" -F file=@image.jpg -F metadata='{"key":"value"}'
+```
+
+### Other Operations
+
+```bash
+GET  /accounts/{account_id}/images/v1/{image_id}      # Get details
+DELETE /accounts/{account_id}/images/v1/{image_id}   # Delete
+GET  /accounts/{account_id}/images/v1?page=1         # List
+```
+
+## URL Transform API
+
+```
+https://imagedelivery.net/{hash}/{id}/width=800,height=600,fit=cover,format=avif
+```
+
+**Params:** `w=`, `h=`, `fit=`, `q=`, `f=`, `dpr=`, `gravity=`, `sharpen=`, `blur=`, `rotate=`, `background=`, `metadata=`
+
+## Direct Creator Upload
+
+```typescript
+// 1. Get upload URL (backend)
+const { result } = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v2/direct_upload`,
+  { method: 'POST', headers: { 'Authorization': `Bearer ${token}` },
+    body: JSON.stringify({ requireSignedURLs: false }) }
+).then(r => r.json());
+
+// 2. Client uploads to result.uploadURL
+const formData = new FormData();
+formData.append('file', file);
+await fetch(result.uploadURL, { method: 'POST', body: formData });
+```
+
+## Error Codes
+
+| Code | Message | Solution |
+|------|---------|----------|
+| 5400 | Invalid format | Use JPEG, PNG, GIF, WebP |
+| 5401 | Too large | Max 100MB |
+| 5403 | Invalid transform | Check params |
+| 9413 | Rate limit | Implement backoff |

package/skills/cloudflare/references/images/configuration.md

@@ -0,0 +1,211 @@
+# Configuration
+
+## Wrangler Integration
+
+### Workers Binding Setup
+
+Add to `wrangler.toml`:
+
+```toml
+name = "my-image-worker"
+main = "src/index.ts"
+compatibility_date = "2024-01-01"
+
+[images]
+binding = "IMAGES"
+```
+
+Access in Worker:
+
+```typescript
+interface Env {
+  IMAGES: ImageBinding;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return await env.IMAGES
+      .input(imageBuffer)
+      .transform({ width: 800 })
+      .output()
+      .response();
+  }
+};
+```
+
+### Upload via Script
+
+Wrangler doesn't have built-in Images commands, use REST API:
+
+```typescript
+// scripts/upload-image.ts
+import fs from 'fs';
+import FormData from 'form-data';
+
+async function uploadImage(filePath: string) {
+  const accountId = process.env.CLOUDFLARE_ACCOUNT_ID!;
+  const apiToken = process.env.CLOUDFLARE_API_TOKEN!;
+  
+  const formData = new FormData();
+  formData.append('file', fs.createReadStream(filePath));
+  
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/images/v1`,
+    {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${apiToken}`,
+      },
+      body: formData,
+    }
+  );
+  
+  const result = await response.json();
+  console.log('Uploaded:', result);
+}
+
+uploadImage('./photo.jpg');
+```
+
+### Environment Variables
+
+Store account hash for URL construction:
+
+```toml
+[vars]
+IMAGES_ACCOUNT_HASH = "your-account-hash"
+ACCOUNT_ID = "your-account-id"
+```
+
+Access in Worker:
+
+```typescript
+const imageUrl = `https://imagedelivery.net/${env.IMAGES_ACCOUNT_HASH}/${imageId}/public`;
+```
+
+## Variants Configuration
+
+Variants are named presets for transformations.
+
+### Create Variant (Dashboard)
+
+1. Navigate to Images → Variants
+2. Click "Create Variant"
+3. Set name (e.g., `thumbnail`)
+4. Configure: `width=200,height=200,fit=cover`
+
+### Create Variant (API)
+
+```bash
+curl -X POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1/variants \
+  -H "Authorization: Bearer {api_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "thumbnail",
+    "options": {
+      "width": 200,
+      "height": 200,
+      "fit": "cover"
+    },
+    "neverRequireSignedURLs": true
+  }'
+```
+
+### Use Variant
+
+```
+https://imagedelivery.net/{account_hash}/{image_id}/thumbnail
+```
+
+### Common Variant Presets
+
+```json
+{
+  "thumbnail": {
+    "width": 200,
+    "height": 200,
+    "fit": "cover"
+  },
+  "avatar": {
+    "width": 128,
+    "height": 128,
+    "fit": "cover",
+    "gravity": "face"
+  },
+  "hero": {
+    "width": 1920,
+    "height": 1080,
+    "fit": "cover",
+    "quality": 90
+  },
+  "mobile": {
+    "width": 640,
+    "fit": "scale-down",
+    "quality": 80,
+    "format": "avif"
+  }
+}
+```
+
+## Authentication
+
+### API Token (Recommended)
+
+Generate at: Dashboard → My Profile → API Tokens
+
+Required permissions:
+- Account → Cloudflare Images → Edit
+
+```bash
+curl -H "Authorization: Bearer {api_token}" \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1
+```
+
+### API Key (Legacy)
+
+```bash
+curl -H "X-Auth-Email: {email}" \
+     -H "X-Auth-Key: {api_key}" \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1
+```
+
+## Signed URLs
+
+For private images, enable signed URLs:
+
+```bash
+# Upload with signed URLs required
+curl -X POST \
+  https://api.cloudflare.com/client/v4/accounts/{account_id}/images/v1 \
+  -H "Authorization: Bearer {api_token}" \
+  -F file=@private.jpg \
+  -F requireSignedURLs=true
+```
+
+Generate signed URL:
+
+```typescript
+import { createHmac } from 'crypto';
+
+function signUrl(imageId: string, variant: string, expiry: number, key: string): string {
+  const path = `/${imageId}/${variant}`;
+  const toSign = `${path}${expiry}`;
+  const signature = createHmac('sha256', key)
+    .update(toSign)
+    .digest('hex');
+  
+  return `https://imagedelivery.net/{hash}${path}?exp=${expiry}&sig=${signature}`;
+}
+
+// Sign URL valid for 1 hour
+const signedUrl = signUrl('image-id', 'public', Date.now() + 3600, env.SIGNING_KEY);
+```
+
+## Local Development
+
+```bash
+npx wrangler dev --remote
+```
+
+Must use `--remote` for Images binding access.

package/skills/cloudflare/references/images/gotchas.md

@@ -0,0 +1,99 @@
+# Gotchas & Best Practices
+
+## Fit Modes
+
+| Mode | Best For | Behavior |
+|------|----------|----------|
+| `cover` | Hero images, thumbnails | Fills space, crops excess |
+| `contain` | Product images, artwork | Preserves full image, may add padding |
+| `scale-down` | User uploads | Never enlarges |
+| `crop` | Precise crops | Uses gravity |
+| `pad` | Fixed aspect ratio | Adds background |
+
+## Format Selection
+
+```typescript
+format: 'auto' // Recommended - negotiates best format
+```
+
+**Support:** AVIF (Chrome 85+, Firefox 93+, Safari 16.4+), WebP (Chrome 23+, Firefox 65+, Safari 14+)
+
+## Quality Settings
+
+| Use Case | Quality |
+|----------|---------|
+| Thumbnails | 75-80 |
+| Standard | 85 (default) |
+| High-quality | 90-95 |
+
+## Common Errors
+
+### 5403: "Image transformation failed"
+- Verify `width`/`height` ≤ 12000
+- Check `quality` 1-100, `dpr` 1-3
+- Don't combine incompatible options
+
+### 9413: "Rate limit exceeded"
+Implement caching and exponential backoff:
+```typescript
+for (let i = 0; i < 3; i++) {
+  try { return await env.IMAGES.input(buffer).transform({...}).output(); }
+  catch { await new Promise(r => setTimeout(r, 2 ** i * 1000)); }
+}
+```
+
+### 5401: "Image too large"
+Pre-process images before upload (max 100MB, 12000×12000px)
+
+### 5400: "Invalid image format"
+Supported: JPEG, PNG, GIF, WebP, AVIF, SVG
+
+### 401/403: "Unauthorized"
+Verify API token has `Cloudflare Images → Edit` permission
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Max input size | 100MB |
+| Max dimensions | 12000×12000px |
+| Quality range | 1-100 |
+| DPR range | 1-3 |
+| API rate limit | ~1200 req/min |
+
+## AVIF Gotchas
+
+- **Slower encoding**: First request may have higher latency
+- **Browser detection**:
+```typescript
+const format = /image\/avif/.test(request.headers.get('Accept') || '') ? 'avif' : 'webp';
+```
+
+## Anti-Patterns
+
+```typescript
+// ❌ No caching - transforms every request
+return env.IMAGES.input(buffer).transform({...}).output().response();
+
+// ❌ cover without both dimensions
+transform({ width: 800, fit: 'cover' })
+
+// ✅ Always set both for cover
+transform({ width: 800, height: 600, fit: 'cover' })
+
+// ❌ Exposes API token to client
+// ✅ Use Direct Creator Upload (patterns.md)
+```
+
+## Debugging
+
+```typescript
+// Check response headers
+console.log('Content-Type:', response.headers.get('Content-Type'));
+
+// Test with curl
+// curl -I "https://imagedelivery.net/{hash}/{id}/width=800,format=avif"
+
+// Monitor logs
+// npx wrangler tail
+```