memory-journal-mcp 8.0.1 → 9.1.0

package/skills/cloudflare/references/realtime-sfu/api.md

@@ -1,164 +0,0 @@
-# API Reference
-
-## Authentication
-
-```bash
-curl -X POST 'https://rtc.live/v1/apps/${CALLS_APP_ID}/sessions/new' \
-  -H "Authorization: Bearer ${CALLS_APP_SECRET}"
-```
-
-## Core Concepts
-
-**Sessions:** PeerConnection to Cloudflare edge  
-**Tracks:** Media/data channels (audio/video/datachannel)  
-**No rooms:** Build presence via track sharing
-
-## Client Libraries
-
-**PartyTracks (Recommended):** Observable-based client library for production use. Handles device changes, network switches, ICE restarts automatically. Push/pull API with React hooks. See patterns.md for full examples.
-
-```bash
-npm install partytracks @cloudflare/calls
-```
-
-**Raw API:** Direct HTTP + WebRTC for custom requirements (documented below).
-
-## Endpoints
-
-### Create Session
-
-```http
-POST /v1/apps/{appId}/sessions/new
-→ {sessionId, sessionDescription}
-```
-
-### Add Track (Publish)
-
-```http
-POST /v1/apps/{appId}/sessions/{sessionId}/tracks/new
-Body: {
-  sessionDescription: {sdp, type: "offer"},
-  tracks: [{location: "local", trackName: "my-video"}]
-}
-→ {sessionDescription, tracks: [{trackName}]}
-```
-
-### Add Track (Subscribe)
-
-```http
-POST /v1/apps/{appId}/sessions/{sessionId}/tracks/new
-Body: {
-  tracks: [{
-    location: "remote",
-    trackName: "remote-track-id",
-    sessionId: "other-session-id"
-  }]
-}
-→ {sessionDescription} (server offer)
-```
-
-### Renegotiate
-
-```http
-PUT /v1/apps/{appId}/sessions/{sessionId}/renegotiate
-Body: {sessionDescription: {sdp, type: "answer"}}
-```
-
-### Close Tracks
-
-```http
-PUT /v1/apps/{appId}/sessions/{sessionId}/tracks/close
-Body: {tracks: [{trackName}]}
-→ {requiresImmediateRenegotiation: boolean}
-```
-
-### Get Session
-
-```http
-GET /v1/apps/{appId}/sessions/{sessionId}
-→ {sessionId, tracks: TrackMetadata[]}
-```
-
-## TypeScript Types
-
-```typescript
-interface TrackMetadata {
-  trackName: string
-  location: 'local' | 'remote'
-  sessionId?: string // For remote tracks
-  mid?: string // WebRTC mid
-}
-```
-
-## WebRTC Flow
-
-```typescript
-// 1. Create PeerConnection
-const pc = new RTCPeerConnection({
-  iceServers: [{ urls: 'stun:stun.cloudflare.com:3478' }],
-})
-
-// 2. Add tracks
-const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true })
-stream.getTracks().forEach((track) => pc.addTrack(track, stream))
-
-// 3. Create offer
-const offer = await pc.createOffer()
-await pc.setLocalDescription(offer)
-
-// 4. Send to backend → Cloudflare API
-const response = await fetch('/api/new-session', {
-  method: 'POST',
-  body: JSON.stringify({ sdp: offer.sdp }),
-})
-
-// 5. Set remote answer
-const { sessionDescription } = await response.json()
-await pc.setRemoteDescription(sessionDescription)
-```
-
-## Publishing
-
-```typescript
-const offer = await pc.createOffer()
-await pc.setLocalDescription(offer)
-
-const res = await fetch(`/api/sessions/${sessionId}/tracks`, {
-  method: 'POST',
-  body: JSON.stringify({
-    sdp: offer.sdp,
-    tracks: [{ location: 'local', trackName: 'my-video' }],
-  }),
-})
-
-const { sessionDescription, tracks } = await res.json()
-await pc.setRemoteDescription(sessionDescription)
-const publishedTrackId = tracks[0].trackName // Share with others
-```
-
-## Subscribing
-
-```typescript
-const res = await fetch(`/api/sessions/${sessionId}/tracks`, {
-  method: 'POST',
-  body: JSON.stringify({
-    tracks: [{ location: 'remote', trackName: remoteTrackId, sessionId: remoteSessionId }],
-  }),
-})
-
-const { sessionDescription } = await res.json()
-await pc.setRemoteDescription(sessionDescription)
-
-const answer = await pc.createAnswer()
-await pc.setLocalDescription(answer)
-
-await fetch(`/api/sessions/${sessionId}/renegotiate`, {
-  method: 'PUT',
-  body: JSON.stringify({ sdp: answer.sdp }),
-})
-
-pc.ontrack = (event) => {
-  const [remoteStream] = event.streams
-  videoElement.srcObject = remoteStream
-}
-```

package/skills/cloudflare/references/realtime-sfu/configuration.md

@@ -1,141 +0,0 @@
-# Configuration & Deployment
-
-## Dashboard Setup
-
-1. Navigate to https://dash.cloudflare.com/?to=/:account/calls
-2. Click "Create Application" (or use existing app)
-3. Copy `CALLS_APP_ID` from dashboard
-4. Generate and copy `CALLS_APP_SECRET` (treat as sensitive credential)
-5. Use credentials in Wrangler config or environment variables below
-
-## Dependencies
-
-**Backend (Workers):** Built-in fetch API, no additional packages required
-
-**Client (PartyTracks):**
-
-```bash
-npm install partytracks @cloudflare/calls
-```
-
-**Client (React + PartyTracks):**
-
-```bash
-npm install partytracks @cloudflare/calls observable-hooks
-# Observable hooks: useObservableAsValue, useValueAsObservable
-```
-
-**Client (Raw API):** Native browser WebRTC API only
-
-## Wrangler Setup
-
-```jsonc
-{
-  "name": "my-calls-app",
-  "main": "src/index.ts",
-  "compatibility_date": "2025-01-01", // Use current date for new projects
-  "vars": {
-    "CALLS_APP_ID": "your-app-id",
-    "MAX_WEBCAM_BITRATE": "1200000",
-    "MAX_WEBCAM_FRAMERATE": "24",
-    "MAX_WEBCAM_QUALITY_LEVEL": "1080",
-  },
-  // Set secret: wrangler secret put CALLS_APP_SECRET
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "ROOM",
-        "class_name": "Room",
-      },
-    ],
-  },
-}
-```
-
-## Deploy
-
-```bash
-wrangler login
-wrangler secret put CALLS_APP_SECRET
-wrangler deploy
-```
-
-## Environment Variables
-
-**Required:**
-
-- `CALLS_APP_ID`: From dashboard
-- `CALLS_APP_SECRET`: From dashboard (secret)
-
-**Optional:**
-
-- `MAX_WEBCAM_BITRATE` (default: 1200000)
-- `MAX_WEBCAM_FRAMERATE` (default: 24)
-- `MAX_WEBCAM_QUALITY_LEVEL` (default: 1080)
-- `TURN_SERVICE_ID`: TURN service
-- `TURN_SERVICE_TOKEN`: TURN auth (secret)
-
-## TURN Configuration
-
-```javascript
-const pc = new RTCPeerConnection({
-  iceServers: [
-    { urls: 'stun:stun.cloudflare.com:3478' },
-    {
-      urls: [
-        'turn:turn.cloudflare.com:3478?transport=udp',
-        'turn:turn.cloudflare.com:3478?transport=tcp',
-        'turns:turn.cloudflare.com:5349?transport=tcp',
-      ],
-      username: turnUsername,
-      credential: turnCredential,
-    },
-  ],
-  bundlePolicy: 'max-bundle', // Recommended: reduces overhead
-  iceTransportPolicy: 'all', // Use 'relay' to force TURN (testing only)
-})
-```
-
-**Ports:** 3478 (UDP/TCP), 53 (UDP), 80 (TCP), 443 (TLS), 5349 (TLS)
-
-**When to use TURN:** Required for restrictive corporate firewalls/networks that block UDP. ~5-10% of connections fallback to TURN. STUN works for most users.
-
-**ICE candidate filtering:** Cloudflare handles candidate filtering automatically. No need to manually filter candidates.
-
-## Durable Object Boilerplate
-
-Minimal presence system:
-
-```typescript
-export class Room {
-  private sessions = new Map<string, { userId: string; tracks: string[] }>()
-
-  async fetch(req: Request) {
-    const { pathname } = new URL(req.url)
-    const body = await req.json()
-
-    if (pathname === '/join') {
-      this.sessions.set(body.sessionId, { userId: body.userId, tracks: [] })
-      return Response.json({ participants: this.sessions.size })
-    }
-
-    if (pathname === '/publish') {
-      this.sessions.get(body.sessionId)?.tracks.push(...body.tracks)
-      // Broadcast to others via WebSocket (not shown)
-      return new Response('OK')
-    }
-
-    return new Response('Not found', { status: 404 })
-  }
-}
-```
-
-## Environment Validation
-
-Check credentials before first API call:
-
-```typescript
-if (!env.CALLS_APP_ID || !env.CALLS_APP_SECRET) {
-  throw new Error('CALLS_APP_ID and CALLS_APP_SECRET required')
-}
-```

package/skills/cloudflare/references/realtime-sfu/gotchas.md

@@ -1,138 +0,0 @@
-# Gotchas & Troubleshooting
-
-## Common Errors
-
-### "Slow initial connect (~1.8s)"
-
-**Cause:** First STUN delayed during consensus forming (normal behavior)
-**Solution:** Subsequent connections are faster. CF detects DTLS ClientHello early to compensate.
-
-### "No media flow"
-
-**Cause:** SDP exchange incomplete, connection not established, tracks not added before offer, browser permissions missing
-**Solution:**
-
-1. Verify SDP exchange complete
-2. Check `pc.connectionState === 'connected'`
-3. Ensure tracks added before creating offer
-4. Confirm browser permissions granted
-5. Use `chrome://webrtc-internals` for debugging
-
-### "Track not receiving"
-
-**Cause:** Track not published, track ID not shared, session IDs mismatch, `pc.ontrack` not set, renegotiation needed
-**Solution:**
-
-1. Verify track published successfully
-2. Confirm track ID shared between peers
-3. Check session IDs match
-4. Set `pc.ontrack` handler before answer
-5. Trigger renegotiation if needed
-
-### "ICE connection failed"
-
-**Cause:** Network changed, firewall blocked UDP, TURN needed, transient network issue
-**Solution:**
-
-```typescript
-pc.oniceconnectionstatechange = async () => {
-  if (pc.iceConnectionState === 'failed') {
-    console.warn('ICE failed, attempting restart')
-    await pc.restartIce() // Triggers new ICE gathering
-
-    // Create new offer with ICE restart flag
-    const offer = await pc.createOffer({ iceRestart: true })
-    await pc.setLocalDescription(offer)
-
-    // Send to backend → Cloudflare API
-    await fetch(`/api/sessions/${sessionId}/renegotiate`, {
-      method: 'PUT',
-      body: JSON.stringify({ sdp: offer.sdp }),
-    })
-  }
-}
-```
-
-### "Track stuck/frozen"
-
-**Cause:** Sender paused track, network congestion, codec mismatch, mobile browser backgrounded
-**Solution:**
-
-1. Check `track.enabled` and `track.readyState === 'live'`
-2. Verify sender active: `pc.getSenders().find(s => s.track === track)`
-3. Check stats for packet loss/jitter (see patterns.md)
-4. On mobile: Re-acquire tracks when app foregrounded
-5. Test with different codecs if persistent
-
-### "Network change disconnects call"
-
-**Cause:** Mobile switching WiFi↔cellular, laptop changing networks
-**Solution:**
-
-```typescript
-// Listen for network changes
-if ('connection' in navigator) {
-  ;(navigator as any).connection.addEventListener('change', async () => {
-    console.log('Network changed')
-    await pc.restartIce() // Use ICE restart pattern above
-  })
-}
-
-// Or use PartyTracks (handles automatically)
-```
-
-## Retry with Exponential Backoff
-
-```typescript
-async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      const res = await fetch(url, options)
-      if (res.ok) return res
-      if (res.status >= 500) throw new Error('Server error')
-      return res // Client error, don't retry
-    } catch (err) {
-      if (i === maxRetries - 1) throw err
-      const delay = Math.min(1000 * 2 ** i, 10000) // Cap at 10s
-      await new Promise((resolve) => setTimeout(resolve, delay))
-    }
-  }
-}
-```
-
-## Debugging with chrome://webrtc-internals
-
-1. Open `chrome://webrtc-internals` in Chrome/Edge
-2. Find your PeerConnection in the list
-3. Check **Stats graphs** for packet loss, jitter, bandwidth
-4. Check **ICE candidate pairs**: Look for `succeeded` state, relay vs host candidates
-5. Check **getStats**: Raw metrics for inbound/outbound RTP
-6. Look for errors in **Event log**: `iceConnectionState`, `connectionState` changes
-7. Export data with "Download the PeerConnection updates and stats data" button
-8. Common issues visible here: ICE failures, high packet loss, bitrate drops
-
-## Limits
-
-| Resource/Limit     | Value          | Notes                                               |
-| ------------------ | -------------- | --------------------------------------------------- |
-| Egress (Free)      | 1TB/month      | Per account                                         |
-| Egress (Paid)      | $0.05/GB       | After free tier                                     |
-| Inbound traffic    | Free           | All plans                                           |
-| TURN service       | Free           | Included with SFU                                   |
-| Participants       | No hard limit  | Client bandwidth/CPU bound (typically 10-50 tracks) |
-| Tracks per session | No hard limit  | Client resources limited                            |
-| Session duration   | No hard limit  | Production calls run for hours                      |
-| WebRTC ports       | UDP 1024-65535 | Outbound only, required for media                   |
-| API rate limit     | 600 req/min    | Per app, burst allowed                              |
-
-## Security Checklist
-
-- ✅ **Never expose** `CALLS_APP_SECRET` to client
-- ✅ **Validate user identity** in backend before creating sessions
-- ✅ **Implement auth tokens** for session access (JWT in custom header)
-- ✅ **Rate limit** session creation endpoints
-- ✅ **Expire sessions** server-side after inactivity
-- ✅ **Validate track IDs** before subscribing (prevent unauthorized access)
-- ✅ **Use HTTPS** for all signaling (API calls)
-- ✅ **Enable DTLS-SRTP** (automatic with Cloudflare, encrypts media)
-- ⚠️ **Consider E2EE** for sensitive content (implement client-side with Insertable Streams API)

package/skills/cloudflare/references/realtime-sfu/patterns.md

@@ -1,187 +0,0 @@
-# Patterns & Use Cases
-
-## Architecture
-
-```
-Client (WebRTC) <---> CF Edge <---> Backend (HTTP)
-                           |
-                    CF Backbone (310+ DCs)
-                           |
-                    Other Edges <---> Other Clients
-```
-
-Anycast: Last-mile <50ms (95%), no region select, NACK shield, distributed consensus
-
-Cascading trees auto-scale to millions:
-
-```
-Publisher -> Edge A -> Edge B -> Sub1
-                    \-> Edge C -> Sub2,3
-```
-
-## Use Cases
-
-**1:1:** A creates session+publishes, B creates+subscribes to A+publishes, A subscribes to B
-**N:N:** All create session+publish, backend broadcasts track IDs, all subscribe to others
-**1:N:** Publisher creates+publishes, viewers each create+subscribe (no fan-out limit)
-**Breakout:** Same PeerConnection! Backend closes/adds tracks, no recreation
-
-## PartyTracks (Recommended)
-
-Observable-based client with automatic device/network handling:
-
-```typescript
-import {PartyTracks} from 'partytracks';
-
-// Create client
-const pt = new PartyTracks({
-  apiUrl: '/api/calls',
-  sessionId: 'my-session',
-  onTrack: (track, peer) => {
-    const video = document.getElementById(`video-${peer.id}`) as HTMLVideoElement;
-    video.srcObject = new MediaStream([track]);
-  }
-});
-
-// Publish camera (push API)
-const camera = await pt.getCamera(); // Auto-requests permissions, handles device changes
-await pt.publishTrack(camera, {trackName: 'my-camera'});
-
-// Subscribe to remote track (pull API)
-await pt.subscribeToTrack({trackName: 'remote-camera', sessionId: 'other-session'});
-
-// React hook example
-import {useObservableAsValue} from 'observable-hooks';
-
-function VideoCall() {
-  const localTracks = useObservableAsValue(pt.localTracks$);
-  const remoteTracks = useObservableAsValue(pt.remoteTracks$);
-
-  return <div>{/* Render tracks */}</div>;
-}
-
-// Screenshare
-const screen = await pt.getScreenshare();
-await pt.publishTrack(screen, {trackName: 'my-screen'});
-
-// Handle device changes (automatic)
-// PartyTracks detects device changes (e.g., Bluetooth headset) and renegotiates
-```
-
-## Backend
-
-Express:
-
-```js
-app.post('/api/new-session', async (req, res) => {
-  const r = await fetch(`${CALLS_API}/apps/${process.env.CALLS_APP_ID}/sessions/new`, {
-    method: 'POST',
-    headers: { Authorization: `Bearer ${process.env.CALLS_APP_SECRET}` },
-  })
-  res.json(await r.json())
-})
-```
-
-Workers: Same pattern, use `env.CALLS_APP_ID` and `env.CALLS_APP_SECRET`
-
-DO Presence: See configuration.md for boilerplate
-
-## Audio Level Detection
-
-```typescript
-// Attach analyzer to audio track
-function attachAudioLevelDetector(track: MediaStreamTrack) {
-  const ctx = new AudioContext()
-  const analyzer = ctx.createAnalyser()
-  const src = ctx.createMediaStreamSource(new MediaStream([track]))
-  src.connect(analyzer)
-
-  const data = new Uint8Array(analyzer.frequencyBinCount)
-  const checkLevel = () => {
-    analyzer.getByteFrequencyData(data)
-    const level = data.reduce((a, b) => a + b) / data.length
-    if (level > 30) console.log('Speaking:', level) // Trigger UI update
-    requestAnimationFrame(checkLevel)
-  }
-  checkLevel()
-}
-```
-
-## Connection Quality Monitoring
-
-```typescript
-pc.getStats().then((stats) => {
-  stats.forEach((report) => {
-    if (report.type === 'inbound-rtp' && report.kind === 'video') {
-      const { packetsLost, packetsReceived, jitter } = report
-      const lossRate = packetsLost / (packetsLost + packetsReceived)
-      if (lossRate > 0.05) console.warn('High packet loss:', lossRate)
-      if (jitter > 100) console.warn('High jitter:', jitter)
-    }
-  })
-})
-```
-
-## Stage Management (Limit Visible Participants)
-
-```typescript
-// Subscribe to top 6 active speakers only
-let activeSubscriptions = new Set<string>()
-
-function updateStage(topSpeakers: string[]) {
-  const toAdd = topSpeakers.filter((id) => !activeSubscriptions.has(id)).slice(0, 6)
-  const toRemove = [...activeSubscriptions].filter((id) => !topSpeakers.includes(id))
-
-  toRemove.forEach((id) => {
-    pc.getSenders()
-      .find((s) => s.track?.id === id)
-      ?.track?.stop()
-    activeSubscriptions.delete(id)
-  })
-
-  toAdd.forEach(async (id) => {
-    await fetch(`/api/subscribe`, { method: 'POST', body: JSON.stringify({ trackId: id }) })
-    activeSubscriptions.add(id)
-  })
-}
-```
-
-## Advanced
-
-Bandwidth mgmt:
-
-```ts
-const s = pc.getSenders().find((s) => s.track?.kind === 'video')
-const p = s.getParameters()
-if (!p.encodings) p.encodings = [{}]
-p.encodings[0].maxBitrate = 1200000
-p.encodings[0].maxFramerate = 24
-await s.setParameters(p)
-```
-
-Simulcast (CF auto-forwards best layer):
-
-```ts
-pc.addTransceiver('video', {
-  direction: 'sendonly',
-  sendEncodings: [
-    { rid: 'high', maxBitrate: 1200000 },
-    { rid: 'med', maxBitrate: 600000, scaleResolutionDownBy: 2 },
-    { rid: 'low', maxBitrate: 200000, scaleResolutionDownBy: 4 },
-  ],
-})
-```
-
-DataChannel:
-
-```ts
-const dc = pc.createDataChannel('chat', { ordered: true, maxRetransmits: 3 })
-dc.onopen = () => dc.send(JSON.stringify({ type: 'chat', text: 'Hi' }))
-dc.onmessage = (e) => console.log('RX:', JSON.parse(e.data))
-```
-
-**WHIP/WHEP:** For streaming interop (OBS → SFU, SFU → video players), use WHIP (ingest) and WHEP (egress) protocols. See Cloudflare Stream integration docs.
-
-Integrations: R2 for recording `env.R2_BUCKET.put(...)`, Queues for analytics
-
-Perf: 100-250ms connect, ~50ms latency (95%), 200-400ms glass-to-glass, no participant limit (client: 10-50 tracks)