memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,206 @@
+# 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,106 @@
+# 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
+```

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

@@ -0,0 +1,126 @@
+# Common Patterns
+
+## URL Transform Options
+
+```
+width=<PX>   height=<PX>   fit=scale-down|contain|cover|crop|pad
+quality=85   format=auto|webp|avif|jpeg|png   dpr=2
+gravity=auto|face|left|right|top|bottom   sharpen=2   blur=10
+rotate=90|180|270   background=white   metadata=none|copyright|keep
+```
+
+## Responsive Images (srcset)
+
+```html
+<img
+  src="https://imagedelivery.net/{hash}/{id}/width=800"
+  srcset=".../{id}/width=400 400w, .../{id}/width=800 800w, .../{id}/width=1200 1200w"
+  sizes="(max-width: 600px) 400px, 800px"
+/>
+```
+
+## Format Negotiation
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const accept = request.headers.get('Accept') || '';
+  const format = /image\/avif/.test(accept) ? 'avif' : /image\/webp/.test(accept) ? 'webp' : 'jpeg';
+  return env.IMAGES.input(buffer).transform({ format, quality: 85 }).output().response();
+}
+```
+
+## Direct Creator Upload
+
+```typescript
+// Backend: Generate upload URL
+const response = await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${env.ACCOUNT_ID}/images/v2/direct_upload`,
+  {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${env.API_TOKEN}` },
+    body: JSON.stringify({ requireSignedURLs: false, metadata: { userId } }),
+  }
+)
+
+// Frontend: Upload to returned uploadURL
+const formData = new FormData()
+formData.append('file', file)
+await fetch(result.uploadURL, { method: 'POST', body: formData })
+// Use: https://imagedelivery.net/{hash}/${result.id}/public
+```
+
+## Transform & Store to R2
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const file = (await request.formData()).get('image') as File;
+  const transformed = await env.IMAGES
+    .input(await file.arrayBuffer())
+    .transform({ width: 800, format: 'avif', quality: 80 })
+    .output();
+  await env.R2.put(`images/${Date.now()}.avif`, transformed.response().body);
+  return Response.json({ success: true });
+}
+```
+
+## Watermarking
+
+```typescript
+const watermark = await env.ASSETS.fetch(new URL('/watermark.png', request.url))
+const result = await env.IMAGES.input(await image.arrayBuffer())
+  .draw(env.IMAGES.input(watermark.body).transform({ width: 100 }), {
+    bottom: 20,
+    right: 20,
+    opacity: 0.7,
+  })
+  .transform({ format: 'avif' })
+  .output()
+return result.response()
+```
+
+## Device-Based Transforms
+
+```typescript
+const ua = request.headers.get('User-Agent') || ''
+const isMobile = /Mobile|Android|iPhone/i.test(ua)
+return env.IMAGES.input(buffer)
+  .transform({ width: isMobile ? 400 : 1200, quality: isMobile ? 75 : 85, format: 'avif' })
+  .output()
+  .response()
+```
+
+## Caching Strategy
+
+```typescript
+async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+  const cache = caches.default;
+  let response = await cache.match(request);
+  if (!response) {
+    response = await env.IMAGES.input(buffer).transform({ width: 800, format: 'avif' }).output().response();
+    response = new Response(response.body, { headers: { ...response.headers, 'Cache-Control': 'public, max-age=86400' } });
+    ctx.waitUntil(cache.put(request, response.clone()));
+  }
+  return response;
+}
+```
+
+## Batch Processing
+
+```typescript
+const results = await Promise.all(
+  images.map((buffer) =>
+    env.IMAGES.input(buffer).transform({ width: 800, fit: 'cover', format: 'avif' }).output()
+  )
+)
+```
+
+## Error Handling
+
+```typescript
+try {
+  return (await env.IMAGES.input(buffer).transform({ width: 800 }).output()).response()
+} catch (error) {
+  console.error('Transform failed:', error)
+  return new Response('Image processing failed', { status: 500 })
+}
+```

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

@@ -0,0 +1,90 @@
+# Cloudflare Workers KV
+
+Globally-distributed, eventually-consistent key-value store optimized for high read volume and low latency.
+
+## Overview
+
+KV provides:
+
+- Eventual consistency (60s global propagation)
+- Read-optimized performance
+- 25 MiB value limit per key
+- Auto-replication to Cloudflare edge
+- Metadata support (1024 bytes)
+
+**Use cases:** Config storage, user sessions, feature flags, caching, A/B testing
+
+## When to Use KV
+
+| Need                        | Recommendation                           |
+| --------------------------- | ---------------------------------------- |
+| Strong consistency          | → [Durable Objects](../durable-objects/) |
+| SQL queries                 | → [D1](../d1/)                           |
+| Object storage (files)      | → [R2](../r2/)                           |
+| High read, low write volume | → KV ✅                                  |
+| Sub-10ms global reads       | → KV ✅                                  |
+
+**Quick comparison:**
+
+| Feature      | KV            | D1              | Durable Objects |
+| ------------ | ------------- | --------------- | --------------- |
+| Consistency  | Eventual      | Strong          | Strong          |
+| Read latency | <10ms         | ~50ms           | <1ms            |
+| Write limit  | 1/s per key   | Unlimited       | Unlimited       |
+| Use case     | Config, cache | Relational data | Coordination    |
+
+## Quick Start
+
+```bash
+wrangler kv namespace create MY_NAMESPACE
+# Add binding to wrangler.jsonc
+```
+
+```typescript
+// Write
+await env.MY_KV.put('key', 'value', { expirationTtl: 300 })
+
+// Read
+const value = await env.MY_KV.get('key')
+const json = await env.MY_KV.get<Config>('config', 'json')
+```
+
+## Core Operations
+
+| Method                      | Purpose          | Returns                            |
+| --------------------------- | ---------------- | ---------------------------------- |
+| `get(key, type?)`           | Single read      | `string \| null`                   |
+| `get(keys, type?)`          | Bulk read (≤100) | `Map<string, T \| null>`           |
+| `put(key, value, options?)` | Write            | `Promise<void>`                    |
+| `delete(key)`               | Delete           | `Promise<void>`                    |
+| `list(options?)`            | List keys        | `{ keys, list_complete, cursor? }` |
+| `getWithMetadata(key)`      | Get + metadata   | `{ value, metadata }`              |
+
+## Consistency Model
+
+- **Write visibility:** Immediate in same location, ≤60s globally
+- **Read path:** Eventually consistent
+- **Write rate:** 1 write/second per key (429 on exceed)
+
+## Reading Order
+
+| Task               | Files to Read                                    |
+| ------------------ | ------------------------------------------------ |
+| Quick start        | README → configuration.md                        |
+| Implement feature  | README → api.md → patterns.md                    |
+| Debug issues       | gotchas.md → api.md                              |
+| Batch operations   | api.md (bulk section) → patterns.md              |
+| Performance tuning | gotchas.md (performance) → patterns.md (caching) |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc setup, namespace creation, TypeScript types
+- [api.md](./api.md) - KV methods, bulk operations, cacheTtl, content types
+- [patterns.md](./patterns.md) - Caching, sessions, rate limiting, A/B testing
+- [gotchas.md](./gotchas.md) - Eventual consistency, concurrent writes, value limits
+
+## See Also
+
+- [workers](../workers/) - Worker runtime for KV access
+- [d1](../d1/) - Use D1 for strong consistency needs
+- [durable-objects](../durable-objects/) - Strongly consistent alternative

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

@@ -0,0 +1,163 @@
+# KV API Reference
+
+## Read Operations
+
+```typescript
+// Single key (string)
+const value = await env.MY_KV.get('user:123')
+
+// JSON type (auto-parsed)
+const config = await env.MY_KV.get<AppConfig>('config', 'json')
+
+// ArrayBuffer for binary
+const buffer = await env.MY_KV.get('image', 'arrayBuffer')
+
+// Stream for large values
+const stream = await env.MY_KV.get('large-file', 'stream')
+
+// With cache TTL (min 60s)
+const value = await env.MY_KV.get('key', { type: 'text', cacheTtl: 300 })
+
+// Bulk get (max 100 keys, counts as 1 operation)
+const keys = ['user:1', 'user:2', 'user:3', 'missing:key']
+const results = await env.MY_KV.get(keys)
+// Returns Map<string, string | null>
+
+console.log(results.get('user:1')) // "John" (if exists)
+console.log(results.get('missing:key')) // null
+
+// Process results with null handling
+for (const [key, value] of results) {
+  if (value !== null) {
+    // Handle found keys
+    console.log(`${key}: ${value}`)
+  }
+}
+
+// TypeScript with generics (type-safe JSON parsing)
+interface UserProfile {
+  name: string
+  email: string
+}
+const profile = await env.USERS.get<UserProfile>('user:123', 'json')
+// profile is typed as UserProfile | null
+if (profile) {
+  console.log(profile.name) // Type-safe access
+}
+
+// Bulk get with type
+const configs = await env.MY_KV.get<Config>(['config:app', 'config:feature'], 'json')
+// Map<string, Config | null>
+```
+
+## Write Operations
+
+```typescript
+// Basic put
+await env.MY_KV.put('key', 'value')
+await env.MY_KV.put('config', JSON.stringify({ theme: 'dark' }))
+
+// With expiration (UNIX timestamp)
+await env.MY_KV.put('session', token, {
+  expiration: Math.floor(Date.now() / 1000) + 3600,
+})
+
+// With TTL (seconds from now, min 60)
+await env.MY_KV.put('cache', data, { expirationTtl: 300 })
+
+// With metadata (max 1024 bytes)
+await env.MY_KV.put('user:profile', userData, {
+  metadata: { version: 2, lastUpdated: Date.now() },
+})
+
+// Combined
+await env.MY_KV.put('temp', value, {
+  expirationTtl: 3600,
+  metadata: { temporary: true },
+})
+```
+
+## Get with Metadata
+
+```typescript
+// Single key
+const result = await env.MY_KV.getWithMetadata('user:profile')
+// { value: string | null, metadata: any | null }
+
+if (result.value && result.metadata) {
+  const { version, lastUpdated } = result.metadata
+}
+
+// Multiple keys (bulk)
+const keys = ['key1', 'key2', 'key3']
+const results = await env.MY_KV.getWithMetadata(keys)
+// Returns Map<string, { value, metadata, cacheStatus? }>
+
+for (const [key, result] of results) {
+  if (result.value) {
+    console.log(`${key}: ${result.value}`)
+    console.log(`Metadata: ${JSON.stringify(result.metadata)}`)
+    // cacheStatus field indicates cache hit/miss (when available)
+  }
+}
+
+// With type
+const result = await env.MY_KV.getWithMetadata<UserData>('user:123', 'json')
+// result: { value: UserData | null, metadata: any | null, cacheStatus?: string }
+```
+
+## Delete Operations
+
+```typescript
+await env.MY_KV.delete('key') // Always succeeds (even if key missing)
+```
+
+## List Operations
+
+```typescript
+// List all
+const keys = await env.MY_KV.list()
+// { keys: [...], list_complete: boolean, cursor?: string }
+
+// With prefix
+const userKeys = await env.MY_KV.list({ prefix: 'user:' })
+
+// Pagination
+let cursor: string | undefined
+let allKeys = []
+do {
+  const result = await env.MY_KV.list({ cursor, limit: 1000 })
+  allKeys.push(...result.keys)
+  cursor = result.cursor
+} while (!result.list_complete)
+```
+
+## Performance Considerations
+
+### Type Selection
+
+| Type          | Use Case                 | Performance              |
+| ------------- | ------------------------ | ------------------------ |
+| `stream`      | Large values (>1MB)      | Fastest - no buffering   |
+| `arrayBuffer` | Binary data              | Fast - single allocation |
+| `text`        | String values            | Medium                   |
+| `json`        | Objects (parse overhead) | Slowest - parsing cost   |
+
+### Parallel Reads
+
+```typescript
+// Efficient parallel reads with Promise.all()
+const [user, settings, cache] = await Promise.all([
+  env.USERS.get('user:123', 'json'),
+  env.SETTINGS.get('config:app', 'json'),
+  env.CACHE.get('data:latest'),
+])
+```
+
+## Error Handling
+
+- **Missing keys:** Return `null` (not an error)
+- **Rate limit (429):** Retry with exponential backoff (see gotchas.md)
+- **Response too large (413):** Values >25MB fail with 413 error
+
+See [gotchas.md](./gotchas.md) for detailed error patterns and solutions.