memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,206 @@
+# RealtimeKit Gotchas & Troubleshooting
+
+## Common Errors
+
+### "Cannot connect to meeting"
+
+**Cause:** Auth token invalid/expired, API credentials lack permissions, or network blocks WebRTC
+**Solution:**
+Verify token validity, check API token has **Realtime / Realtime Admin** permissions, enable TURN service for restrictive networks
+
+### "No video/audio tracks"
+
+**Cause:** Browser permissions not granted, video/audio not enabled, device in use, or device unavailable
+**Solution:**
+Request browser permissions explicitly, verify initialization config, use `meeting.self.getAllDevices()` to debug, close other apps using device
+
+### "Participant count mismatched"
+
+**Cause:** `meeting.participants` doesn't include `meeting.self`
+**Solution:** Total count = `meeting.participants.joined.size() + 1`
+
+### "Events not firing"
+
+**Cause:** Listeners registered after actions, incorrect event name, or wrong namespace
+**Solution:**
+Register listeners before calling `meeting.join()`, check event names against docs, verify correct namespace
+
+### "CORS errors in API calls"
+
+**Cause:** Making REST API calls from client-side
+**Solution:** All REST API calls **must** be server-side (Workers, backend). Never expose API tokens to clients.
+
+### "Preset not applying"
+
+**Cause:** Preset doesn't exist, name mismatch (case-sensitive), or participant created before preset
+**Solution:**
+Verify preset exists via Dashboard or API, check exact spelling and case, create preset before adding participants
+
+### "Token reuse error"
+
+**Cause:** Reusing participant tokens across sessions
+**Solution:** Generate fresh token per session. Use refresh endpoint if token expires during session.
+
+### "Video quality poor"
+
+**Cause:** Insufficient bandwidth, resolution/bitrate too high, or CPU overload
+**Solution:**
+Lower `mediaConfiguration.video` resolution/frameRate, monitor network conditions, reduce participant count or grid size
+
+### "Echo or audio feedback"
+
+**Cause:** Multiple devices picking up same audio source
+**Solution:**
+
+- Lower `mediaConfiguration.video` resolution/frameRate
+- Monitor network conditions
+- Reduce participant count or grid size
+
+### Issue: Echo or audio feedback
+
+**Cause**: Multiple devices picking up same audio source
+
+**Solutions**:
+Enable `echoCancellation: true` in `mediaConfiguration.audio`, use headphones, mute when not speaking
+
+### "Screen share not working"
+
+**Cause:** Browser doesn't support screen sharing API, permission denied, or wrong `displaySurface` config
+**Solution:**
+Use Chrome/Edge/Firefox (Safari limited support), check browser permissions, try different `displaySurface` values ('window', 'monitor', 'browser')
+
+### "How do I schedule meetings?"
+
+**Cause:** RealtimeKit has no built-in scheduling system
+**Solution:**
+Store meeting IDs in your database with timestamps. Generate participant tokens only when user should join. Example:
+
+```typescript
+// Store in DB
+{ meetingId: 'abc123', scheduledFor: '2026-02-15T10:00:00Z', userId: 'user456' }
+
+// Generate token when user clicks "Join" near scheduled time
+const response = await fetch('/api/join-meeting', {
+  method: 'POST',
+  body: JSON.stringify({ meetingId: 'abc123' })
+});
+const { authToken } = await response.json();
+```
+
+### "Recording not starting"
+
+**Cause:** Preset lacks recording permissions, no active session, or API call from client
+**Solution:**
+Verify preset has `canRecord: true` and `canStartStopRecording: true`, ensure session is active (at least one participant), make recording API calls server-side only
+
+## Limits
+
+| Resource                        | Limit              |
+| ------------------------------- | ------------------ |
+| Max participants per session    | 100                |
+| Max concurrent sessions per App | 1000               |
+| Max recording duration          | 6 hours            |
+| Max meeting duration            | 24 hours           |
+| Max chat message length         | 4000 characters    |
+| Max preset name length          | 64 characters      |
+| Max meeting title length        | 256 characters     |
+| Max participant name length     | 256 characters     |
+| Token expiration                | 24 hours (default) |
+| WebRTC ports required           | UDP 1024-65535     |
+
+## Network Requirements
+
+### Firewall Rules
+
+Allow outbound UDP/TCP to:
+
+- `*.cloudflare.com` ports 443, 80
+- UDP ports 1024-65535 (WebRTC media)
+
+### TURN Service
+
+Enable for users behind restrictive firewalls/proxies:
+
+```jsonc
+// wrangler.jsonc
+{
+  "vars": {
+    "TURN_SERVICE_ID": "your_turn_service_id",
+  },
+  // Set secret: wrangler secret put TURN_SERVICE_TOKEN
+}
+```
+
+TURN automatically configured in SDK when enabled in account.
+
+## Debugging Tips
+
+```typescript
+// Check devices
+const devices = await meeting.self.getAllDevices()
+meeting.self.on('deviceListUpdate', ({ added, removed, devices }) =>
+  console.log('Devices:', { added, removed, devices })
+)
+
+// Monitor participants
+meeting.participants.joined.on('participantJoined', (p) =>
+  console.log(`${p.name} joined:`, {
+    id: p.id,
+    userId: p.userId,
+    audioEnabled: p.audioEnabled,
+    videoEnabled: p.videoEnabled,
+  })
+)
+
+// Check room state
+meeting.self.on('roomJoined', () =>
+  console.log('Room:', {
+    meetingId: meeting.meta.meetingId,
+    meetingTitle: meeting.meta.meetingTitle,
+    participantCount: meeting.participants.joined.size() + 1,
+    audioEnabled: meeting.self.audioEnabled,
+    videoEnabled: meeting.self.videoEnabled,
+  })
+)
+
+// Log all events
+;[
+  'roomJoined',
+  'audioUpdate',
+  'videoUpdate',
+  'screenShareUpdate',
+  'deviceUpdate',
+  'deviceListUpdate',
+].forEach((event) => meeting.self.on(event, (data) => console.log(`[self] ${event}:`, data)))
+;['participantJoined', 'participantLeft'].forEach((event) =>
+  meeting.participants.joined.on(event, (data) => console.log(`[participants] ${event}:`, data))
+)
+meeting.chat.on('chatUpdate', (data) => console.log('[chat] chatUpdate:', data))
+```
+
+## Security & Performance
+
+### Security: Do NOT
+
+- Expose `CLOUDFLARE_API_TOKEN` in client code, hardcode credentials in frontend
+- Reuse participant tokens, store tokens in localStorage without encryption
+- Allow client-side meeting creation
+
+### Security: DO
+
+- Generate tokens server-side only, use HTTPS, implement rate limiting
+- Validate user auth before generating tokens, use `custom_participant_id` to map to your user system
+- Set appropriate preset permissions per user role, rotate API tokens regularly
+
+### Performance
+
+- **CPU**: Lower video resolution/frameRate, disable video for audio-only, use `meeting.participants.active` for large meetings, implement virtual scrolling
+- **Bandwidth**: Set max resolution in `mediaConfiguration`, disable screenshare audio if unneeded, use audio-only mode, implement adaptive bitrate
+- **Memory**: Clean up event listeners on unmount, call `meeting.leave()` when done, don't store large participant arrays
+
+## In This Reference
+
+- [README.md](README.md) - Overview, core concepts, quick start
+- [configuration.md](configuration.md) - SDK config, presets, wrangler setup
+- [api.md](api.md) - Client SDK APIs, REST endpoints
+- [patterns.md](patterns.md) - Common patterns, React hooks, backend integration

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

@@ -0,0 +1,240 @@
+# RealtimeKit Patterns
+
+## UI Kit (Minimal Code)
+
+```tsx
+// React
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui';
+<RtkMeeting authToken="<token>" onLeave={() => console.log('Left')} />
+
+// Angular
+@Component({ template: `<rtk-meeting [authToken]="authToken" (rtkLeave)="onLeave($event)"></rtk-meeting>` })
+export class AppComponent { authToken = '<token>'; onLeave(event: unknown) {} }
+
+// HTML/Web Components
+<script type="module" src="https://cdn.jsdelivr.net/npm/@cloudflare/realtimekit-ui/dist/realtimekit-ui/realtimekit-ui.esm.js"></script>
+<rtk-meeting id="meeting"></rtk-meeting>
+<script>document.getElementById('meeting').authToken = '<token>';</script>
+```
+
+## UI Components
+
+RealtimeKit provides 133+ pre-built Stencil.js Web Components with framework wrappers:
+
+### Layout Components
+
+- `<RtkMeeting>` - Full meeting UI (all-in-one)
+- `<RtkHeader>`, `<RtkStage>`, `<RtkControlbar>` - Layout sections
+- `<RtkSidebar>` - Chat/participants sidebar
+- `<RtkGrid>` - Adaptive video grid
+
+### Control Components
+
+- `<RtkMicToggle>`, `<RtkCameraToggle>` - Media controls
+- `<RtkScreenShareToggle>` - Screen sharing
+- `<RtkLeaveButton>` - Leave meeting
+- `<RtkSettingsModal>` - Device settings
+
+### Grid Variants
+
+- `<RtkSpotlightGrid>` - Active speaker focus
+- `<RtkAudioGrid>` - Audio-only mode
+- `<RtkPaginatedGrid>` - Paginated layout
+
+**See full catalog**: https://docs.realtime.cloudflare.com/ui-kit
+
+## Core SDK Patterns
+
+### Basic Setup
+
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit'
+
+const meeting = new RealtimeKitClient({ authToken, video: true, audio: true })
+meeting.self.on('roomJoined', () => console.log('Joined:', meeting.meta.meetingTitle))
+meeting.participants.joined.on('participantJoined', (p) => console.log(`${p.name} joined`))
+await meeting.join()
+```
+
+### Video Grid & Device Selection
+
+```typescript
+// Video grid
+function VideoGrid({ meeting }) {
+  const [participants, setParticipants] = useState([]);
+  useEffect(() => {
+    const update = () => setParticipants(meeting.participants.joined.toArray());
+    meeting.participants.joined.on('participantJoined', update);
+    meeting.participants.joined.on('participantLeft', update);
+    update();
+    return () => { meeting.participants.joined.off('participantJoined', update); meeting.participants.joined.off('participantLeft', update); };
+  }, [meeting]);
+  return <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(300px, 1fr))' }}>
+    {participants.map(p => <VideoTile key={p.id} participant={p} />)}
+  </div>;
+}
+
+function VideoTile({ participant }) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  useEffect(() => {
+    if (videoRef.current && participant.videoTrack) videoRef.current.srcObject = new MediaStream([participant.videoTrack]);
+  }, [participant.videoTrack]);
+  return <div><video ref={videoRef} autoPlay playsInline muted /><div>{participant.name}</div></div>;
+}
+
+// Device selection
+const devices = await meeting.self.getAllDevices();
+const switchCamera = (deviceId: string) => {
+  const device = devices.find(d => d.deviceId === deviceId);
+  if (device) await meeting.self.setDevice(device);
+};
+```
+
+## React Hooks (Official)
+
+```typescript
+import { useRealtimeKitClient, useRealtimeKitSelector } from '@cloudflare/realtimekit-react-ui';
+
+function MyComponent() {
+  const [meeting, initMeeting] = useRealtimeKitClient();
+  const audioEnabled = useRealtimeKitSelector(m => m.self.audioEnabled);
+  const participantCount = useRealtimeKitSelector(m => m.participants.joined.size());
+
+  useEffect(() => { initMeeting({ authToken: '<token>' }); }, []);
+
+  return <div>
+    <button onClick={() => meeting?.self.enableAudio()}>{audioEnabled ? 'Mute' : 'Unmute'}</button>
+    <span>{participantCount} participants</span>
+  </div>;
+}
+```
+
+**Benefits:** Automatic re-renders, memoized selectors, type-safe
+
+## Waitlist Handling
+
+```typescript
+// Monitor waitlist
+meeting.participants.waitlisted.on('participantJoined', (participant) => {
+  console.log(`${participant.name} is waiting`)
+  // Show admin UI to approve/reject
+})
+
+// Approve from waitlist (backend only)
+await fetch(
+  `https://api.cloudflare.com/client/v4/accounts/${accountId}/realtime/kit/${appId}/meetings/${meetingId}/active-session/waitlist/approve`,
+  {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiToken}` },
+    body: JSON.stringify({ user_ids: [participant.userId] }),
+  }
+)
+
+// Client receives automatic transition when approved
+meeting.self.on('roomJoined', () => console.log('Approved and joined'))
+```
+
+## Audio-Only Mode
+
+```typescript
+const meeting = new RealtimeKitClient({
+  authToken: '<token>',
+  video: false,  // Disable video
+  audio: true,
+  mediaConfiguration: {
+    audio: {
+      echoCancellation: true,
+      noiseSuppression: true,
+      autoGainControl: true
+    }
+  }
+});
+
+// Use audio grid component
+import { RtkAudioGrid } from '@cloudflare/realtimekit-react-ui';
+<RtkAudioGrid meeting={meeting} />
+```
+
+## Addon System
+
+```typescript
+// List available addons
+meeting.plugins.all.forEach((plugin) => {
+  console.log(plugin.id, plugin.name, plugin.active)
+})
+
+// Activate collaborative app
+await meeting.plugins.activate('whiteboard-addon-id')
+
+// Listen for activations
+meeting.plugins.on('pluginActivated', ({ plugin }) => {
+  console.log(`${plugin.name} activated`)
+})
+
+// Deactivate
+await meeting.plugins.deactivate()
+```
+
+## Backend Integration
+
+### Token Generation (Workers)
+
+```typescript
+export interface Env {
+  CLOUDFLARE_API_TOKEN: string
+  CLOUDFLARE_ACCOUNT_ID: string
+  REALTIMEKIT_APP_ID: string
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url)
+
+    if (url.pathname === '/api/join-meeting') {
+      const { meetingId, userName, presetName } = await request.json()
+      const response = await fetch(
+        `https://api.cloudflare.com/client/v4/accounts/${env.CLOUDFLARE_ACCOUNT_ID}/realtime/kit/${env.REALTIMEKIT_APP_ID}/meetings/${meetingId}/participants`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${env.CLOUDFLARE_API_TOKEN}`,
+          },
+          body: JSON.stringify({ name: userName, preset_name: presetName }),
+        }
+      )
+      const data = await response.json()
+      return Response.json({ authToken: data.result.authToken })
+    }
+
+    return new Response('Not found', { status: 404 })
+  },
+}
+```
+
+## Best Practices
+
+### Security
+
+1. **Never expose API tokens client-side** - Generate participant tokens server-side only
+2. **Don't reuse participant tokens** - Generate fresh token per session, use refresh endpoint if expired
+3. **Use custom participant IDs** - Map to your user system for cross-session tracking
+
+### Performance
+
+1. **Event-driven updates** - Listen to events, don't poll. Use `toArray()` only when needed
+2. **Media quality constraints** - Set appropriate resolution/bitrate limits based on network conditions
+3. **Device management** - Enable `autoSwitchAudioDevice` for better UX, handle device list updates
+
+### Architecture
+
+1. **Separate Apps for environments** - staging vs production to prevent data mixing
+2. **Preset strategy** - Create presets at App level, reuse across meetings
+3. **Token management** - Backend generates tokens, frontend receives via authenticated endpoint
+
+## In This Reference
+
+- [README.md](README.md) - Overview, core concepts, quick start
+- [configuration.md](configuration.md) - SDK config, presets, wrangler setup
+- [api.md](api.md) - Client SDK APIs, REST endpoints
+- [gotchas.md](gotchas.md) - Common issues, troubleshooting, limits

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

@@ -0,0 +1,104 @@
+# Cloudflare Sandbox SDK
+
+Secure isolated code execution in containers on Cloudflare's edge. Run untrusted code, manage files, expose services, integrate with AI agents.
+
+**Use cases**: AI code execution, interactive dev environments, data analysis, CI/CD, code interpreters, multi-tenant execution.
+
+## Architecture
+
+- Each sandbox = Durable Object + Container
+- Persistent across requests (same ID = same sandbox)
+- Isolated filesystem/processes/network
+- Configurable sleep/wake for cost optimization
+
+## Quick Start
+
+```typescript
+import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox'
+export { Sandbox } from '@cloudflare/sandbox'
+
+type Env = { Sandbox: DurableObjectNamespace<Sandbox> }
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // CRITICAL: proxyToSandbox MUST be called first for preview URLs
+    const proxyResponse = await proxyToSandbox(request, env)
+    if (proxyResponse) return proxyResponse
+
+    const sandbox = getSandbox(env.Sandbox, 'my-sandbox')
+    const result = await sandbox.exec('python3 -c "print(2 + 2)"')
+    return Response.json({ output: result.stdout })
+  },
+}
+```
+
+**wrangler.jsonc**:
+
+```jsonc
+{
+  "name": "my-sandbox-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+
+  "containers": [
+    {
+      "class_name": "Sandbox",
+      "image": "./Dockerfile",
+      "instance_type": "lite", // lite | standard | heavy
+      "max_instances": 5,
+    },
+  ],
+
+  "durable_objects": {
+    "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }],
+  },
+
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Sandbox"],
+    },
+  ],
+}
+```
+
+**Dockerfile**:
+
+```dockerfile
+FROM docker.io/cloudflare/sandbox:latest
+RUN pip3 install --no-cache-dir pandas numpy matplotlib
+EXPOSE 8080 3000  # Required for wrangler dev
+```
+
+## Core APIs
+
+- `getSandbox(namespace, id, options?)` → Get/create sandbox
+- `sandbox.exec(command, options?)` → Execute command
+- `sandbox.readFile(path)` / `writeFile(path, content)` → File ops
+- `sandbox.startProcess(command, options)` → Background process
+- `sandbox.exposePort(port, options)` → Get preview URL
+- `sandbox.createSession(options)` → Isolated session
+- `sandbox.wsConnect(request, port)` → WebSocket proxy
+- `sandbox.destroy()` → Terminate container
+- `sandbox.mountBucket(bucket, path, options)` → Mount S3 storage
+
+## Critical Rules
+
+- ALWAYS call `proxyToSandbox()` first
+- Same ID = reuse sandbox
+- Use `/workspace` for persistent files
+- `normalizeId: true` for preview URLs
+- Retry on `CONTAINER_NOT_READY`
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - Config, CLI, environment setup
+- [api.md](./api.md) - Programmatic API, testing patterns
+- [patterns.md](./patterns.md) - Common workflows, CI/CD integration
+- [gotchas.md](./gotchas.md) - Issues, limits, best practices
+
+## See Also
+
+- [durable-objects](../durable-objects/) - Sandbox runs on DO infrastructure
+- [containers](../containers/) - Container runtime fundamentals
+- [workers](../workers/) - Entry point for sandbox requests