@appsocom/protocol 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1588 @@
1
+ /**
2
+ * Shared types between @appsocom/server and @appsocom/client.
3
+ * Mostly types, plus a few tiny constants and helpers both sides share.
4
+ */
5
+ /** Mirrors partytracks' TrackMetadata: what another participant needs to pull a track. */
6
+ export interface TrackMetadata {
7
+ location?: "local" | "remote";
8
+ trackName?: string;
9
+ sessionId?: string;
10
+ mid?: string | null;
11
+ simulcast?: {
12
+ preferredRid: string;
13
+ };
14
+ /** Simulcast layers the publisher sends for this track (camera video only). */
15
+ layers?: VideoLayer[];
16
+ }
17
+ /**
18
+ * Simulcast layer IDs (RIDs). Alphabetical order is priority order, which is
19
+ * what Realtime SFU's "asciibetical" fallback uses: f(ull) > h(alf) > q(uarter).
20
+ */
21
+ export type VideoLayer = "f" | "h" | "q";
22
+ export declare const VIDEO_LAYERS: readonly VideoLayer[];
23
+ /** Per-participant connection rating shown in the UI. */
24
+ export type ConnectionQuality = "excellent" | "good" | "poor" | "lost";
25
+ export declare const CONNECTION_QUALITIES: readonly ConnectionQuality[];
26
+ /** What a viewer wants to receive for one participant's camera. */
27
+ export type VideoQuality = "high" | "medium" | "low" | "off";
28
+ export declare const QUALITY_TO_LAYER: Record<Exclude<VideoQuality, "off">, VideoLayer>;
29
+ export type TrackKind = "audio" | "video" | "screenVideo" | "screenAudio";
30
+ export type ParticipantTracks = Partial<Record<TrackKind, TrackMetadata>>;
31
+ export interface ParticipantState {
32
+ micOn: boolean;
33
+ cameraOn: boolean;
34
+ screenOn: boolean;
35
+ /** Camera is on but its video is paused because the connection is too weak. */
36
+ videoPaused?: boolean;
37
+ /** This participant's own view of their connection, from their WebRTC stats. */
38
+ connectionQuality?: ConnectionQuality;
39
+ /** Free-form app data (hand raised, role label, etc.). Keep it small. */
40
+ custom?: Record<string, unknown>;
41
+ /** The participant's client encrypts its media and messages end to end. */
42
+ e2ee?: boolean;
43
+ /**
44
+ * The participant sends and receives no camera video right now: they chose
45
+ * audio only, use the "audio" data-saver preset, or their network fell back
46
+ * to audio (see `audioFallback`). Show their avatar instead of a frozen tile.
47
+ */
48
+ audioOnly?: boolean;
49
+ /** Audio only because their connection is too weak for video (automatic; comes back by itself). */
50
+ audioFallback?: boolean;
51
+ /** The data-saver preset they use ("off" or absent = none). */
52
+ dataSaver?: DataSaverMode;
53
+ }
54
+ /**
55
+ * Data-saver presets, for costly or weak mobile data:
56
+ * - "off": normal quality.
57
+ * - "low": send one 360p layer (≤300 kbps, 15 fps), receive at most 360p, and
58
+ * only from the active speaker (and spotlighted people); everyone else is audio.
59
+ * - "minimal": send 180p (≤100 kbps, 10 fps), receive at most 180p from the
60
+ * active speaker only, audio capped at 24 kbps.
61
+ * - "audio": no camera video either way (screen shares still come through), audio capped at 24 kbps.
62
+ */
63
+ export type DataSaverMode = "off" | "low" | "minimal" | "audio";
64
+ export declare const DATA_SAVER_MODES: readonly DataSaverMode[];
65
+ /** What a data-saver preset does. Pass your own (any subset) for a custom mode. */
66
+ export interface DataSaverSettings {
67
+ /** Highest quality of other people's camera video you receive. */
68
+ maxReceiveQuality: VideoQuality;
69
+ /**
70
+ * Receive camera video only from this many recent speakers (plus spotlighted
71
+ * people); 0 = everyone (no limit). Others stay audio-only.
72
+ */
73
+ activeSpeakerVideo: number;
74
+ /** Your camera: largest height sent, in pixels (0 = don't send camera video). */
75
+ maxSendHeight: number;
76
+ /** Your camera: bitrate cap in bits/s (0 = no cap beyond the normal layers). */
77
+ maxSendBitrate: number;
78
+ /** Your camera: frame-rate cap (0 = no cap). */
79
+ maxSendFramerate: number;
80
+ /** Your mic: bitrate cap in bits/s (0 = browser default, about 32–40 kbps). */
81
+ maxAudioBitrate: number;
82
+ /** No camera video either way (like room.setAudioOnly(true)). */
83
+ audioOnly: boolean;
84
+ }
85
+ export declare const DATA_SAVER_PRESETS: Record<DataSaverMode, DataSaverSettings>;
86
+ /** A preset name or custom settings (missing fields come from `base`, default "off"). */
87
+ export type DataSaverInput = DataSaverMode | (Partial<DataSaverSettings> & {
88
+ base?: DataSaverMode;
89
+ });
90
+ /** Full settings for a preset name or a partial custom object. Throws on an unknown preset. */
91
+ export declare function resolveDataSaver(input: DataSaverInput | undefined | null): {
92
+ mode: DataSaverMode | "custom";
93
+ settings: DataSaverSettings;
94
+ };
95
+ /**
96
+ * The simulcast layer to ask for: the wanted one if the publisher sends it,
97
+ * else the best one below it, else the lowest one above it. Publishers on a
98
+ * data saver send fewer layers, and announce which.
99
+ */
100
+ export declare function pickLayer(wanted: VideoLayer, layers: readonly VideoLayer[] | undefined): VideoLayer;
101
+ /** Typical bitrates (bits/s) behind estimateDataUsage(). Real use depends on the picture and the network. */
102
+ export declare const TYPICAL_BITRATES: {
103
+ /** Opus voice with the browser's defaults. Silent mics send almost nothing (DTX). */
104
+ audio: number;
105
+ /** One camera at each received quality. */
106
+ video: Record<VideoQuality, number>;
107
+ /** Your camera, all three simulcast layers. */
108
+ sendSimulcast: number;
109
+ };
110
+ export interface DataUsageEstimate {
111
+ /** Megabytes uploaded per hour. */
112
+ sendMBPerHour: number;
113
+ /** Megabytes downloaded per hour. */
114
+ receiveMBPerHour: number;
115
+ totalMBPerHour: number;
116
+ /** Megabytes for `minutes` (default 60). */
117
+ totalMB: number;
118
+ }
119
+ /**
120
+ * Rough data use for a call, to show before joining ("about 90 MB per hour").
121
+ * Assumes your camera is on, up to 3 people talk at once, and without a data
122
+ * saver you watch up to 1 person in high quality (one-on-one) or up to 9 in
123
+ * medium (gallery). While in a call, room.dataUsage has the measured numbers.
124
+ */
125
+ export declare function estimateDataUsage(opts: {
126
+ mode?: DataSaverInput;
127
+ /** People in the call, you included. Default 2. */
128
+ participants?: number;
129
+ /** Your camera on? Default true. */
130
+ camera?: boolean;
131
+ minutes?: number;
132
+ }): DataUsageEstimate;
133
+ /** Media data used in this call (what you'd see on your mobile data bill, roughly). */
134
+ export interface DataUsage {
135
+ /** Bytes uploaded since joining. */
136
+ sentBytes: number;
137
+ /** Bytes downloaded since joining. */
138
+ receivedBytes: number;
139
+ totalBytes: number;
140
+ /** Current upload rate, bits/s (last sample). */
141
+ sendBitrate: number;
142
+ /** Current download rate, bits/s (last sample). */
143
+ receiveBitrate: number;
144
+ /** At the rate of the last ~30 s: megabytes per hour, both ways. */
145
+ mbPerHour: number;
146
+ /** When counting started (ms since epoch). */
147
+ since: number;
148
+ }
149
+ /**
150
+ * What a participant may do. Enforced by the server, not just the client.
151
+ * `screen` covers screen video and screen audio.
152
+ */
153
+ export interface Permissions {
154
+ mic: boolean;
155
+ camera: boolean;
156
+ screen: boolean;
157
+ /** May change other participants' mic/camera/screen permissions (teachers, hosts). */
158
+ moderate: boolean;
159
+ }
160
+ /** A publishable device, as permissions and moderation name them. */
161
+ export type Device = "mic" | "camera" | "screen";
162
+ /** Room-wide settings, shared with everyone in the room. */
163
+ export interface RoomState {
164
+ /** Only moderators (teachers) may join while locked. Present participants stay. */
165
+ locked: boolean;
166
+ /** When false, only moderators can send chat messages. */
167
+ chat: boolean;
168
+ /**
169
+ * userIds a moderator put in the spotlight (everyone should show them large),
170
+ * in order. Empty = no spotlight. At most MAX_SPOTLIGHT.
171
+ */
172
+ spotlight: string[];
173
+ /** New non-moderators wait until a moderator admits them. */
174
+ waitingRoom: boolean;
175
+ /** Breakout groups while breakouts are running (empty = none). */
176
+ breakouts: BreakoutGroup[];
177
+ /**
178
+ * App data your backend attached to the room (PATCH /rooms/:id { metadata }),
179
+ * e.g. a lesson title or agenda. Everyone in the room gets it. Max 4 KB as JSON.
180
+ */
181
+ metadata?: Record<string, unknown>;
182
+ }
183
+ export interface BreakoutGroup {
184
+ id: string;
185
+ name: string;
186
+ /** Who is assigned to this group (connected or not). */
187
+ userIds: string[];
188
+ }
189
+ export declare const MAX_BREAKOUTS = 50;
190
+ export declare const MAX_SPOTLIGHT = 6;
191
+ export interface ChatMessage {
192
+ /** Unique per room; increases with time. */
193
+ id: string;
194
+ /** Sender's participant id, or null when sent by your app's backend. */
195
+ from: string | null;
196
+ fromUserId: string | null;
197
+ fromName: string;
198
+ text: string;
199
+ /** Private message to this userId; null = everyone in the group. */
200
+ to: string | null;
201
+ /** Breakout group it was sent in (null = main room), or "*" = sent by a moderator to every group. */
202
+ group: string | null;
203
+ /** Server time, ms since epoch. */
204
+ at: number;
205
+ }
206
+ /** Longest chat message, in characters. */
207
+ export declare const MAX_CHAT_LENGTH = 2000;
208
+ /** App messages (`send`): at most this many recipients in `to`, and topics up to this length. */
209
+ export declare const MAX_MESSAGE_RECIPIENTS = 100;
210
+ export declare const MAX_TOPIC_LENGTH = 64;
211
+ /**
212
+ * Who may receive a participant's tracks. Default: everyone in the room.
213
+ * Enforced by the server: others only see (and can only pull) tracks they're allowed.
214
+ */
215
+ export interface TrackPermissions {
216
+ /** true = everyone in the room may receive all your tracks (the default). */
217
+ allowAll: boolean;
218
+ /** When allowAll is false: who may receive what. No `kinds` = all your tracks. Max 100 entries. */
219
+ allow?: {
220
+ userId: string;
221
+ kinds?: TrackKind[];
222
+ }[];
223
+ }
224
+ /** Built-in roles for classrooms. Any other role name is a plain label. */
225
+ export type ClassroomRole = "teacher" | "student" | "observer";
226
+ /** Default permissions of the built-in roles. Token `permissions` override these. */
227
+ export declare const RolePermissions: Record<ClassroomRole, Permissions>;
228
+ /**
229
+ * What is behind a participant. "user" = a person with the client library
230
+ * (the default when absent). "ingress" = an outside encoder such as OBS,
231
+ * publishing over WHIP; it has no WebSocket and never sends messages.
232
+ * "bot" = a server-side helper (recorder/streamer) that chose to be visible.
233
+ * "agent" = an AI voice agent started with POST /rooms/:roomId/agents.
234
+ */
235
+ /** "phone": someone who dialled in from a phone (audio only). */
236
+ export type ParticipantKind = "user" | "ingress" | "bot" | "agent" | "phone";
237
+ /** What an AI agent is doing right now (same idea as LiveKit Agents' agent state). */
238
+ export type AgentState = "initializing" | "listening" | "thinking" | "speaking";
239
+ export interface AgentInfo {
240
+ state: AgentState;
241
+ /** The participant the agent listens to (it hears one person at a time). */
242
+ listeningTo?: string;
243
+ /**
244
+ * The agent's video avatar, if it has one. While "starting" (or after
245
+ * "failed") the agent still talks, voice only.
246
+ */
247
+ avatar?: {
248
+ provider: string;
249
+ state: "starting" | "ready" | "failed";
250
+ error?: string;
251
+ };
252
+ /** Set when the agent is an AI participant (POST /rooms/:roomId/ai-participants). */
253
+ ai?: AiParticipantInfo;
254
+ }
255
+ /**
256
+ * What an AI participant does in the room:
257
+ * - "contributor": gives its view when asked (by name, "Ask AI" or a typed question).
258
+ * - "scribe": stays quiet and keeps minutes (who said what, decisions, actions).
259
+ * - "facilitator": keeps to the agenda and time, sums up, invites quiet people in.
260
+ * - "policy": checks what is said against the organisation's policies and flags conflicts.
261
+ * - "co-teacher": a classroom helper the teacher can ask to explain, or hand a topic to teach.
262
+ * - "custom": follows the admin's own instructions.
263
+ */
264
+ export type AiRole = "contributor" | "scribe" | "facilitator" | "policy" | "co-teacher" | "custom";
265
+ export declare const AI_ROLES: AiRole[];
266
+ /** An AI participant's settings, as everyone in the room sees them. */
267
+ export interface AiParticipantInfo {
268
+ role: AiRole;
269
+ /** true: it speaks its answers; false (default): it answers in chat. */
270
+ voice: boolean;
271
+ /** Everyone may ask it directly (hosts always can). */
272
+ directQuestions: boolean;
273
+ /** It draws on the organisation knowledge base. */
274
+ knowledge: boolean;
275
+ /** Where policy flags go: only to hosts (default), or said in the room. */
276
+ flags: "hosts" | "room";
277
+ /** It watches for points that conflict with the organisation's policies. */
278
+ watchPolicy: boolean;
279
+ /** A host paused it: it hears nothing and says nothing until resumed. */
280
+ paused?: boolean;
281
+ /** Co-teacher: it is teaching now (the lesson's id = the agent's id). */
282
+ teaching?: boolean;
283
+ /** Questions waiting for it. */
284
+ queue?: number;
285
+ }
286
+ /** A host's command to an AI participant (WebSocket "ai-control", or POST /rooms/:roomId/ai-participants/:agentId/control). */
287
+ export type AiControl = {
288
+ action: "pause";
289
+ } | {
290
+ action: "resume";
291
+ } | {
292
+ action: "settings";
293
+ voice?: boolean;
294
+ directQuestions?: boolean;
295
+ flags?: "hosts" | "room";
296
+ watchPolicy?: boolean;
297
+ knowledge?: boolean;
298
+ }
299
+ /** Say (or post) a short recap of the discussion so far. */
300
+ | {
301
+ action: "recap";
302
+ }
303
+ /** Post the minutes so far in the chat. */
304
+ | {
305
+ action: "minutes";
306
+ }
307
+ /** Co-teacher: teach a topic, or an approved lesson plan from the library. */
308
+ | {
309
+ action: "teach";
310
+ topic?: string;
311
+ planId?: string;
312
+ notes?: string;
313
+ minutes?: number;
314
+ }
315
+ /** Co-teacher: stop teaching and go back to helping. */
316
+ | {
317
+ action: "stop-teaching";
318
+ };
319
+ /** The AI noticed a point that conflicts with the organisation's knowledge (usually a policy). */
320
+ export interface AiFlag {
321
+ id: string;
322
+ at: number;
323
+ /** Who said it. */
324
+ userId: string;
325
+ name: string;
326
+ /** What was said (short). */
327
+ quote: string;
328
+ /** What the conflict is, in a sentence or two. */
329
+ issue: string;
330
+ /** The document it conflicts with. */
331
+ source?: {
332
+ docId: string;
333
+ title: string;
334
+ };
335
+ severity: "info" | "warning";
336
+ }
337
+ /** Running minutes kept by every AI participant. */
338
+ export interface AiMinutes {
339
+ /** Short summary of the discussion. */
340
+ summary: string;
341
+ /** Each person's contributions. */
342
+ people: {
343
+ userId: string;
344
+ name: string;
345
+ points: string[];
346
+ turns: number;
347
+ }[];
348
+ decisions: string[];
349
+ actions: {
350
+ who?: string;
351
+ what: string;
352
+ due?: string;
353
+ }[];
354
+ openQuestions: string[];
355
+ updatedAt: number;
356
+ }
357
+ /** A document in a project's knowledge base. */
358
+ export interface KnowledgeDoc {
359
+ id: string;
360
+ title: string;
361
+ /** Set when the document belongs to one room only (its syllabus, agenda…); otherwise the whole organisation's. */
362
+ room?: string;
363
+ /** "policy" documents are what AI participants check discussions against. */
364
+ kind: "policy" | "reference";
365
+ /** Where it came from: a file, typed text, a Google Docs link, or a web page / site crawl (`pages` read). */
366
+ source: {
367
+ type: "upload" | "text" | "link" | "web";
368
+ name?: string;
369
+ url?: string;
370
+ pages?: number;
371
+ crawl?: number;
372
+ };
373
+ /** Passages it was split into (0 while waiting for review). */
374
+ chunks: number;
375
+ chars: number;
376
+ /**
377
+ * "review": read and previewed, waiting for an admin to approve it (the AI
378
+ * doesn't use it yet). "ready": in use. "failed": couldn't be read.
379
+ */
380
+ status: "review" | "ready" | "failed";
381
+ error?: string;
382
+ /** The AI's preview: what it understood, suggested tags, and parts it couldn't read. Shown before approving. */
383
+ preview?: KnowledgePreview;
384
+ /** Short summary (from the approved preview). */
385
+ summary?: string;
386
+ tags?: string[];
387
+ /** Web imports: re-read on this schedule; a changed page waits for review as `pendingUpdate`. */
388
+ recheck?: "daily" | "weekly";
389
+ checkedAt?: number;
390
+ /** A newer version (a re-check found changes, or the text was edited) is waiting for review; the AI still uses the approved one. */
391
+ pendingUpdate?: boolean;
392
+ createdAt: number;
393
+ updatedAt: number;
394
+ }
395
+ /** A passage found in the knowledge base. */
396
+ export interface KnowledgePreview {
397
+ summary: string;
398
+ tags: string[];
399
+ /** Parts that couldn't be read, pages skipped, text cut short, things that look wrong. */
400
+ issues: string[];
401
+ /** The first part of the text as read, to check it came through properly. */
402
+ excerpt: string;
403
+ }
404
+ export interface KnowledgeHit {
405
+ docId: string;
406
+ title: string;
407
+ /** The room the passage's document belongs to (absent: the organisation's). */
408
+ room?: string;
409
+ kind: "policy" | "reference";
410
+ /** The heading the passage sits under ("Fees › Term fees"), when the document has headings. */
411
+ section?: string;
412
+ tags?: string[];
413
+ /** Where it came from (a web address, file name or "text"), and when the approved version was last updated. */
414
+ source?: string;
415
+ updatedAt?: number;
416
+ text: string;
417
+ score: number;
418
+ }
419
+ export interface Participant {
420
+ /** Unique per connection (one user in two tabs = two participants). */
421
+ id: string;
422
+ /** Absent means "user". */
423
+ kind?: ParticipantKind;
424
+ /** Set only when kind is "agent". */
425
+ agent?: AgentInfo;
426
+ userId: string;
427
+ name: string;
428
+ /**
429
+ * "teacher", "student", "observer", any label your app chose, or, for tokens
430
+ * minted without a role, "participant" (may publish) / "viewer" (may not).
431
+ */
432
+ role: string;
433
+ /** Current permissions, including changes made during the call. */
434
+ permissions: Permissions;
435
+ /** True if any of mic/camera/screen is allowed. */
436
+ canPublish: boolean;
437
+ /** When this user raised their hand (ms since epoch, set by the server), or null. */
438
+ handRaisedAt: number | null;
439
+ /** True when this person asked AI participants not to hear them (their speech and chat are left out). */
440
+ aiOptOut?: boolean;
441
+ /** Breakout group id, or null = main room. You only see participants of your own group. */
442
+ group: string | null;
443
+ /**
444
+ * App data your backend attached to this user (join token `metadata`, or
445
+ * PATCH /rooms/:id/participants/:userId). Shared with everyone; participants
446
+ * can't change it themselves (use state.custom for that). Max 4 KB as JSON.
447
+ */
448
+ metadata?: Record<string, unknown>;
449
+ /**
450
+ * Track kinds this participant publishes that YOU aren't allowed to receive
451
+ * (their track permissions). Those tracks are left out of `tracks`.
452
+ */
453
+ restricted?: TrackKind[];
454
+ joinedAt: number;
455
+ tracks: ParticipantTracks;
456
+ state: ParticipantState;
457
+ }
458
+ /** Claims carried in a join token. */
459
+ export interface JoinClaims {
460
+ /** userId */
461
+ sub: string;
462
+ /** roomId */
463
+ room: string;
464
+ name: string;
465
+ /** may publish anything at all (any of perm.mic/camera/screen) */
466
+ pub: boolean;
467
+ /** Room size limit carried by this token (e.g. 2 for a one-on-one call). */
468
+ max?: number;
469
+ /** role label (absent in tokens minted before roles existed) */
470
+ role?: string;
471
+ /** permissions (absent in older tokens: derived from `pub`) */
472
+ perm?: Permissions;
473
+ /** participant metadata set by your backend */
474
+ md?: Record<string, unknown>;
475
+ /** Must use end-to-end encryption: the room refuses tracks until the client says it encrypts. */
476
+ e2ee?: boolean;
477
+ /** Data-saver preset the client starts with (it can still change it). */
478
+ ds?: DataSaverMode;
479
+ /** tenant (absent = the default tenant). Set when a tenant's API key minted the token. */
480
+ ten?: string;
481
+ exp: number;
482
+ iat: number;
483
+ }
484
+ /**
485
+ * A WHIP ingest point for a room (e.g. OBS). Created by your backend with
486
+ * POST /rooms/:roomId/ingress. The stream key is shown only once, at creation.
487
+ */
488
+ /** How an outside stream reaches the room. */
489
+ export type IngressProtocol = "whip" | "rtmp";
490
+ export interface IngressInfo {
491
+ ingressId: string;
492
+ roomId: string;
493
+ /**
494
+ * "whip": the encoder (OBS 30+) publishes straight into the room.
495
+ * "rtmp": the encoder sends RTMPS or SRT to a Cloudflare Stream live input,
496
+ * and the sfukit bot brings it into the room while anyone is there.
497
+ */
498
+ protocol: IngressProtocol;
499
+ /** Display name of the participant the stream appears as. */
500
+ name: string;
501
+ /** userId of that participant (default "ingress-<ingressId>"). */
502
+ userId: string;
503
+ /** protocol "whip": paste into OBS (Settings → Stream → Service "WHIP" → Server). */
504
+ whipUrl?: string;
505
+ /** protocol "rtmp": the Cloudflare Stream live input behind it. */
506
+ streamInputId?: string;
507
+ /**
508
+ * protocol "rtmp": the encoder's connection to Stream right now
509
+ * ("connected", "reconnecting", "client_disconnect", ...; null = never connected).
510
+ */
511
+ encoderStatus?: string | null;
512
+ createdAt: number;
513
+ /** True while an encoder is connected and publishing. */
514
+ live: boolean;
515
+ /** When the current stream started (ms), if live. */
516
+ liveSince?: number;
517
+ }
518
+ /** Returned once by POST /rooms/:roomId/ingress. */
519
+ export interface CreatedIngress extends IngressInfo {
520
+ /** protocol "whip": paste into OBS as the "Bearer Token". Store it like a password. */
521
+ streamKey?: string;
522
+ /** protocol "rtmp": OBS Service "Custom", Server = url, Stream Key = streamKey. */
523
+ rtmps?: {
524
+ url: string;
525
+ streamKey: string;
526
+ };
527
+ /** protocol "rtmp": SRT alternative (srt://… with streamid + passphrase). */
528
+ srt?: {
529
+ url: string;
530
+ streamId: string;
531
+ passphrase: string;
532
+ };
533
+ }
534
+ /** Where a room's live stream goes. Keys are never returned by the API. */
535
+ export interface EgressDestination {
536
+ /** Stream output id (via Cloudflare Stream) or "direct". */
537
+ id: string;
538
+ name?: string;
539
+ /** RTMP(S) server URL, without the stream key. */
540
+ url: string;
541
+ }
542
+ export type EgressStatus = "starting" | "live" | "stopped" | "failed";
543
+ /** A room being streamed out (POST /rooms/:roomId/egress). */
544
+ export interface EgressInfo {
545
+ egressId: string;
546
+ roomId: string;
547
+ status: EgressStatus;
548
+ /** "cloudflare-stream": bot → Stream live input → HLS viewers + simulcast outputs. "direct": bot → one RTMP(S) server. */
549
+ via: "cloudflare-stream" | "direct";
550
+ layout: "grid";
551
+ width: number;
552
+ height: number;
553
+ /** Stream records the broadcast (via Cloudflare Stream only). */
554
+ record: boolean;
555
+ /** Viewer links (via Cloudflare Stream only). */
556
+ playback?: {
557
+ hls?: string;
558
+ dash?: string;
559
+ iframe?: string;
560
+ };
561
+ /** The Cloudflare Stream live input the bot sends to. */
562
+ streamInputId?: string;
563
+ destinations: EgressDestination[];
564
+ createdAt: number;
565
+ stoppedAt?: number;
566
+ error?: string;
567
+ }
568
+ /** In a "tracks" update, null removes that track (e.g. screen share stopped). */
569
+ export type TrackUpdate = Partial<Record<TrackKind, TrackMetadata | null>>;
570
+ export type ClientMessage = {
571
+ type: "tracks";
572
+ tracks: TrackUpdate;
573
+ }
574
+ /** A fresh join token for the same room and user: extends this connection past the old token's expiry. */
575
+ | {
576
+ type: "token";
577
+ token: string;
578
+ } | {
579
+ type: "state";
580
+ state: Partial<ParticipantState>;
581
+ }
582
+ /**
583
+ * App message. `to` limits it to these userIds (up to 100; default everyone
584
+ * else in your breakout group); `topic` (up to 64 characters) is passed through
585
+ * so apps can route messages (e.g. "whiteboard", "effects").
586
+ */
587
+ | {
588
+ type: "broadcast";
589
+ data: unknown;
590
+ to?: string[];
591
+ topic?: string;
592
+ }
593
+ /** Own mic level 0–1 for active-speaker detection; 0 = stopped speaking. */
594
+ | {
595
+ type: "speaking";
596
+ level: number;
597
+ }
598
+ /**
599
+ * Moderators only: change what a user may publish, for all their connections.
600
+ * Only mic/camera/screen; `moderate` can be changed by your backend (admin API).
601
+ */
602
+ | {
603
+ type: "set-permissions";
604
+ userId: string;
605
+ permissions: Partial<Omit<Permissions, "moderate">>;
606
+ }
607
+ /**
608
+ * Moderators only: turn off devices of one user, or of everyone who isn't a
609
+ * moderator (userId "*"). `lock: true` also takes the permission away, so they
610
+ * can't turn it back on until allowed again (set-permissions).
611
+ */
612
+ | {
613
+ type: "mute";
614
+ userId: string;
615
+ devices: Device[];
616
+ lock?: boolean;
617
+ }
618
+ /** Moderators only: remove a (non-moderator) user. `ban: true` keeps them out until the room empties. */
619
+ | {
620
+ type: "remove";
621
+ userId: string;
622
+ ban?: boolean;
623
+ }
624
+ /** Raise or lower your own hand. Anyone may, observers included. */
625
+ | {
626
+ type: "hand";
627
+ raised: boolean;
628
+ }
629
+ /** Keep (true) or stop keeping yourself out of what AI participants hear. */
630
+ | {
631
+ type: "ai-opt-out";
632
+ optOut: boolean;
633
+ }
634
+ /** Moderators only: lower a user's hand, or everyone's ("*"). */
635
+ | {
636
+ type: "lower-hand";
637
+ userId: string;
638
+ }
639
+ /**
640
+ * Chat. `to` sends privately to one userId; private messages must involve a
641
+ * moderator on one side (student ↔ teacher). Not allowed while chat is off,
642
+ * except for moderators.
643
+ */
644
+ | {
645
+ type: "chat";
646
+ text: string;
647
+ to?: string;
648
+ everywhere?: boolean;
649
+ }
650
+ /** Moderators only: delete a chat message for everyone. */
651
+ | {
652
+ type: "chat-delete";
653
+ id: string;
654
+ }
655
+ /** Moderators only: start breakouts, putting users into named groups (replaces any running). */
656
+ | {
657
+ type: "breakouts";
658
+ groups: {
659
+ name: string;
660
+ userIds: string[];
661
+ }[];
662
+ }
663
+ /** Moderators only: move a user (yourself = visit) to a group id, or null = main room. */
664
+ | {
665
+ type: "move";
666
+ userId: string;
667
+ group: string | null;
668
+ }
669
+ /** Moderators only: end breakouts; everyone returns to the main room. */
670
+ | {
671
+ type: "end-breakouts";
672
+ }
673
+ /** Moderators only: let a waiting user in ("*" = everyone waiting). */
674
+ | {
675
+ type: "admit";
676
+ userId: string;
677
+ }
678
+ /** Moderators only: turn a waiting user away. */
679
+ | {
680
+ type: "deny";
681
+ userId: string;
682
+ }
683
+ /** Moderators only: ask for the attendance report (answered with an `attendance` message). */
684
+ | {
685
+ type: "attendance";
686
+ }
687
+ /** Moderators only: change room-wide settings. */
688
+ | {
689
+ type: "room";
690
+ locked?: boolean;
691
+ chat?: boolean;
692
+ spotlight?: string[];
693
+ waitingRoom?: boolean;
694
+ }
695
+ /** Moderators only: start / stop recording the room to R2. `video` needs the recorder bot. */
696
+ | {
697
+ type: "start-recording";
698
+ video?: boolean;
699
+ } | {
700
+ type: "stop-recording";
701
+ }
702
+ /** Choose who may receive your tracks (see TrackPermissions). */
703
+ | {
704
+ type: "track-permissions";
705
+ permissions: TrackPermissions;
706
+ }
707
+ /** Type to an AI agent instead of speaking (the agent answers out loud). */
708
+ | {
709
+ type: "agent-text";
710
+ agentId: string;
711
+ text: string;
712
+ }
713
+ /** A quick emoji reaction shown to everyone (rate limited). */
714
+ | {
715
+ type: "reaction";
716
+ emoji: string;
717
+ }
718
+ /** Ask the AI teacher of a lesson a question by typing (it answers out loud when it fits). */
719
+ | {
720
+ type: "lesson-ask";
721
+ lessonId: string;
722
+ text: string;
723
+ }
724
+ /** Moderators only: steer an AI lesson (pause, take over, call on someone, …). */
725
+ | {
726
+ type: "lesson-control";
727
+ lessonId: string;
728
+ control: LessonControl;
729
+ }
730
+ /**
731
+ * Ask an AI participant something by typing ("Ask AI"). `private`: the
732
+ * answer comes to you alone, in chat. Non-hosts need its directQuestions on.
733
+ */
734
+ | {
735
+ type: "ai-ask";
736
+ agentId: string;
737
+ text: string;
738
+ private?: boolean;
739
+ }
740
+ /** Hosts only: pause, resume, change or steer an AI participant. */
741
+ | {
742
+ type: "ai-control";
743
+ agentId: string;
744
+ control: AiControl;
745
+ }
746
+ /** Hosts only (see canHost): start a poll. */
747
+ | {
748
+ type: "poll-create";
749
+ poll: PollInput;
750
+ }
751
+ /** Vote (again, to change your vote). `choices` are option indexes; one unless the poll allows multiple. */
752
+ | {
753
+ type: "poll-vote";
754
+ pollId: string;
755
+ choices: number[];
756
+ }
757
+ /** Hosts only. */
758
+ | {
759
+ type: "poll-close";
760
+ pollId: string;
761
+ } | {
762
+ type: "poll-delete";
763
+ pollId: string;
764
+ }
765
+ /** Ask a question (Q&A). `anonymous` hides your name from everyone but hosts. */
766
+ | {
767
+ type: "question-ask";
768
+ text: string;
769
+ anonymous?: boolean;
770
+ } | {
771
+ type: "question-upvote";
772
+ id: string;
773
+ up: boolean;
774
+ }
775
+ /** Hosts only. */
776
+ | {
777
+ type: "question-answer";
778
+ id: string;
779
+ answered: boolean;
780
+ }
781
+ /** Hosts, or whoever asked. */
782
+ | {
783
+ type: "question-delete";
784
+ id: string;
785
+ }
786
+ /**
787
+ * Hosts only: turn live captions on/off for the room. `server`: transcribe
788
+ * everyone's mic on the server (works for every SDK) instead of clients uploading clips.
789
+ */
790
+ | {
791
+ type: "captions";
792
+ on: boolean;
793
+ language?: string;
794
+ translate?: boolean;
795
+ server?: boolean;
796
+ }
797
+ /** The language you read captions in (ISO 639-1, e.g. "fr"); null = as spoken. */
798
+ | {
799
+ type: "caption-language";
800
+ language: string | null;
801
+ } | {
802
+ type: "ping";
803
+ };
804
+ /** One piece of a live transcript. Partial segments are re-sent with the same id until final. */
805
+ export interface TranscriptSegment {
806
+ /** Stable per utterance. */
807
+ id: string;
808
+ /** The agent this conversation belongs to. */
809
+ agentId: string;
810
+ /** Who said it: the agent's participant id, or the person's. */
811
+ speakerId: string;
812
+ role: "user" | "agent";
813
+ text: string;
814
+ final: boolean;
815
+ }
816
+ export type ServerMessage = {
817
+ type: "welcome";
818
+ self: Participant;
819
+ participants: Participant[];
820
+ room: RoomState;
821
+ recording?: RecordingStatus | null;
822
+ } | {
823
+ type: "room-updated";
824
+ room: RoomState;
825
+ }
826
+ /** Instead of welcome: you're in the waiting room. `welcome` follows once admitted. */
827
+ | {
828
+ type: "waiting";
829
+ }
830
+ /** You were moved to another group: these are the participants you see now (like a new welcome). */
831
+ | {
832
+ type: "group-changed";
833
+ group: string | null;
834
+ participants: Participant[];
835
+ } | {
836
+ type: "attendance";
837
+ report: AttendanceReport;
838
+ }
839
+ /** Moderators only: who is in the waiting room now, first come first. */
840
+ | {
841
+ type: "waiting-list";
842
+ waiting: Participant[];
843
+ } | {
844
+ type: "chat";
845
+ message: ChatMessage;
846
+ }
847
+ /** Recent public messages, oldest first. Sent right after welcome. */
848
+ | {
849
+ type: "chat-history";
850
+ messages: ChatMessage[];
851
+ } | {
852
+ type: "chat-deleted";
853
+ id: string;
854
+ }
855
+ /** A moderator (participant id) or your app's backend (null) turned off these devices of yours. */
856
+ | {
857
+ type: "muted";
858
+ devices: Device[];
859
+ by: string | null;
860
+ }
861
+ /** Recording started (status) or stopped (null). Show a "recording" indicator while it's set. */
862
+ | {
863
+ type: "recording";
864
+ recording: RecordingStatus | null;
865
+ } | {
866
+ type: "participant-joined";
867
+ participant: Participant;
868
+ } | {
869
+ type: "participant-updated";
870
+ participant: Participant;
871
+ }
872
+ /** Your own record changed (e.g. a teacher changed your permissions). */
873
+ | {
874
+ type: "self-updated";
875
+ self: Participant;
876
+ } | {
877
+ type: "participant-left";
878
+ id: string;
879
+ userId: string;
880
+ } | {
881
+ type: "broadcast";
882
+ from: string;
883
+ data: unknown;
884
+ topic?: string;
885
+ private?: boolean;
886
+ } | {
887
+ type: "speaking";
888
+ from: string;
889
+ level: number;
890
+ } | {
891
+ type: "transcript";
892
+ segment: TranscriptSegment;
893
+ }
894
+ /** Someone reacted. Sent to everyone, including the sender. */
895
+ | {
896
+ type: "reaction";
897
+ from: string;
898
+ userId: string;
899
+ emoji: string;
900
+ at: number;
901
+ }
902
+ /** A file was shared in the room (upload with POST /rooms/:roomId/files). */
903
+ | {
904
+ type: "file-shared";
905
+ file: SharedFile;
906
+ } | {
907
+ type: "file-removed";
908
+ id: string;
909
+ }
910
+ /** A poll was created or changed (votes are coalesced, at most ~2 updates a second). */
911
+ | {
912
+ type: "poll";
913
+ poll: Poll;
914
+ } | {
915
+ type: "poll-removed";
916
+ id: string;
917
+ }
918
+ /** Your own vote, as the server recorded it (sent to all your connections). */
919
+ | {
920
+ type: "poll-voted";
921
+ pollId: string;
922
+ choices: number[];
923
+ } | {
924
+ type: "question";
925
+ question: Question;
926
+ } | {
927
+ type: "question-removed";
928
+ id: string;
929
+ }
930
+ /** Your own upvote, as the server recorded it. */
931
+ | {
932
+ type: "question-upvoted";
933
+ id: string;
934
+ up: boolean;
935
+ }
936
+ /** Captions were turned on/off or their settings changed. */
937
+ | {
938
+ type: "captions-state";
939
+ captions: CaptionsState;
940
+ }
941
+ /** A new caption line (one speaker, one phrase). */
942
+ | {
943
+ type: "caption";
944
+ line: TranscriptLine;
945
+ translation?: CaptionTranslation;
946
+ }
947
+ /** A host (or your backend) generated a summary of the call so far. */
948
+ | {
949
+ type: "summary";
950
+ summary: CallSummary;
951
+ }
952
+ /** An AI lesson started or changed (slide, whiteboard, floor, quiz, timer…). Also sent right after welcome. */
953
+ | {
954
+ type: "lesson";
955
+ lesson: LessonState;
956
+ }
957
+ /** Moderators only: the AI teacher is worried about a learner (safeguarding) or needs a human. */
958
+ | {
959
+ type: "lesson-alert";
960
+ lessonId: string;
961
+ alert: LessonAlert;
962
+ }
963
+ /** An AI participant flagged a point (hosts only, unless its flags go to the room). */
964
+ | {
965
+ type: "ai-flag";
966
+ agentId: string;
967
+ flag: AiFlag;
968
+ }
969
+ /** Hosts only: an AI participant's minutes so far (after "minutes", and when it leaves). */
970
+ | {
971
+ type: "ai-minutes";
972
+ agentId: string;
973
+ minutes: AiMinutes;
974
+ }
975
+ /** The AI lesson ended (its report is at GET /lessons/:lessonId/report). */
976
+ | {
977
+ type: "lesson-ended";
978
+ lessonId: string;
979
+ }
980
+ /** Sent right after "welcome" (and after each reconnect): files, polls, questions, captions. */
981
+ | {
982
+ type: "engage-state";
983
+ state: EngageState;
984
+ } | {
985
+ type: "pong";
986
+ } | {
987
+ type: "error";
988
+ message: string;
989
+ }
990
+ /** Sent right before the server closes the socket on purpose. */
991
+ | {
992
+ type: "bye";
993
+ code: number;
994
+ reason: string;
995
+ };
996
+ /** A recording in progress, as every participant sees it. */
997
+ export interface RecordingStatus {
998
+ id: string;
999
+ /** ms since epoch */
1000
+ startedAt: number;
1001
+ /** userId of the moderator who started it, or "admin" (your backend). */
1002
+ startedBy: string;
1003
+ /** true: the recorder bot records audio + video (WebM per track). false: audio only (WAV per track). */
1004
+ video: boolean;
1005
+ }
1006
+ /**
1007
+ * One file in a recording: one participant's track from when it appeared (or
1008
+ * the recording started) until it went away (or the recording stopped).
1009
+ * Audio-only recordings: mono 48 kHz WAV. Video recordings: WebM per track
1010
+ * (Opus audio, VP8/VP9 video).
1011
+ */
1012
+ export interface RecordingFile {
1013
+ /** R2 object key */
1014
+ key: string;
1015
+ userId: string;
1016
+ name: string;
1017
+ kind: TrackKind;
1018
+ format: "wav" | "webm";
1019
+ /** "pcm_s16le" (wav), "opus", "vp8", "vp9" */
1020
+ codec: string;
1021
+ /** audio files */
1022
+ sampleRate?: 48000;
1023
+ channels?: 1 | 2;
1024
+ /** video files, from the first keyframe (0 if unknown) */
1025
+ width?: number;
1026
+ height?: number;
1027
+ /** ms since epoch: when this file's first sample was heard (use it to line tracks up). */
1028
+ startedAt: number;
1029
+ endedAt: number;
1030
+ durationMs: number;
1031
+ bytes: number;
1032
+ }
1033
+ /** Written to R2 as rooms/<roomId>/recordings/<recordingId>/manifest.json when a recording stops. */
1034
+ export interface RecordingManifest {
1035
+ version: 1;
1036
+ roomId: string;
1037
+ recordingId: string;
1038
+ startedAt: number;
1039
+ stoppedAt: number;
1040
+ startedBy: string;
1041
+ /** "admin", "moderator:<userId>", "room-empty" or "room-closed" */
1042
+ stopReason: string;
1043
+ files: RecordingFile[];
1044
+ /** Tracks that could not be recorded (e.g. the SFU refused the adapter). */
1045
+ errors: string[];
1046
+ /**
1047
+ * Video recordings: every track combined into one grid MP4 (H.264 + AAC);
1048
+ * audio recordings started with { mix: true }: every mic mixed into one
1049
+ * AAC file (mixed.m4a). Rendered after the recording stops: "pending"
1050
+ * until the bot uploads it; this manifest is rewritten when it's "ready" (or "failed").
1051
+ */
1052
+ composite?: {
1053
+ key: string;
1054
+ status: "pending" | "ready" | "failed";
1055
+ width?: number;
1056
+ height?: number;
1057
+ durationMs?: number;
1058
+ bytes?: number;
1059
+ error?: string;
1060
+ };
1061
+ }
1062
+ /** A file shared in the call. Stored in the Worker's R2 bucket until the room empties. */
1063
+ export interface SharedFile {
1064
+ id: string;
1065
+ name: string;
1066
+ /** Bytes. */
1067
+ size: number;
1068
+ /** MIME type the uploader gave (downloads are always served as attachments). */
1069
+ type: string;
1070
+ userId: string;
1071
+ /** Display name of the uploader. */
1072
+ from: string;
1073
+ at: number;
1074
+ }
1075
+ export interface PollInput {
1076
+ question: string;
1077
+ /** 2-10 options. */
1078
+ options: string[];
1079
+ /** Allow picking more than one option. Default false. */
1080
+ multiple?: boolean;
1081
+ /** Hide who voted for what from hosts too. Default false. */
1082
+ anonymous?: boolean;
1083
+ /** Only hosts see results until the poll closes. Default false (live results). */
1084
+ hideResults?: boolean;
1085
+ }
1086
+ export interface Poll {
1087
+ id: string;
1088
+ question: string;
1089
+ options: string[];
1090
+ multiple: boolean;
1091
+ anonymous: boolean;
1092
+ hideResults: boolean;
1093
+ /** Votes per option. Empty while results are hidden from you. */
1094
+ counts: number[];
1095
+ /** How many people voted. */
1096
+ voters: number;
1097
+ closed: boolean;
1098
+ createdBy: string;
1099
+ at: number;
1100
+ /**
1101
+ * Hosts only, non-anonymous polls: userId → choices. Names are in `voterNames`.
1102
+ */
1103
+ votes?: Record<string, number[]>;
1104
+ voterNames?: Record<string, string>;
1105
+ }
1106
+ export interface Question {
1107
+ id: string;
1108
+ text: string;
1109
+ /** Empty for anonymous questions (except for hosts). */
1110
+ userId: string;
1111
+ from: string;
1112
+ anonymous: boolean;
1113
+ upvotes: number;
1114
+ answered: boolean;
1115
+ at: number;
1116
+ }
1117
+ export interface CaptionsState {
1118
+ on: boolean;
1119
+ /** Spoken language hint (ISO 639-1, e.g. "en"); unset = detect per phrase. */
1120
+ language?: string;
1121
+ /** Translate speech into English captions. */
1122
+ translate?: boolean;
1123
+ /** When captions were first turned on in this room (transcript time 0). */
1124
+ startedAt?: number;
1125
+ /** Transcribed on the server from each mic, so clients don't upload clips. */
1126
+ server?: boolean;
1127
+ }
1128
+ /** A caption line in the language you asked for (see "caption-language"). */
1129
+ export interface CaptionTranslation {
1130
+ language: string;
1131
+ text: string;
1132
+ }
1133
+ export interface TranscriptLine {
1134
+ /** Increasing per room. */
1135
+ seq: number;
1136
+ userId: string;
1137
+ name: string;
1138
+ text: string;
1139
+ /** When the phrase started (server-adjusted ms since epoch). */
1140
+ at: number;
1141
+ /** Length of the audio in seconds. */
1142
+ duration: number;
1143
+ /** The spoken language, when the speech model reports it (ISO 639-1). */
1144
+ language?: string;
1145
+ }
1146
+ export interface CallSummary {
1147
+ text: string;
1148
+ at: number;
1149
+ /** How many transcript lines it covers. */
1150
+ lines: number;
1151
+ }
1152
+ /** Room-wide engagement state, sent after welcome. */
1153
+ export interface EngageState {
1154
+ captions: CaptionsState;
1155
+ /** The most recent caption lines (up to 50). The full transcript is on GET /rooms/:id/transcript. */
1156
+ recentCaptions: TranscriptLine[];
1157
+ summary?: CallSummary;
1158
+ files: SharedFile[];
1159
+ polls: Poll[];
1160
+ /** Your own votes: pollId → choices. */
1161
+ myVotes: Record<string, number[]>;
1162
+ questions: Question[];
1163
+ /** Question ids you upvoted. */
1164
+ myUpvotes: string[];
1165
+ }
1166
+ /**
1167
+ * Who may run polls, Q&A moderation (and captions): anyone with `moderate`, or
1168
+ * everyone in rooms without roles (tokens minted without a role).
1169
+ */
1170
+ export declare function canHost(p: Pick<Participant, "role" | "permissions">): boolean;
1171
+ /** Emoji reactions: 1-16 chars of emoji (incl. ZWJ sequences, skin tones, flags). */
1172
+ export declare const REACTION_PATTERN: RegExp;
1173
+ export declare function isValidReaction(emoji: unknown): emoji is string;
1174
+ /** WebSocket close codes used by the kit. Clients must not auto-reconnect on these. */
1175
+ export declare const CloseCodes: {
1176
+ readonly Kicked: 4001;
1177
+ readonly RoomFull: 4002;
1178
+ readonly Unauthorized: 4003;
1179
+ readonly RoomClosed: 4004;
1180
+ /** The room is locked and you aren't a moderator. */
1181
+ readonly RoomLocked: 4005;
1182
+ /** A moderator turned you away from the waiting room. */
1183
+ readonly Denied: 4006;
1184
+ };
1185
+ /** The permissions a set of verified claims grant (before any changes made during the call). */
1186
+ export declare function claimsPermissions(claims: Pick<JoinClaims, "pub" | "role" | "perm">): Permissions;
1187
+ /** The role a set of claims carries, with the pre-roles fallback. */
1188
+ export declare function claimsRole(claims: Pick<JoinClaims, "pub" | "role">): string;
1189
+ /** Largest metadata object (room or participant), as JSON characters. */
1190
+ export declare const MAX_METADATA_BYTES = 4096;
1191
+ export declare function canPublishAny(p: Permissions): boolean;
1192
+ /** One stay in the room (join → leave) of one connection. Time in the waiting room isn't counted. */
1193
+ export interface AttendanceSession {
1194
+ userId: string;
1195
+ name: string;
1196
+ role: string;
1197
+ joinedAt: number;
1198
+ /** null = still in the room */
1199
+ leftAt: number | null;
1200
+ }
1201
+ /** Per-user totals for a room. */
1202
+ export interface AttendanceUser {
1203
+ userId: string;
1204
+ name: string;
1205
+ role: string;
1206
+ firstJoinedAt: number;
1207
+ /** null = still in the room */
1208
+ lastLeftAt: number | null;
1209
+ /** Time present, overlapping connections (two tabs) counted once. */
1210
+ totalSeconds: number;
1211
+ sessions: number;
1212
+ present: boolean;
1213
+ }
1214
+ export interface AttendanceReport {
1215
+ roomId?: string;
1216
+ generatedAt: number;
1217
+ users: AttendanceUser[];
1218
+ sessions: AttendanceSession[];
1219
+ }
1220
+ /** Totals per user from raw sessions (open sessions count up to `now`). */
1221
+ export declare function summarizeAttendance(sessions: AttendanceSession[], now?: number): AttendanceUser[];
1222
+ /** CSV (one row per user) for spreadsheets. Times are ISO 8601 UTC. */
1223
+ export declare function attendanceToCsv(report: Pick<AttendanceReport, "users">): string;
1224
+ /** "tutor": one learner and an AI tutor. "class": an AI teacher and many learners. */
1225
+ export type LessonMode = "tutor" | "class";
1226
+ /**
1227
+ * Who the AI listens to in a class. "hands": it calls on raised hands one at a
1228
+ * time; "teacher": only a human teacher gives the floor; "off": lecture, typed
1229
+ * questions only. A tutor always listens to its learner.
1230
+ */
1231
+ export type LessonFloorPolicy = "hands" | "teacher" | "off";
1232
+ /**
1233
+ * How closely the AI keeps to the lesson's content. "strict": only what the
1234
+ * lesson provides (anything else is politely declined and steered back);
1235
+ * "guided" (default): the lesson's topics, with its own examples and
1236
+ * explanations within the subject; "open": anything within the subject.
1237
+ */
1238
+ export type LessonScope = "strict" | "guided" | "open";
1239
+ export interface LessonSlide {
1240
+ title: string;
1241
+ /** Bullet points. */
1242
+ bullets?: string[];
1243
+ /** An image to show (https URL). */
1244
+ imageUrl?: string;
1245
+ /** Not shown: what the AI should say about this slide. */
1246
+ notes?: string;
1247
+ }
1248
+ /** A multiple-choice question; `answer` is the index of the right option. */
1249
+ export interface LessonQuestion {
1250
+ id?: string;
1251
+ question: string;
1252
+ options: string[];
1253
+ answer: number;
1254
+ /** Said after the quiz closes. */
1255
+ explanation?: string;
1256
+ /** Written by the AI (not from your content): check the answer before approving. */
1257
+ aiSuggested?: boolean;
1258
+ /** Objective id this question checks. */
1259
+ objective?: string;
1260
+ }
1261
+ export interface LessonObjective {
1262
+ id: string;
1263
+ text: string;
1264
+ }
1265
+ export interface LessonSection {
1266
+ title: string;
1267
+ /** Written by the AI when it drafted the lesson (not from your content): check it before approving. */
1268
+ aiSuggested?: boolean;
1269
+ /** What to teach, in plain text or Markdown. */
1270
+ content?: string;
1271
+ slides?: LessonSlide[];
1272
+ questions?: LessonQuestion[];
1273
+ /** Rough minutes to spend. */
1274
+ minutes?: number;
1275
+ }
1276
+ /** What a developer gives a lesson: sections, or plain `text` the AI plans into sections. */
1277
+ export interface LessonPlan {
1278
+ title: string;
1279
+ /** e.g. "Mathematics". */
1280
+ subject?: string;
1281
+ /** Grade or level, e.g. "JSS1", "Year 7", "beginner". */
1282
+ level?: string;
1283
+ /** Curriculum or syllabus this lesson follows (its name, or the relevant part as text). */
1284
+ curriculum?: string;
1285
+ /** Who it's for, e.g. "Year 7 maths". */
1286
+ audience?: string;
1287
+ objectives?: LessonObjective[];
1288
+ sections?: LessonSection[];
1289
+ /** Instead of sections: the material as text or Markdown. */
1290
+ text?: string;
1291
+ }
1292
+ /**
1293
+ * Language the AI teaches in. "en" English (default), "pcm" Nigerian Pidgin,
1294
+ * "fr" French.
1295
+ */
1296
+ export type LessonLanguage = "en" | "pcm" | "fr";
1297
+ /** Exam boards for exam practice. */
1298
+ export type ExamBoard = "WAEC" | "NECO" | "JAMB" | "BECE" | "NABTEB";
1299
+ /** A lesson plan in the library: drafts are edited and approved; only approved versions are taught. */
1300
+ export interface LessonPlanRecord {
1301
+ id: string;
1302
+ status: "draft" | "approved" | "archived";
1303
+ title: string;
1304
+ /** The plan being edited (a draft), or the approved plan. */
1305
+ plan: LessonPlan;
1306
+ /** "practice": exam practice (many questions, timed, explained). */
1307
+ style?: "lesson" | "practice";
1308
+ exam?: {
1309
+ board: ExamBoard;
1310
+ subject: string;
1311
+ year?: string;
1312
+ };
1313
+ language?: LessonLanguage;
1314
+ /** Where the content came from. */
1315
+ source?: {
1316
+ kind: "file" | "text" | "topic" | "link" | "manual" | "api";
1317
+ name?: string;
1318
+ };
1319
+ /** Latest approved version number (0 = never approved). */
1320
+ version: number;
1321
+ /** True while the draft has changes since the last approval. */
1322
+ changed: boolean;
1323
+ /** Draft processing: "ready", or "processing" while the AI drafts it, or "failed" with `error`. */
1324
+ draftState: "ready" | "processing" | "failed";
1325
+ error?: string;
1326
+ createdAt: number;
1327
+ updatedAt: number;
1328
+ approvedAt?: number;
1329
+ approvedBy?: string;
1330
+ }
1331
+ /** An ordered set of lessons taught one after another (e.g. a term's scheme of work). */
1332
+ export interface Course {
1333
+ id: string;
1334
+ title: string;
1335
+ subject?: string;
1336
+ level?: string;
1337
+ /** Lesson plan ids in teaching order. */
1338
+ plans: string[];
1339
+ /** Index of the next plan a timetable starts. */
1340
+ next: number;
1341
+ createdAt: number;
1342
+ updatedAt: number;
1343
+ }
1344
+ /** Settings a timetable or course passes to each lesson it starts. */
1345
+ export interface LessonDefaults {
1346
+ mode?: LessonMode;
1347
+ scope?: LessonScope;
1348
+ floor?: LessonFloorPolicy;
1349
+ language?: LessonLanguage;
1350
+ /** Teachers who get every lesson report by email. */
1351
+ reportEmails?: string[];
1352
+ /** Parents or guardians by learner userId: each gets only their learner's part. */
1353
+ guardianEmails?: Record<string, string[]>;
1354
+ /** AI teacher's name and voice. */
1355
+ name?: string;
1356
+ voice?: string;
1357
+ llmModel?: string;
1358
+ }
1359
+ /** A weekly slot: on these days at `start` (local time), start a lesson in `roomId`. */
1360
+ export interface TimetableSlot {
1361
+ id: string;
1362
+ /** 0 = Sunday … 6 = Saturday. */
1363
+ days: number[];
1364
+ /** "HH:MM", 24-hour, in the timetable's time zone. */
1365
+ start: string;
1366
+ minutes: number;
1367
+ roomId: string;
1368
+ /** Teach this lesson plan every time, or the course's next one. */
1369
+ planId?: string;
1370
+ courseId?: string;
1371
+ label?: string;
1372
+ }
1373
+ /** A one-off session on a date. */
1374
+ export interface TimetableSession {
1375
+ id: string;
1376
+ /** "YYYY-MM-DD" in the timetable's time zone. */
1377
+ date: string;
1378
+ start: string;
1379
+ minutes: number;
1380
+ roomId: string;
1381
+ planId?: string;
1382
+ courseId?: string;
1383
+ label?: string;
1384
+ }
1385
+ export interface Timetable {
1386
+ id: string;
1387
+ name: string;
1388
+ /** IANA time zone, e.g. "Africa/Lagos". */
1389
+ timeZone: string;
1390
+ /** Weekly slots run only between these dates (inclusive, "YYYY-MM-DD"). */
1391
+ termStart?: string;
1392
+ termEnd?: string;
1393
+ /** Dates with no lessons. */
1394
+ holidays?: string[];
1395
+ slots: TimetableSlot[];
1396
+ sessions: TimetableSession[];
1397
+ defaults?: LessonDefaults;
1398
+ /** False pauses auto-start. */
1399
+ active: boolean;
1400
+ createdAt: number;
1401
+ updatedAt: number;
1402
+ }
1403
+ /** A scheduled lesson, past or upcoming. */
1404
+ export interface TimetableRun {
1405
+ key: string;
1406
+ timetableId: string;
1407
+ at: number;
1408
+ roomId: string;
1409
+ planId?: string;
1410
+ courseId?: string;
1411
+ label?: string;
1412
+ status: "upcoming" | "started" | "failed" | "skipped";
1413
+ /** The running lesson's id (agent id) once started. */
1414
+ liveLessonId?: string;
1415
+ error?: string;
1416
+ }
1417
+ /** Something on the AI's whiteboard. x, y, w, h are fractions (0–1) of a 16:10 board. */
1418
+ export type BoardItem = {
1419
+ id: string;
1420
+ kind: "text";
1421
+ text: string;
1422
+ x: number;
1423
+ y: number;
1424
+ size?: "s" | "m" | "l";
1425
+ color?: string;
1426
+ } | {
1427
+ id: string;
1428
+ kind: "math";
1429
+ tex: string;
1430
+ x: number;
1431
+ y: number;
1432
+ size?: "s" | "m" | "l";
1433
+ color?: string;
1434
+ } | {
1435
+ id: string;
1436
+ kind: "list";
1437
+ items: string[];
1438
+ ordered?: boolean;
1439
+ x: number;
1440
+ y: number;
1441
+ color?: string;
1442
+ } | {
1443
+ id: string;
1444
+ kind: "shape";
1445
+ shape: "line" | "arrow" | "rect" | "circle";
1446
+ x: number;
1447
+ y: number;
1448
+ w: number;
1449
+ h: number;
1450
+ color?: string;
1451
+ label?: string;
1452
+ } | {
1453
+ id: string;
1454
+ kind: "image";
1455
+ url: string;
1456
+ x: number;
1457
+ y: number;
1458
+ w: number;
1459
+ h: number;
1460
+ } | {
1461
+ id: string;
1462
+ kind: "highlight";
1463
+ target: string;
1464
+ color?: string;
1465
+ };
1466
+ export interface LessonQuiz {
1467
+ /** Poll id: learners answer with poll-vote. */
1468
+ pollId: string;
1469
+ question: string;
1470
+ options: string[];
1471
+ /** Set once the quiz has closed. */
1472
+ answer?: number;
1473
+ explanation?: string;
1474
+ closesAt?: number;
1475
+ closed: boolean;
1476
+ }
1477
+ export interface LessonState {
1478
+ lessonId: string;
1479
+ /** The agent participant who teaches. */
1480
+ agentId: string;
1481
+ mode: LessonMode;
1482
+ title: string;
1483
+ status: "starting" | "teaching" | "paused" | "teacher" | "ended";
1484
+ section: number;
1485
+ sections: {
1486
+ title: string;
1487
+ }[];
1488
+ /** Current slide (null = none shown). */
1489
+ slide: (LessonSlide & {
1490
+ section: number;
1491
+ index: number;
1492
+ }) | null;
1493
+ board: BoardItem[];
1494
+ /** userId the AI is listening to right now (class), or null. */
1495
+ floor: string | null;
1496
+ floorPolicy: LessonFloorPolicy;
1497
+ scope: LessonScope;
1498
+ quiz: LessonQuiz | null;
1499
+ /** A countdown for an exercise (ms since epoch), with what it's for. */
1500
+ timer: {
1501
+ endsAt: number;
1502
+ label: string;
1503
+ } | null;
1504
+ startedAt: number;
1505
+ }
1506
+ export type LessonControl = {
1507
+ action: "pause";
1508
+ } | {
1509
+ action: "resume";
1510
+ }
1511
+ /** A human teacher takes over: the AI stops talking and keeps notes. */
1512
+ | {
1513
+ action: "takeover";
1514
+ } | {
1515
+ action: "handback";
1516
+ }
1517
+ /** `section` is 0-based, like LessonState.section. */
1518
+ | {
1519
+ action: "goto";
1520
+ section: number;
1521
+ } | {
1522
+ action: "call-on";
1523
+ userId: string | null;
1524
+ } | {
1525
+ action: "floor-policy";
1526
+ policy: LessonFloorPolicy;
1527
+ }
1528
+ /** How closely the AI keeps to the lesson's content from now on. */
1529
+ | {
1530
+ action: "scope";
1531
+ scope: LessonScope;
1532
+ }
1533
+ /** A private instruction for the AI ("slow down", "explain it again"). */
1534
+ | {
1535
+ action: "note";
1536
+ text: string;
1537
+ } | {
1538
+ action: "end";
1539
+ };
1540
+ /** A safeguarding or help alert raised by the AI teacher. */
1541
+ export interface LessonAlert {
1542
+ /** The learner it is about, if any. */
1543
+ userId?: string;
1544
+ name?: string;
1545
+ /** "urgent": possible risk of harm; "concern": worrying behaviour; "help": the AI needs a human. */
1546
+ severity: "urgent" | "concern" | "help";
1547
+ reason: string;
1548
+ at: number;
1549
+ }
1550
+ /** Per-learner part of a lesson report. */
1551
+ export interface LearnerReport {
1552
+ userId: string;
1553
+ name: string;
1554
+ /** Seconds in the lesson. */
1555
+ attendedSeconds: number;
1556
+ quizzes: {
1557
+ question: string;
1558
+ chosen: number | null;
1559
+ correct: boolean;
1560
+ }[];
1561
+ /** Spoken or typed questions, and spoken answers. */
1562
+ contributions: number;
1563
+ /** Objective id → "met" | "weak" | "not-seen", from quizzes and the AI's notes. */
1564
+ objectives: Record<string, "met" | "weak" | "not-seen">;
1565
+ /** The AI's notes on this learner. */
1566
+ notes: string[];
1567
+ /** Short feedback written by the AI at the end (when an LLM is configured). */
1568
+ feedback?: string;
1569
+ }
1570
+ export interface LessonReport {
1571
+ lessonId: string;
1572
+ roomId: string;
1573
+ mode: LessonMode;
1574
+ title: string;
1575
+ startedAt: number;
1576
+ endedAt: number;
1577
+ sectionsCovered: number;
1578
+ summary?: string;
1579
+ learners: LearnerReport[];
1580
+ /** Safeguarding or help alerts the AI raised. */
1581
+ alerts: LessonAlert[];
1582
+ transcript: {
1583
+ at: number;
1584
+ speaker: string;
1585
+ role: "teacher" | "learner" | "human-teacher";
1586
+ text: string;
1587
+ }[];
1588
+ }