memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,220 @@
+# Queues Patterns & Best Practices
+
+## Async Task Processing
+
+```typescript
+// Producer: Accept request, queue work
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const { userId, reportType } = await request.json()
+    await env.REPORT_QUEUE.send({ userId, reportType, requestedAt: Date.now() })
+    return Response.json({ message: 'Report queued', status: 'pending' })
+  },
+}
+
+// Consumer: Process reports
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      const { userId, reportType } = msg.body
+      const report = await generateReport(userId, reportType, env)
+      await env.REPORTS_BUCKET.put(`${userId}/${reportType}.pdf`, report)
+      msg.ack()
+    }
+  },
+}
+```
+
+## Buffering API Calls
+
+```typescript
+// Producer: Queue log entries
+ctx.waitUntil(env.LOGS_QUEUE.send({
+  method: request.method,
+  url: request.url,
+  timestamp: Date.now()
+}));
+
+// Consumer: Batch write to external API
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  const logs = batch.messages.map(m => m.body);
+  await fetch(env.LOG_ENDPOINT, { method: 'POST', body: JSON.stringify({ logs }) });
+  batch.ackAll();
+}
+```
+
+## Rate Limiting Upstream
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    try {
+      await callRateLimitedAPI(msg.body);
+      msg.ack();
+    } catch (error) {
+      if (error.status === 429) {
+        const retryAfter = parseInt(error.headers.get('Retry-After') || '60');
+        msg.retry({ delaySeconds: retryAfter });
+      } else throw error;
+    }
+  }
+}
+```
+
+## Event-Driven Workflows
+
+```typescript
+// R2 event → Queue → Worker
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      const event = msg.body
+      if (event.action === 'PutObject') {
+        await processNewFile(event.object.key, env)
+      } else if (event.action === 'DeleteObject') {
+        await cleanupReferences(event.object.key, env)
+      }
+      msg.ack()
+    }
+  },
+}
+```
+
+## Dead Letter Queue Pattern
+
+```typescript
+// Main queue: After max_retries, goes to DLQ automatically
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      try {
+        await riskyOperation(msg.body)
+        msg.ack()
+      } catch (error) {
+        console.error(`Failed after ${msg.attempts} attempts:`, error)
+      }
+    }
+  },
+}
+
+// DLQ consumer: Log and store failed messages
+export default {
+  async queue(batch: MessageBatch, env: Env): Promise<void> {
+    for (const msg of batch.messages) {
+      await env.FAILED_KV.put(msg.id, JSON.stringify(msg.body))
+      msg.ack()
+    }
+  },
+}
+```
+
+## Priority Queues
+
+High priority: `max_batch_size: 5, max_batch_timeout: 1`. Low priority: `max_batch_size: 100, max_batch_timeout: 30`.
+
+## Delayed Job Processing
+
+```typescript
+await env.EMAIL_QUEUE.send({ to, template, userId }, { delaySeconds: 3600 })
+```
+
+## Fan-out Pattern
+
+```typescript
+async fetch(request: Request, env: Env): Promise<Response> {
+  const event = await request.json();
+
+  // Send to multiple queues for parallel processing
+  await Promise.all([
+    env.ANALYTICS_QUEUE.send(event),
+    env.NOTIFICATIONS_QUEUE.send(event),
+    env.AUDIT_LOG_QUEUE.send(event)
+  ]);
+
+  return Response.json({ status: 'processed' });
+}
+```
+
+## Idempotency Pattern
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    // Check if already processed
+    const processed = await env.PROCESSED_KV.get(msg.id);
+    if (processed) {
+      msg.ack();
+      continue;
+    }
+
+    await processMessage(msg.body);
+    await env.PROCESSED_KV.put(msg.id, '1', { expirationTtl: 86400 });
+    msg.ack();
+  }
+}
+```
+
+## Integration: D1 Batch Writes
+
+```typescript
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  // Collect all inserts for single D1 batch
+  const statements = batch.messages.map(msg =>
+    env.DB.prepare('INSERT INTO events (id, data, created) VALUES (?, ?, ?)')
+      .bind(msg.id, JSON.stringify(msg.body), Date.now())
+  );
+
+  try {
+    await env.DB.batch(statements);
+    batch.ackAll();
+  } catch (error) {
+    console.error('D1 batch failed:', error);
+    batch.retryAll({ delaySeconds: 60 });
+  }
+}
+```
+
+## Integration: Workflows
+
+```typescript
+// Queue triggers Workflow for long-running tasks
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    try {
+      const instance = await env.MY_WORKFLOW.create({
+        id: msg.id,
+        params: msg.body
+      });
+      console.log('Workflow started:', instance.id);
+      msg.ack();
+    } catch (error) {
+      msg.retry({ delaySeconds: 30 });
+    }
+  }
+}
+```
+
+## Integration: Durable Objects
+
+```typescript
+// Queue distributes work to Durable Objects by ID
+async queue(batch: MessageBatch, env: Env): Promise<void> {
+  for (const msg of batch.messages) {
+    const { userId, action } = msg.body;
+
+    // Route to user-specific DO
+    const id = env.USER_DO.idFromName(userId);
+    const stub = env.USER_DO.get(id);
+
+    try {
+      await stub.fetch(new Request('https://do/process', {
+        method: 'POST',
+        body: JSON.stringify({ action, messageId: msg.id })
+      }));
+      msg.ack();
+    } catch (error) {
+      msg.retry({ delaySeconds: 60 });
+    }
+  }
+}
+```

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

@@ -0,0 +1,97 @@
+# Cloudflare R2 Object Storage
+
+S3-compatible object storage with zero egress fees, optimized for large file storage and delivery.
+
+## Overview
+
+R2 provides:
+
+- S3-compatible API (Workers API + S3 REST)
+- Zero egress fees globally
+- Strong consistency for writes/deletes
+- Storage classes (Standard/Infrequent Access)
+- SSE-C encryption support
+
+**Use cases:** Media storage, backups, static assets, user uploads, data lakes
+
+## Quick Start
+
+```bash
+wrangler r2 bucket create my-bucket --location=enam
+wrangler r2 object put my-bucket/file.txt --file=./local.txt
+```
+
+```typescript
+// Upload
+await env.MY_BUCKET.put(key, data, {
+  httpMetadata: { contentType: 'image/jpeg' },
+})
+
+// Download
+const object = await env.MY_BUCKET.get(key)
+if (object) return new Response(object.body)
+```
+
+## Core Operations
+
+| Method                      | Purpose           | Returns                            |
+| --------------------------- | ----------------- | ---------------------------------- |
+| `put(key, value, options?)` | Upload object     | `R2Object \| null`                 |
+| `get(key, options?)`        | Download object   | `R2ObjectBody \| R2Object \| null` |
+| `head(key)`                 | Get metadata only | `R2Object \| null`                 |
+| `delete(keys)`              | Delete object(s)  | `Promise<void>`                    |
+| `list(options?)`            | List objects      | `R2Objects`                        |
+
+## Storage Classes
+
+- **Standard**: Frequent access, low latency reads
+- **InfrequentAccess**: 30-day minimum storage, retrieval fees, lower storage cost
+
+## Event Notifications
+
+R2 integrates with Cloudflare Queues for reactive workflows:
+
+```typescript
+// wrangler.jsonc
+{
+  "event_notifications": [{
+    "queue": "r2-notifications",
+    "actions": ["PutObject", "DeleteObject"]
+  }]
+}
+
+// Consumer
+async queue(batch: MessageBatch, env: Env) {
+  for (const message of batch.messages) {
+    const event = message.body; // { action, bucket, object, timestamps }
+    if (event.action === 'PutObject') {
+      // Process upload: thumbnail generation, virus scan, etc.
+    }
+  }
+}
+```
+
+## Reading Order
+
+**First-time users:** README → configuration.md → api.md → patterns.md  
+**Specific tasks:**
+
+- Setup: configuration.md
+- Client uploads: patterns.md (presigned URLs)
+- Public static site: patterns.md (public access + custom domain)
+- Processing uploads: README (event notifications) + queues reference
+- Debugging: gotchas.md
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Bindings, S3 SDK, CORS, lifecycles, token scopes
+- [api.md](./api.md) - Workers API, multipart, conditional requests, presigned URLs
+- [patterns.md](./patterns.md) - Streaming, caching, client uploads, public buckets
+- [gotchas.md](./gotchas.md) - List truncation, etag format, stream length, S3 SDK region
+
+## See Also
+
+- [workers](../workers/) - Worker runtime and fetch handlers
+- [kv](../kv/) - Metadata storage for R2 objects
+- [d1](../d1/) - Store R2 URLs in relational database
+- [queues](../queues/) - Process R2 uploads asynchronously

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

@@ -0,0 +1,235 @@
+# R2 API Reference
+
+## PUT (Upload)
+
+```typescript
+// Basic
+await env.MY_BUCKET.put(key, value)
+
+// With metadata
+await env.MY_BUCKET.put(key, value, {
+  httpMetadata: {
+    contentType: 'image/jpeg',
+    contentDisposition: 'attachment; filename="photo.jpg"',
+    cacheControl: 'max-age=3600',
+  },
+  customMetadata: { userId: '123', version: '2' },
+  storageClass: 'Standard', // or 'InfrequentAccess'
+  sha256: arrayBufferOrHex, // Integrity check
+  ssecKey: arrayBuffer32bytes, // SSE-C encryption
+})
+
+// Value types: ReadableStream | ArrayBuffer | string | Blob
+```
+
+## GET (Download)
+
+```typescript
+const object = await env.MY_BUCKET.get(key)
+if (!object) return new Response('Not found', { status: 404 })
+
+// Body: arrayBuffer(), text(), json(), blob(), body (ReadableStream)
+
+// Ranged reads
+const object = await env.MY_BUCKET.get(key, { range: { offset: 0, length: 1024 } })
+
+// Conditional GET
+const object = await env.MY_BUCKET.get(key, { onlyIf: { etagMatches: '"abc123"' } })
+```
+
+## HEAD (Metadata Only)
+
+```typescript
+const object = await env.MY_BUCKET.head(key) // Returns R2Object without body
+```
+
+## DELETE
+
+```typescript
+await env.MY_BUCKET.delete(key)
+await env.MY_BUCKET.delete([key1, key2, key3]) // Batch (max 1000)
+```
+
+## LIST
+
+```typescript
+const listed = await env.MY_BUCKET.list({
+  limit: 1000,
+  prefix: 'photos/',
+  cursor: cursorFromPrevious,
+  delimiter: '/',
+  include: ['httpMetadata', 'customMetadata'],
+})
+
+// Pagination (always use truncated flag)
+while (listed.truncated) {
+  const next = await env.MY_BUCKET.list({ cursor: listed.cursor })
+  listed.objects.push(...next.objects)
+  listed.truncated = next.truncated
+  listed.cursor = next.cursor
+}
+```
+
+## Multipart Uploads
+
+```typescript
+const multipart = await env.MY_BUCKET.createMultipartUpload(key, {
+  httpMetadata: { contentType: 'video/mp4' },
+})
+
+const uploadedParts: R2UploadedPart[] = []
+for (let i = 0; i < partCount; i++) {
+  const part = await multipart.uploadPart(i + 1, partData)
+  uploadedParts.push(part)
+}
+
+const object = await multipart.complete(uploadedParts)
+// OR: await multipart.abort();
+
+// Resume
+const multipart = env.MY_BUCKET.resumeMultipartUpload(key, uploadId)
+```
+
+## Presigned URLs (S3 SDK)
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+
+const s3 = new S3Client({
+  region: 'auto',
+  endpoint: `https://${accountId}.r2.cloudflarestorage.com`,
+  credentials: { accessKeyId: env.R2_ACCESS_KEY_ID, secretAccessKey: env.R2_SECRET_ACCESS_KEY },
+})
+
+const uploadUrl = await getSignedUrl(s3, new PutObjectCommand({ Bucket: 'my-bucket', Key: key }), {
+  expiresIn: 3600,
+})
+return Response.json({ uploadUrl })
+```
+
+## TypeScript Interfaces
+
+```typescript
+interface R2Bucket {
+  head(key: string): Promise<R2Object | null>
+  get(key: string, options?: R2GetOptions): Promise<R2ObjectBody | null>
+  put(
+    key: string,
+    value: ReadableStream | ArrayBuffer | string | Blob,
+    options?: R2PutOptions
+  ): Promise<R2Object | null>
+  delete(keys: string | string[]): Promise<void>
+  list(options?: R2ListOptions): Promise<R2Objects>
+  createMultipartUpload(key: string, options?: R2MultipartOptions): Promise<R2MultipartUpload>
+  resumeMultipartUpload(key: string, uploadId: string): R2MultipartUpload
+}
+
+interface R2Object {
+  key: string
+  version: string
+  size: number
+  etag: string
+  httpEtag: string // httpEtag is quoted, use for headers
+  uploaded: Date
+  httpMetadata?: R2HTTPMetadata
+  customMetadata?: Record<string, string>
+  storageClass: 'Standard' | 'InfrequentAccess'
+  checksums: R2Checksums
+  writeHttpMetadata(headers: Headers): void
+}
+
+interface R2ObjectBody extends R2Object {
+  body: ReadableStream
+  bodyUsed: boolean
+  arrayBuffer(): Promise<ArrayBuffer>
+  text(): Promise<string>
+  json<T>(): Promise<T>
+  blob(): Promise<Blob>
+}
+
+interface R2HTTPMetadata {
+  contentType?: string
+  contentDisposition?: string
+  contentEncoding?: string
+  contentLanguage?: string
+  cacheControl?: string
+  cacheExpiry?: Date
+}
+
+interface R2PutOptions {
+  httpMetadata?: R2HTTPMetadata | Headers
+  customMetadata?: Record<string, string>
+  sha256?: ArrayBuffer | string // Only ONE checksum allowed
+  storageClass?: 'Standard' | 'InfrequentAccess'
+  ssecKey?: ArrayBuffer
+}
+
+interface R2GetOptions {
+  onlyIf?: R2Conditional | Headers
+  range?: R2Range | Headers
+  ssecKey?: ArrayBuffer
+}
+
+interface R2ListOptions {
+  limit?: number
+  prefix?: string
+  cursor?: string
+  delimiter?: string
+  startAfter?: string
+  include?: ('httpMetadata' | 'customMetadata')[]
+}
+
+interface R2Objects {
+  objects: R2Object[]
+  truncated: boolean
+  cursor?: string
+  delimitedPrefixes: string[]
+}
+
+interface R2Conditional {
+  etagMatches?: string
+  etagDoesNotMatch?: string
+  uploadedBefore?: Date
+  uploadedAfter?: Date
+}
+
+interface R2Range {
+  offset?: number
+  length?: number
+  suffix?: number
+}
+
+interface R2Checksums {
+  md5?: ArrayBuffer
+  sha1?: ArrayBuffer
+  sha256?: ArrayBuffer
+  sha384?: ArrayBuffer
+  sha512?: ArrayBuffer
+}
+
+interface R2MultipartUpload {
+  key: string
+  uploadId: string
+  uploadPart(
+    partNumber: number,
+    value: ReadableStream | ArrayBuffer | string | Blob
+  ): Promise<R2UploadedPart>
+  abort(): Promise<void>
+  complete(uploadedParts: R2UploadedPart[]): Promise<R2Object>
+}
+
+interface R2UploadedPart {
+  partNumber: number
+  etag: string
+}
+```
+
+## CLI Operations
+
+```bash
+wrangler r2 object put my-bucket/file.txt --file=./local.txt
+wrangler r2 object get my-bucket/file.txt --file=./download.txt
+wrangler r2 object delete my-bucket/file.txt
+wrangler r2 object list my-bucket --prefix=photos/
+```