memory-journal-mcp 7.7.1 → 8.0.0

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

@@ -0,0 +1,118 @@
+# Cloudflare RealtimeKit
+
+Expert guidance for building real-time video and audio applications using **Cloudflare RealtimeKit** - a comprehensive SDK suite for adding customizable live video and voice to web or mobile applications.
+
+## Overview
+
+RealtimeKit is Cloudflare's SDK suite built on Realtime SFU, abstracting WebRTC complexity with fast integration, pre-built UI components, global performance (300+ cities), and production features (recording, transcription, chat, polls).
+
+**Use cases**: Team meetings, webinars, social video, audio calls, interactive plugins
+
+## Core Concepts
+
+- **App**: Workspace grouping meetings, participants, presets, recordings. Use separate Apps for staging/production
+- **Meeting**: Re-usable virtual room. Each join creates new **Session**
+- **Session**: Live meeting instance. Created on first join, ends after last leave
+- **Participant**: User added via REST API. Returns `authToken` for client SDK. **Do not reuse tokens**
+- **Preset**: Reusable permission/UI template (permissions, meeting type, theme). Applied at participant creation
+- **Peer ID** (`id`): Unique per session, changes on rejoin
+- **Participant ID** (`userId`): Persistent across sessions
+
+## Quick Start
+
+### 1. Create App & Meeting (Backend)
+
+```bash
+# Create app
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "My RealtimeKit App"}'
+
+# Create meeting
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"title": "Team Standup"}'
+
+# Add participant
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/meetings/<meeting_id>/participants' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "Alice", "preset_name": "host"}'
+# Returns: { authToken }
+```
+
+### 2. Client Integration
+
+**React**:
+
+```tsx
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui'
+
+function App() {
+  return <RtkMeeting authToken="<participant_auth_token>" onLeave={() => {}} />
+}
+```
+
+**Core SDK**:
+
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit'
+
+const meeting = new RealtimeKitClient({ authToken: '<token>', video: true, audio: true })
+await meeting.join()
+```
+
+## Reading Order
+
+| Task              | Files                   |
+| ----------------- | ----------------------- |
+| Quick integration | README only             |
+| Custom UI         | README → patterns → api |
+| Backend setup     | README → configuration  |
+| Debug issues      | gotchas                 |
+| Advanced features | patterns → api          |
+
+## RealtimeKit vs Realtime SFU
+
+| Choose           | When                                                    |
+| ---------------- | ------------------------------------------------------- |
+| **RealtimeKit**  | Need pre-built UI, fast integration, React/Angular/HTML |
+| **Realtime SFU** | Building from scratch, custom WebRTC, full control      |
+
+RealtimeKit is built on Realtime SFU but abstracts WebRTC complexity with UI components and SDKs.
+
+## Which Package?
+
+Need pre-built meeting UI?
+
+- React → `@cloudflare/realtimekit-react-ui` (`<RtkMeeting>`)
+- Angular → `@cloudflare/realtimekit-angular-ui`
+- HTML/Vanilla → `@cloudflare/realtimekit-ui`
+
+Need custom UI?
+
+- Core SDK → `@cloudflare/realtimekit` (RealtimeKitClient) - full control
+
+Need raw WebRTC control?
+
+- See `realtime-sfu/` reference
+
+## In This Reference
+
+- [Configuration](./configuration.md) - Setup, installation, wrangler config
+- [API](./api.md) - Meeting object, REST API, SDK methods
+- [Patterns](./patterns.md) - Common workflows, code examples
+- [Gotchas](./gotchas.md) - Common issues, troubleshooting
+
+## See Also
+
+- [Workers](../workers/) - Backend integration
+- [D1](../d1/) - Meeting metadata storage
+- [R2](../r2/) - Recording storage
+- [KV](../kv/) - Session management
+
+## Reference Links
+
+- **Official Docs**: https://developers.cloudflare.com/realtime/realtimekit/
+- **API Reference**: https://developers.cloudflare.com/api/resources/realtime_kit/
+- **Examples**: https://github.com/cloudflare/realtimekit-web-examples
+- **Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit

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

@@ -0,0 +1,234 @@
+# RealtimeKit API Reference
+
+Complete API reference for Meeting object, REST endpoints, and SDK methods.
+
+## Meeting Object API
+
+### `meeting.self` - Local Participant
+
+```typescript
+// Properties: id, userId, name, audioEnabled, videoEnabled, screenShareEnabled, audioTrack, videoTrack, screenShareTracks, roomJoined, roomState
+// Methods
+;(await meeting.self.enableAudio()) /
+  disableAudio() /
+  enableVideo() /
+  disableVideo() /
+  enableScreenShare() /
+  disableScreenShare()
+await meeting.self.setName('Name') // Before join only
+await meeting.self.setDevice(device)
+const devices =
+  (await meeting.self.getAllDevices()) / getAudioDevices() / getVideoDevices() / getSpeakerDevices()
+// Events: 'roomJoined', 'audioUpdate', 'videoUpdate', 'screenShareUpdate', 'deviceUpdate', 'deviceListUpdate'
+meeting.self.on('roomJoined', () => {})
+meeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {})
+```
+
+### `meeting.participants` - Remote Participants
+
+**Collections**:
+
+```typescript
+meeting.participants.joined / active / waitlisted / pinned // Maps
+const participants = meeting.participants.joined.toArray()
+const count = meeting.participants.joined.size()
+const p = meeting.participants.joined.get('peer-id')
+```
+
+**Participant Properties**:
+
+```typescript
+participant.id / userId / name
+participant.audioEnabled / videoEnabled / screenShareEnabled
+participant.audioTrack / videoTrack / screenShareTracks
+```
+
+**Events**:
+
+```typescript
+meeting.participants.joined.on('participantJoined', (participant) => {})
+meeting.participants.joined.on('participantLeft', (participant) => {})
+```
+
+### `meeting.meta` - Metadata
+
+```typescript
+meeting.meta.meetingId / meetingTitle / meetingStartedTimestamp
+```
+
+### `meeting.chat` - Chat
+
+```typescript
+meeting.chat.messages // Array
+;(await meeting.chat.sendTextMessage('Hello')) / sendImageMessage(file)
+meeting.chat.on('chatUpdate', ({ message, messages }) => {})
+```
+
+### `meeting.polls` - Polling
+
+```typescript
+meeting.polls.items // Array
+await meeting.polls.create(question, options, anonymous, hideVotes)
+await meeting.polls.vote(pollId, optionIndex)
+```
+
+### `meeting.plugins` - Collaborative Apps
+
+```typescript
+meeting.plugins.all // Array
+;(await meeting.plugins.activate(pluginId)) / deactivate()
+```
+
+### `meeting.ai` - AI Features
+
+```typescript
+meeting.ai.transcripts // Live transcriptions (when enabled in Preset)
+```
+
+### Core Methods
+
+```typescript
+await meeting.join() // Emits 'roomJoined' on meeting.self
+await meeting.leave()
+```
+
+## TypeScript Types
+
+```typescript
+import type { RealtimeKitClient, States, UIConfig, Participant } from '@cloudflare/realtimekit'
+
+// Main interface
+interface RealtimeKitClient {
+  self: SelfState // Local participant (id, userId, name, audioEnabled, videoEnabled, roomJoined, roomState)
+  participants: { joined; active; waitlisted; pinned } // Reactive Maps
+  chat: ChatNamespace // messages[], sendTextMessage(), sendImageMessage()
+  polls: PollsNamespace // items[], create(), vote()
+  plugins: PluginsNamespace // all[], activate(), deactivate()
+  ai: AINamespace // transcripts[]
+  meta: MetaState // meetingId, meetingTitle, meetingStartedTimestamp
+  join(): Promise<void>
+  leave(): Promise<void>
+}
+
+// Participant (self & remote share same shape)
+interface Participant {
+  id: string // Peer ID (changes on rejoin)
+  userId: string // Persistent participant ID
+  name: string
+  audioEnabled: boolean
+  videoEnabled: boolean
+  screenShareEnabled: boolean
+  audioTrack: MediaStreamTrack | null
+  videoTrack: MediaStreamTrack | null
+  screenShareTracks: MediaStreamTrack[]
+}
+```
+
+## Store Architecture
+
+RealtimeKit uses reactive store (event-driven updates, live Maps):
+
+```typescript
+// Subscribe to state changes
+meeting.self.on('audioUpdate', ({ audioEnabled, audioTrack }) => {})
+meeting.participants.joined.on('participantJoined', (p) => {})
+
+// Access current state synchronously
+const isAudioOn = meeting.self.audioEnabled
+const count = meeting.participants.joined.size()
+```
+
+**Key principles:** State updates emit events after changes. Use `.toArray()` sparingly. Collections are live Maps.
+
+## REST API
+
+Base: `https://api.cloudflare.com/client/v4/accounts/{account_id}/realtime/kit/{app_id}`
+
+### Meetings
+
+```bash
+GET    /meetings                                    # List all
+GET    /meetings/{meeting_id}                       # Get details
+POST   /meetings                                    # Create: {"title": "..."}
+PATCH  /meetings/{meeting_id}                       # Update: {"title": "...", "record_on_start": true}
+```
+
+### Participants
+
+```bash
+GET    /meetings/{meeting_id}/participants                          # List all
+GET    /meetings/{meeting_id}/participants/{participant_id}         # Get details
+POST   /meetings/{meeting_id}/participants                          # Add: {"name": "...", "preset_name": "...", "custom_participant_id": "..."}
+PATCH  /meetings/{meeting_id}/participants/{participant_id}         # Update: {"name": "...", "preset_name": "..."}
+DELETE /meetings/{meeting_id}/participants/{participant_id}         # Delete
+POST   /meetings/{meeting_id}/participants/{participant_id}/token   # Refresh token
+```
+
+### Active Session
+
+```bash
+GET  /meetings/{meeting_id}/active-session               # Get active session
+POST /meetings/{meeting_id}/active-session/kick          # Kick users: {"user_ids": ["id1", "id2"]}
+POST /meetings/{meeting_id}/active-session/kick-all      # Kick all
+POST /meetings/{meeting_id}/active-session/poll          # Create poll: {"question": "...", "options": [...], "anonymous": false}
+```
+
+### Recording
+
+```bash
+GET  /recordings?meeting_id={meeting_id}                 # List recordings
+GET  /recordings/active-recording/{meeting_id}           # Get active recording
+POST /recordings                                         # Start: {"meeting_id": "...", "type": "composite"} (or "track")
+PUT  /recordings/{recording_id}                          # Control: {"action": "pause"} (or "resume", "stop")
+POST /recordings/track                                   # Track recording: {"meeting_id": "...", "layers": [...]}
+```
+
+### Livestreaming
+
+```bash
+GET  /livestreams?exclude_meetings=false                                # List all
+GET  /livestreams/{livestream_id}                                       # Get details
+POST /meetings/{meeting_id}/livestreams                                 # Start for meeting
+POST /meetings/{meeting_id}/active-livestream/stop                      # Stop
+POST /livestreams                                                       # Create independent: returns {ingest_server, stream_key, playback_url}
+```
+
+### Sessions & Analytics
+
+```bash
+GET  /sessions                                                          # List all
+GET  /sessions/{session_id}                                             # Get details
+GET  /sessions/{session_id}/participants                                # List participants
+GET  /sessions/{session_id}/participants/{participant_id}               # Call stats
+GET  /sessions/{session_id}/chat                                        # Download chat CSV
+GET  /sessions/{session_id}/transcript                                  # Download transcript CSV
+GET  /sessions/{session_id}/summary                                     # Get summary
+POST /sessions/{session_id}/summary                                     # Generate summary
+GET  /analytics/daywise?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD      # Day-wise analytics
+GET  /analytics/livestreams/overall                                     # Livestream analytics
+```
+
+### Webhooks
+
+```bash
+GET    /webhooks                    # List all
+POST   /webhooks                    # Create: {"url": "https://...", "events": ["session.started", "session.ended"]}
+PATCH  /webhooks/{webhook_id}       # Update
+DELETE /webhooks/{webhook_id}       # Delete
+```
+
+## Session Lifecycle
+
+```
+Initialization → Join Intent → [Waitlist?] → Meeting Screen (Stage) → Ended
+                                   ↓ Approved
+                               [Rejected → Ended]
+```
+
+UI Kit handles state transitions automatically.
+
+## See Also
+
+- [Configuration](./configuration.md) - Setup and installation
+- [Patterns](./patterns.md) - Usage examples
+- [README](./README.md) - Overview and quick start

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

@@ -0,0 +1,226 @@
+# RealtimeKit Configuration
+
+Configuration guide for RealtimeKit setup, client SDKs, and wrangler integration.
+
+## Installation
+
+### React
+
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-react-ui
+```
+
+### Angular
+
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-angular-ui
+```
+
+### Web Components/HTML
+
+```bash
+npm install @cloudflare/realtimekit @cloudflare/realtimekit-ui
+```
+
+## Client SDK Configuration
+
+### React UI Kit
+
+```tsx
+import { RtkMeeting } from '@cloudflare/realtimekit-react-ui'
+;<RtkMeeting authToken="<token>" onLeave={() => {}} />
+```
+
+### Angular UI Kit
+
+```typescript
+@Component({
+  template: `<rtk-meeting [authToken]="authToken" (rtkLeave)="onLeave($event)"></rtk-meeting>`,
+})
+export class AppComponent {
+  authToken = '<token>'
+  onLeave() {}
+}
+```
+
+### Web Components
+
+```html
+<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>
+```
+
+### Core SDK Configuration
+
+```typescript
+import RealtimeKitClient from '@cloudflare/realtimekit'
+
+const meeting = new RealtimeKitClient({
+  authToken: '<token>',
+  video: true,
+  audio: true,
+  autoSwitchAudioDevice: true,
+  mediaConfiguration: {
+    video: { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } },
+    audio: { echoCancellation: true, noiseSuppression: true, autoGainControl: true },
+    screenshare: { width: { max: 1920 }, height: { max: 1080 }, frameRate: { ideal: 15 } },
+  },
+})
+await meeting.join()
+```
+
+## Backend Setup
+
+### Create App & Credentials
+
+**Dashboard**: https://dash.cloudflare.com/?to=/:account/realtime/kit
+
+**API**:
+
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/apps' \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{"name": "My RealtimeKit App"}'
+```
+
+**Required Permissions**: API token with **Realtime / Realtime Admin** permissions
+
+### Create Presets
+
+```bash
+curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<account_id>/realtime/kit/<app_id>/presets' \
+  -H 'Authorization: Bearer <api_token>' \
+  -d '{
+    "name": "host",
+    "permissions": {
+      "canShareAudio": true,
+      "canShareVideo": true,
+      "canRecord": true,
+      "canLivestream": true,
+      "canStartStopRecording": true
+    }
+  }'
+```
+
+## Wrangler Configuration
+
+### Basic Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "realtimekit-app",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date
+  "vars": {
+    "CLOUDFLARE_ACCOUNT_ID": "abc123",
+    "REALTIMEKIT_APP_ID": "xyz789",
+  },
+  // Secrets: wrangler secret put CLOUDFLARE_API_TOKEN
+}
+```
+
+### With Database & Storage
+
+```jsonc
+{
+  "d1_databases": [{ "binding": "DB", "database_name": "meetings", "database_id": "d1-id" }],
+  "r2_buckets": [{ "binding": "RECORDINGS", "bucket_name": "recordings" }],
+  "kv_namespaces": [{ "binding": "SESSIONS", "id": "kv-id" }],
+}
+```
+
+### Multi-Environment
+
+```bash
+# Deploy to environments
+wrangler deploy --env staging
+wrangler deploy --env production
+```
+
+## TURN Service Configuration
+
+RealtimeKit can use Cloudflare's TURN service for connectivity through restrictive networks:
+
+```jsonc
+// wrangler.jsonc
+{
+  "vars": {
+    "TURN_SERVICE_ID": "your_turn_service_id",
+  },
+  // Set secret: wrangler secret put TURN_SERVICE_TOKEN
+}
+```
+
+TURN automatically configured when enabled in account - no client-side changes needed.
+
+## Theming & Design Tokens
+
+```typescript
+import type { UIConfig } from '@cloudflare/realtimekit';
+
+const uiConfig: UIConfig = {
+  designTokens: {
+    colors: {
+      brand: { 500: '#0066ff', 600: '#0052cc' },
+      background: { 1000: '#1A1A1A', 900: '#2D2D2D' },
+      text: { 1000: '#FFFFFF', 900: '#E0E0E0' }
+    },
+    borderRadius: 'extra-rounded',  // 'rounded' | 'extra-rounded' | 'sharp'
+    theme: 'dark'  // 'light' | 'dark'
+  },
+  logo: { url: 'https://example.com/logo.png', altText: 'Company' }
+};
+
+// Apply to React
+<RtkMeeting authToken={token} config={uiConfig} onLeave={() => {}} />
+
+// Or use CSS variables
+// :root { --rtk-color-brand-500: #0066ff; --rtk-border-radius: 12px; }
+```
+
+## Internationalization (i18n)
+
+### Custom Language Strings
+
+```typescript
+import { useLanguage } from '@cloudflare/realtimekit-ui';
+
+const customLanguage = {
+  'join': 'Entrar',
+  'leave': 'Salir',
+  'mute': 'Silenciar',
+  'unmute': 'Activar audio',
+  'turn_on_camera': 'Encender cámara',
+  'turn_off_camera': 'Apagar cámara',
+  'share_screen': 'Compartir pantalla',
+  'stop_sharing': 'Dejar de compartir'
+};
+
+const t = useLanguage(customLanguage);
+
+// React usage
+<RtkMeeting authToken={token} t={t} onLeave={() => {}} />
+```
+
+### Supported Locales
+
+Default locales available: `en`, `es`, `fr`, `de`, `pt`, `ja`, `zh`
+
+```typescript
+import { setLocale } from '@cloudflare/realtimekit-ui'
+setLocale('es') // Switch to Spanish
+```
+
+## See Also
+
+- [API](./api.md) - Meeting APIs, REST endpoints
+- [Patterns](./patterns.md) - Backend integration examples
+- [README](./README.md) - Overview and quick start