memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/static-assets/gotchas.md

@@ -0,0 +1,164 @@
+## Best Practices
+
+### 1. Use Selective Worker-First Routing
+
+Instead of `run_worker_first = true`, use array patterns:
+
+```jsonc
+{
+  "assets": {
+    "run_worker_first": [
+      "/api/*", // API routes
+      "/admin/*", // Admin area
+      "!/admin/assets/*", // Except admin assets
+    ],
+  },
+}
+```
+
+**Benefits:**
+
+- Reduces Worker invocations
+- Lowers costs
+- Improves asset delivery performance
+
+### 2. Leverage Navigation Request Optimization
+
+For SPAs, use `compatibility_date = "2025-04-01"` or later:
+
+```jsonc
+{
+  "compatibility_date": "2025-04-01",
+  "assets": {
+    "not_found_handling": "single-page-application",
+  },
+}
+```
+
+Navigation requests skip Worker invocation, reducing costs.
+
+### 3. Type Safety with Bindings
+
+Always type your environment:
+
+```typescript
+interface Env {
+  ASSETS: Fetcher
+}
+```
+
+## Common Errors
+
+### "Asset not found"
+
+**Cause:** Asset not in assets directory, wrong path, or assets not deployed  
+**Solution:** Verify asset exists, check path case-sensitivity, redeploy if needed
+
+### "Worker not invoked for asset"
+
+**Cause:** Asset served directly, `run_worker_first` not configured  
+**Solution:** Configure `run_worker_first` patterns to include asset routes (see configuration.md:66-106)
+
+### "429 Too Many Requests on free tier"
+
+**Cause:** `run_worker_first` patterns invoke Worker for many requests, hitting free tier limits (100k req/day)  
+**Solution:** Use more selective patterns with negative exclusions, or upgrade to paid plan
+
+### "Smart Placement increases latency"
+
+**Cause:** `run_worker_first=true` + Smart Placement routes all requests through single smart-placed location  
+**Solution:** Use selective patterns (array syntax) or disable Smart Placement for asset-heavy apps
+
+### "CF-Cache-Status header unreliable"
+
+**Cause:** Header is probabilistically added for privacy reasons  
+**Solution:** Don't rely on `CF-Cache-Status` for critical routing logic. Use other signals (ETag, age).
+
+### "JWT expired during deployment"
+
+**Cause:** Large asset deployments exceed JWT token lifetime  
+**Solution:** Update to Wrangler 4.34.0+ (automatic token refresh), or reduce asset count
+
+### "Cannot use 'assets' with 'site'"
+
+**Cause:** Legacy `site` config conflicts with new `assets` config  
+**Solution:** Migrate from `site` to `assets` (see configuration.md). Remove `site` key from wrangler.jsonc.
+
+### "Assets not updating after deployment"
+
+**Cause:** Browser or CDN cache serving old assets  
+**Solution:**
+
+- Hard refresh browser (Cmd+Shift+R / Ctrl+F5)
+- Use cache-busting (hashed filenames)
+- Verify deployment completed: `wrangler tail`
+
+## Limits
+
+| Resource/Limit     | Free      | Paid        | Notes                                     |
+| ------------------ | --------- | ----------- | ----------------------------------------- |
+| Max asset size     | 25 MiB    | 25 MiB      | Per file                                  |
+| Total assets       | 20,000    | **100,000** | Requires Wrangler 4.34.0+ (Sep 2025)      |
+| Worker invocations | 100k/day  | 10M/month   | Optimize with `run_worker_first` patterns |
+| Asset storage      | Unlimited | Unlimited   | Included                                  |
+
+### Version Requirements
+
+| Feature                 | Minimum Wrangler Version                 |
+| ----------------------- | ---------------------------------------- |
+| 100k file limit (paid)  | 4.34.0                                   |
+| Vite plugin             | 4.0.0 + @cloudflare/vite-plugin 1.0.0    |
+| Navigation optimization | 4.0.0 + compatibility_date: "2025-04-01" |
+
+## Performance Tips
+
+### 1. Use Hashed Filenames
+
+Enable long-term caching with content-hashed filenames:
+
+```
+app.a3b2c1d4.js
+styles.e5f6g7h8.css
+```
+
+Most bundlers (Vite, Webpack, Parcel) do this automatically.
+
+### 2. Minimize Worker Invocations
+
+Serve assets directly when possible:
+
+```jsonc
+{
+  "assets": {
+    // Only invoke Worker for dynamic routes
+    "run_worker_first": ["/api/*", "/auth/*"],
+  },
+}
+```
+
+### 3. Leverage Browser Cache
+
+Set appropriate `Cache-Control` headers:
+
+```typescript
+// Versioned assets
+'Cache-Control': 'public, max-age=31536000, immutable'
+
+// HTML (revalidate often)
+'Cache-Control': 'public, max-age=0, must-revalidate'
+```
+
+See patterns.md:169-189 for implementation.
+
+### 4. Use .assetsignore
+
+Reduce upload time by excluding unnecessary files:
+
+```
+*.map
+*.md
+.DS_Store
+node_modules/
+```
+
+See configuration.md:107-126 for details.

package/skills/cloudflare/references/static-assets/patterns.md

@@ -0,0 +1,189 @@
+### Common Patterns
+
+**1. Forward request to assets:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**2. Fetch specific asset by path:**
+
+```typescript
+const response = await env.ASSETS.fetch('https://assets.local/logo.png')
+```
+
+**3. Modify request before fetching asset:**
+
+```typescript
+const url = new URL(request.url)
+url.pathname = '/index.html'
+return env.ASSETS.fetch(new Request(url, request))
+```
+
+**4. Transform asset response:**
+
+```typescript
+const response = await env.ASSETS.fetch(request)
+const modifiedResponse = new Response(response.body, response)
+modifiedResponse.headers.set('X-Custom-Header', 'value')
+modifiedResponse.headers.set('Cache-Control', 'public, max-age=3600')
+return modifiedResponse
+```
+
+**5. Conditional asset serving:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch('/index.html')
+    }
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**6. SPA with API routes:**
+
+Most common full-stack pattern - static SPA with backend API:
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname.startsWith('/api/')) {
+      return handleAPI(request, env)
+    }
+    return env.ASSETS.fetch(request)
+  },
+}
+
+async function handleAPI(request: Request, env: Env): Promise<Response> {
+  return new Response(JSON.stringify({ status: 'ok' }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+```
+
+**Config:** Set `run_worker_first: ["/api/*"]` (see configuration.md:66-106)
+
+**7. Auth gating for protected assets:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname.startsWith('/admin/')) {
+      const session = await validateSession(request, env)
+      if (!session) {
+        return Response.redirect('/login', 302)
+      }
+    }
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**Config:** Set `run_worker_first: ["/admin/*"]`
+
+**8. Custom headers for security:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await env.ASSETS.fetch(request)
+    const secureResponse = new Response(response.body, response)
+    secureResponse.headers.set('X-Frame-Options', 'DENY')
+    secureResponse.headers.set('X-Content-Type-Options', 'nosniff')
+    secureResponse.headers.set('Content-Security-Policy', "default-src 'self'")
+    return secureResponse
+  },
+}
+```
+
+**9. A/B testing via cookies:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const cookies = request.headers.get('Cookie') || ''
+    const variant = cookies.includes('variant=b') ? 'b' : 'a'
+    const url = new URL(request.url)
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch(`/index-${variant}.html`)
+    }
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**10. Locale-based routing:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const locale = request.headers.get('Accept-Language')?.split(',')[0] || 'en'
+    const url = new URL(request.url)
+    if (url.pathname === '/') {
+      return env.ASSETS.fetch(`/${locale}/index.html`)
+    }
+    if (!url.pathname.startsWith(`/${locale}/`)) {
+      url.pathname = `/${locale}${url.pathname}`
+    }
+    return env.ASSETS.fetch(url)
+  },
+}
+```
+
+**11. OAuth callback handling:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname === '/auth/callback') {
+      const code = url.searchParams.get('code')
+      if (code) {
+        const session = await exchangeCode(code, env)
+        return new Response(null, {
+          status: 302,
+          headers: {
+            Location: '/',
+            'Set-Cookie': `session=${session}; HttpOnly; Secure; SameSite=Lax`,
+          },
+        })
+      }
+    }
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**Config:** Set `run_worker_first: ["/auth/*"]`
+
+**12. Cache control override:**
+
+```typescript
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const response = await env.ASSETS.fetch(request)
+    const url = new URL(request.url)
+    // Immutable assets (hashed filenames)
+    if (/\.[a-f0-9]{8,}\.(js|css|png|jpg)$/.test(url.pathname)) {
+      return new Response(response.body, {
+        ...response,
+        headers: {
+          ...Object.fromEntries(response.headers),
+          'Cache-Control': 'public, max-age=31536000, immutable',
+        },
+      })
+    }
+    return response
+  },
+}
+```

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

@@ -0,0 +1,123 @@
+# Cloudflare Stream
+
+Serverless live and on-demand video streaming platform with one API.
+
+## Overview
+
+Cloudflare Stream provides video upload, storage, encoding, and delivery without managing infrastructure. Runs on Cloudflare's global network.
+
+### Key Features
+
+- **On-demand video**: Upload, encode, store, deliver
+- **Live streaming**: RTMPS/SRT ingestion with ABR
+- **Direct creator uploads**: End users upload without API keys
+- **Signed URLs**: Token-based access control
+- **Analytics**: Server-side metrics via GraphQL
+- **Webhooks**: Processing notifications
+- **Captions**: Upload or AI-generate subtitles
+- **Watermarks**: Apply branding to videos
+- **Downloads**: Enable MP4 offline viewing
+
+## Core Concepts
+
+### Video Upload Methods
+
+1. **API Upload (TUS protocol)**: Direct server upload
+2. **Upload from URL**: Import from external source
+3. **Direct Creator Uploads**: User-generated content (recommended)
+
+### Playback Options
+
+1. **Stream Player (iframe)**: Built-in, optimized player
+2. **Custom Player (HLS/DASH)**: Video.js, HLS.js integration
+3. **Thumbnails**: Static or animated previews
+
+### Access Control
+
+- **Public**: No restrictions
+- **requireSignedURLs**: Token-based access
+- **allowedOrigins**: Domain restrictions
+- **Access Rules**: Geo/IP restrictions in tokens
+
+### Live Streaming
+
+- RTMPS/SRT ingest from OBS, FFmpeg
+- Automatic recording to on-demand
+- Simulcast to YouTube, Twitch, etc.
+- WebRTC support for browser streaming
+
+## Quick Start
+
+**Upload video via API**
+
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/copy" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/video.mp4"}'
+```
+
+**Embed player**
+
+```html
+<iframe
+  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe"
+  style="border: none;"
+  height="720"
+  width="1280"
+  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
+  allowfullscreen="true"
+></iframe>
+```
+
+**Create live input**
+
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/live_inputs" \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"recording": {"mode": "automatic"}}'
+```
+
+## Limits
+
+- Max file size: 30 GB
+- Max frame rate: 60 fps (recommended)
+- Supported formats: MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime
+
+## Pricing
+
+- $5/1000 min stored
+- $1/1000 min delivered
+
+## Resources
+
+- Dashboard: https://dash.cloudflare.com/?to=/:account/stream
+- API Docs: https://developers.cloudflare.com/api/resources/stream/
+- Stream Docs: https://developers.cloudflare.com/stream/
+
+## Reading Order
+
+| Order | File                                   | Purpose                            | When to Use                   |
+| ----- | -------------------------------------- | ---------------------------------- | ----------------------------- |
+| 1     | [configuration.md](./configuration.md) | Setup SDKs, env vars, signing keys | Starting new project          |
+| 2     | [api.md](./api.md)                     | On-demand video APIs               | Implementing uploads/playback |
+| 3     | [api-live.md](./api-live.md)           | Live streaming APIs                | Building live streaming       |
+| 4     | [patterns.md](./patterns.md)           | Full-stack flows, TUS, JWT signing | Implementing workflows        |
+| 5     | [gotchas.md](./gotchas.md)             | Errors, limits, troubleshooting    | Debugging issues              |
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Setup, environment variables, wrangler config
+- [api.md](./api.md) - On-demand video upload, playback, management APIs
+- [api-live.md](./api-live.md) - Live streaming (RTMPS/SRT/WebRTC), simulcast
+- [patterns.md](./patterns.md) - Full-stack flows, state management, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting, limits
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs in Workers
+- [pages](../pages/) - Integrate Stream with Pages
+- [workers-ai](../workers-ai/) - AI-generate captions

package/skills/cloudflare/references/stream/api-live.md

@@ -0,0 +1,202 @@
+# Stream Live Streaming API
+
+Live input creation, status checking, simulcast, and WebRTC streaming.
+
+## Create Live Input
+
+### Using Cloudflare SDK
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: env.CF_API_TOKEN })
+
+const liveInput = await client.stream.liveInputs.create({
+  account_id: env.CF_ACCOUNT_ID,
+  recording: { mode: 'automatic', timeoutSeconds: 30 },
+  deleteRecordingAfterDays: 30,
+})
+
+// Returns: { uid, rtmps, srt, webRTC }
+```
+
+### Raw fetch API
+
+```typescript
+async function createLiveInput(accountId: string, apiToken: string) {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs`,
+    {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        recording: { mode: 'automatic', timeoutSeconds: 30 },
+        deleteRecordingAfterDays: 30,
+      }),
+    }
+  )
+  const { result } = await response.json()
+  return {
+    uid: result.uid,
+    rtmps: { url: result.rtmps.url, streamKey: result.rtmps.streamKey },
+    srt: { url: result.srt.url, streamId: result.srt.streamId, passphrase: result.srt.passphrase },
+    webRTC: result.webRTC,
+  }
+}
+```
+
+## Check Live Status
+
+```typescript
+async function getLiveStatus(accountId: string, liveInputId: string, apiToken: string) {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}`,
+    { headers: { Authorization: `Bearer ${apiToken}` } }
+  )
+  const { result } = await response.json()
+  return {
+    isLive: result.status?.current?.state === 'connected',
+    recording: result.recording,
+    status: result.status,
+  }
+}
+```
+
+## Simulcast (Live Outputs)
+
+### Create Output
+
+```typescript
+async function createLiveOutput(
+  accountId: string,
+  liveInputId: string,
+  apiToken: string,
+  outputUrl: string,
+  streamKey: string
+) {
+  return fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}/outputs`,
+    {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        url: `${outputUrl}/${streamKey}`,
+        enabled: true,
+        streamKey, // For platforms like YouTube, Twitch
+      }),
+    }
+  ).then((r) => r.json())
+}
+```
+
+### Example: Simulcast to YouTube + Twitch
+
+```typescript
+const liveInput = await createLiveInput(accountId, apiToken)
+
+// Add YouTube output
+await createLiveOutput(
+  accountId,
+  liveInput.uid,
+  apiToken,
+  'rtmp://a.rtmp.youtube.com/live2',
+  'your-youtube-stream-key'
+)
+
+// Add Twitch output
+await createLiveOutput(
+  accountId,
+  liveInput.uid,
+  apiToken,
+  'rtmp://live.twitch.tv/app',
+  'your-twitch-stream-key'
+)
+```
+
+## WebRTC Streaming (WHIP/WHEP)
+
+### Browser to Stream (WHIP)
+
+```typescript
+async function startWebRTCBroadcast(liveInputId: string) {
+  const pc = new RTCPeerConnection()
+
+  // Add local media tracks
+  const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
+  stream.getTracks().forEach((track) => pc.addTrack(track, stream))
+
+  // Create offer
+  const offer = await pc.createOffer()
+  await pc.setLocalDescription(offer)
+
+  // Send to Stream via WHIP
+  const response = await fetch(
+    `https://customer-<CODE>.cloudflarestream.com/${liveInputId}/webRTC/publish`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/sdp' },
+      body: offer.sdp,
+    }
+  )
+
+  const answer = await response.text()
+  await pc.setRemoteDescription({ type: 'answer', sdp: answer })
+}
+```
+
+### Stream to Browser (WHEP)
+
+```typescript
+async function playWebRTCStream(videoId: string) {
+  const pc = new RTCPeerConnection()
+
+  pc.addTransceiver('video', { direction: 'recvonly' })
+  pc.addTransceiver('audio', { direction: 'recvonly' })
+
+  const offer = await pc.createOffer()
+  await pc.setLocalDescription(offer)
+
+  const response = await fetch(
+    `https://customer-<CODE>.cloudflarestream.com/${videoId}/webRTC/play`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/sdp' },
+      body: offer.sdp,
+    }
+  )
+
+  const answer = await response.text()
+  await pc.setRemoteDescription({ type: 'answer', sdp: answer })
+
+  return pc
+}
+```
+
+## Recording Settings
+
+| Mode             | Behavior                                     |
+| ---------------- | -------------------------------------------- |
+| `automatic`      | Record all live streams                      |
+| `off`            | No recording                                 |
+| `timeoutSeconds` | Stop recording after N seconds of inactivity |
+
+```typescript
+const recordingConfig = {
+  mode: 'automatic',
+  timeoutSeconds: 30, // Auto-stop 30s after stream ends
+  requireSignedURLs: true, // Require token for VOD playback
+  allowedOrigins: ['https://yourdomain.com'],
+}
+```
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [api.md](./api.md) - On-demand video APIs
+- [configuration.md](./configuration.md) - Setup and config
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [workers](../workers/) - Deploy live APIs in Workers