@mohanscodex/spectra-code 0.4.8 → 0.5.0

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

@@ -0,0 +1,212 @@
+# 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-deploy/references/realtimekit/configuration.md

@@ -0,0 +1,203 @@
+# 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

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

@@ -0,0 +1,169 @@
+# 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