@appsocom/client 0.0.0-stage → 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,632 @@
+import "webrtc-adapter";
+import { PartyTracks, getCamera, getMic, getScreenshare } from "partytracks/client";
+import { type AttendanceReport, type ChatMessage, type Device, type RoomState, type JoinClaims, type Participant, type ParticipantState, type Permissions, type RecordingStatus, type SharedFile, type Poll, type PollInput, type Question, type CaptionsState, type CaptionTranslation, type TranscriptLine, type CallSummary, type TrackKind, type TrackPermissions, type VideoQuality, type ConnectionQuality, type TranscriptSegment, type AgentState, type LessonAlert, type LessonControl, type LessonState, type AiControl, type AiFlag, type AiMinutes, type DataSaverInput, type DataSaverMode, type DataSaverSettings } from "@appsocom/protocol";
+import { Emitter } from "./emitter.js";
+export { SPEAKER, SpeakerTracker, VoiceActivity } from "./speaker.js";
+import { type DataUsage, type LinkSample } from "./adaptive.js";
+export { qualityForHeight, nextAdaptiveState, initialAdaptiveState, ADAPTIVE, connectionQualityFromSample, FALLBACK, nextFallbackState, initialFallbackState, cameraEncodings, videoAllowList, nextUsage, initialUsageMeter, bytesFromStats, } from "./adaptive.js";
+export type { LinkSample, AdaptiveState, FallbackState, DataUsage, UsageMeter, ByteTotals } from "./adaptive.js";
+export { DATA_SAVER_PRESETS, DATA_SAVER_MODES, resolveDataSaver, estimateDataUsage, pickLayer, TYPICAL_BITRATES } from "@appsocom/protocol";
+import { type E2EEKey, type E2EEOptions, type EncryptionErrorType } from "./e2ee.js";
+export { isE2EESupported, deriveE2EEKeys, createE2EEWorker, e2eeWorkerSource, type E2EEKey, type E2EEOptions, type EncryptionErrorType, } from "./e2ee.js";
+import { type BackgroundEffectOptions, type NoiseSuppressionOptions } from "./effects.js";
+export * from "./effects.js";
+export type * from "@appsocom/protocol";
+export { CloseCodes, attendanceToCsv } from "@appsocom/protocol";
+export { runPreflight, type PreflightOptions, type PreflightReport, type PreflightStep, type Verdict } from "./preflight.js";
+export declare const TOKEN_HEADER = "X-SfuKit-Token";
+/** Options for `room.send()`. */
+export interface SendOptions {
+    /** Only these userIds get it (up to 100). Default: everyone else in your group. */
+    to?: string[];
+    /** A label passed through to receivers, up to 64 characters (e.g. "whiteboard"). */
+    topic?: string;
+}
+/** What came with a received app message. */
+export interface MessageInfo {
+    topic: string | null;
+    /** Sent only to some people (with `to`), not the whole room. */
+    private: boolean;
+}
+export interface JoinOptions {
+    /**
+     * Where the kit's Worker routes live, e.g. "https://video.client.com"
+     * or "https://api.client.com/video" if mounted under a path.
+     */
+    url: string;
+    /** Join token from your backend (POST /tokens). */
+    token: string;
+    /** Start with the mic broadcasting. Default true. */
+    audio?: boolean;
+    /** Start with the camera broadcasting. Default true (false when mode is "audio"). */
+    video?: boolean;
+    /**
+     * "video" (default): normal video call.
+     * "audio": voice call. The camera is never opened (no camera permission prompt)
+     * and nobody's camera video is received; screen shares still work.
+     */
+    mode?: "video" | "audio";
+    /** Play remote audio automatically through hidden <audio> elements. Default true. */
+    autoPlayAudio?: boolean;
+    /** Reconnect after network drops (Wi-Fi ↔ mobile data, sleep, blips). Default true. */
+    reconnect?: boolean;
+    /** Give up reconnecting after this long without a connection, in ms. Default 120000. */
+    reconnectTimeoutMs?: number;
+    /** Override ICE servers. By default they come from the kit (TURN if configured). */
+    iceServers?: RTCIceServer[];
+    /** Give up joining after this many ms. Default 15000. Paused while you're in a waiting room. */
+    joinTimeoutMs?: number;
+    /**
+     * Send the camera in three sizes (720p / 360p / 180p) so each viewer gets the
+     * size it needs and the SFU can step down on weak links. Default true.
+     */
+    simulcast?: boolean;
+    /**
+     * Adapt to the connection: lower received video quality, then pause received
+     * video, and pause sending your own video when upload bandwidth collapses.
+     * Audio is never paused. Default true.
+     */
+    adaptive?: boolean;
+    /** How often to sample WebRTC stats, in ms. Default 2000. */
+    statsIntervalMs?: number;
+    /**
+     * Audio-first fallback: when the connection stays very bad even after the
+     * adaptive steps (heavy loss, very slow round trips, almost no upload), stop
+     * all camera video both ways and keep audio; video comes back by itself after
+     * a long good stretch. Fires "audio-fallback". Default true (false when
+     * `adaptive` is false). `{ keepScreenShare: true }` keeps receiving screen shares.
+     */
+    audioFallback?: boolean | {
+        keepScreenShare?: boolean;
+    };
+    /**
+     * Data saver for costly or weak mobile data: "low", "minimal", "audio", or
+     * custom settings (see DATA_SAVER_PRESETS). Default: the join token's
+     * `dataSaver`, else "off". Change it any time with room.setDataSaver().
+     */
+    dataSaver?: DataSaverInput;
+    /**
+     * Receive other people's tracks automatically. Default true. Set
+     * `{ video: false }` to pull no camera/screen video until you call
+     * room.setSubscribed() or room.observeVisibility() (large rooms, galleries).
+     */
+    autoSubscribe?: boolean | {
+        audio?: boolean;
+        video?: boolean;
+    };
+    /** Called when you're put in the room's waiting room; joinRoom() resolves once a teacher admits you. */
+    onWaiting?: () => void;
+    /**
+     * End-to-end encryption: a passphrase or random bytes every participant shares,
+     * handed out by your app (never through the kit's Worker or the join token).
+     * Media frames and room.send() messages are then unreadable to the Worker and the SFU.
+     */
+    e2ee?: E2EEOptions;
+    /**
+     * When a host turns captions on, transcribe your mic (only while it's on and
+     * you're speaking). Default true; false = others won't see captions of you.
+     */
+    sendCaptions?: boolean;
+    /** Start with background blur (true) or replacement ({ backgroundImage }). See room.setBackgroundEffect(). */
+    backgroundEffect?: boolean | BackgroundEffectOptions;
+    /** Start with RNNoise noise suppression on the mic. See room.setNoiseSuppression(). */
+    noiseSuppression?: boolean | NoiseSuppressionOptions;
+}
+export type ConnectionState = "connecting" | "connected" | "reconnecting" | "disconnected";
+export type RoomEvents = {
+    "participant-joined": (participant: Participant) => void;
+    "participant-updated": (participant: Participant) => void;
+    "participant-left": (participant: Participant) => void;
+    /** A remote track is ready (or was replaced). Attach it to a <video>/<audio>. */
+    track: (participant: Participant, kind: TrackKind, track: MediaStreamTrack) => void;
+    /** A remote track went away (e.g. screen share stopped, participant left). */
+    "track-removed": (participant: Participant, kind: TrackKind) => void;
+    /** Your own camera / screen preview track. */
+    "local-track": (kind: "video" | "screenVideo", track: MediaStreamTrack | null) => void;
+    /** Your mic/camera/screen state changed. */
+    "local-state": (state: ParticipantState) => void;
+    /**
+     * Your permissions changed during the call (a teacher allowed or stopped
+     * your mic/camera/screen). Devices you lost are already turned off.
+     */
+    permissions: (permissions: Permissions, previous: Permissions) => void;
+    /**
+     * Your own participant record changed on the server: metadata or display
+     * name set by your app's backend, role, permissions, hand…
+     */
+    self: (self: Participant) => void;
+    /** Your role changed during the call (e.g. your app's backend promoted you). */
+    role: (role: string, previous: string) => void;
+    /** A teacher/host (`by`, undefined = your app's backend) turned off these devices of yours. */
+    muted: (devices: Device[], by: Participant | undefined) => void;
+    /** A chat message arrived (or was part of the history sent when you joined). */
+    chat: (message: ChatMessage) => void;
+    /** A teacher/host deleted a chat message. */
+    "chat-deleted": (id: string) => void;
+    /** The raised-hand queue changed: everyone with a hand up (you included), first raised first. */
+    hands: (raised: Participant[]) => void;
+    /** You're in the waiting room (before joinRoom() resolves; also see JoinOptions.onWaiting). */
+    waiting: () => void;
+    /**
+     * You were moved to a breakout group (null = main room). `participants`
+     * already holds the people you see now; the usual join/leave events fired.
+     */
+    "group-changed": (group: string | null) => void;
+    /** Teachers/hosts: the waiting room changed. */
+    "waiting-list": (waiting: Participant[]) => void;
+    /** Room-wide settings changed (e.g. a teacher locked the room). */
+    "room-state": (state: RoomState) => void;
+    /**
+     * The room started (status) or stopped (null) recording. Show an indicator
+     * while it's set: participants should know they're being recorded.
+     */
+    recording: (recording: RecordingStatus | null) => void;
+    /** Someone reacted with an emoji. `from` is null for your own reactions. */
+    reaction: (emoji: string, from: Participant | null, at: number) => void;
+    /** A file was shared (also fired for each file already shared when you join). */
+    "file-shared": (file: SharedFile) => void;
+    "file-removed": (fileId: string) => void;
+    /** A poll started, got votes, closed (or you just joined and it exists). */
+    poll: (poll: Poll) => void;
+    "poll-removed": (pollId: string) => void;
+    /** A question was asked, upvoted or answered. */
+    question: (question: Question) => void;
+    "question-removed": (questionId: string) => void;
+    /** Captions turned on/off (or settings changed). */
+    captions: (state: CaptionsState) => void;
+    /** A new caption line from someone (you included), translated if you asked with setCaptionLanguage(). */
+    caption: (line: TranscriptLine, translation?: CaptionTranslation) => void;
+    /** A host or your backend summarized the call. */
+    summary: (summary: CallSummary) => void;
+    /** App-level message sent by another participant with room.send(). */
+    /** `info.topic` is the sender's topic (or null); `info.private` is true when it was sent only to some people. */
+    message: (data: unknown, from: Participant | undefined, info: MessageInfo) => void;
+    /**
+     * Overall call state. "reconnecting" covers both the room connection and the
+     * media connection dropping; it goes back to "connected" once both are back.
+     */
+    connection: (state: ConnectionState) => void;
+    /** Your join token expires in about a minute: get a new one and call room.updateToken(). */
+    "token-expiring": (expiresAt: number) => void;
+    /** Media (WebRTC) connection state. */
+    "media-connection": (state: RTCPeerConnectionState) => void;
+    /** Background effect / noise suppression switched on or off. */
+    effects: (effects: {
+        background: BackgroundEffectOptions | null;
+        noiseSuppression: boolean;
+    }) => void;
+    error: (error: Error) => void;
+    /**
+     * End-to-end encryption problem: a frame or message couldn't be decrypted
+     * (wrong or missing key, or a sender that doesn't encrypt). Throttled.
+     */
+    "encryption-error": (type: EncryptionErrorType, detail: string) => void;
+    /** You left, were removed, or the room closed. The Room can't be reused. */
+    left: (reason: string) => void;
+    /**
+     * Video was paused or resumed to save bandwidth. `participant` is whose video
+     * you stopped/started receiving, or null for your own outgoing camera.
+     */
+    "video-paused": (participant: Participant | null, paused: boolean) => void;
+    /**
+     * Someone's connection rating changed. `participantId` is `room.self.id` for
+     * your own. Ratings come from each participant's own WebRTC stats.
+     */
+    "connection-quality": (participantId: string, quality: ConnectionQuality) => void;
+    /** Who is talking right now, loudest first (participant ids; includes room.self.id). */
+    "active-speakers": (participantIds: string[]) => void;
+    /** The quality of video you receive from a participant changed (high/medium/low/off). */
+    "video-quality": (participant: Participant, quality: VideoQuality) => void;
+    /**
+     * Your connection fell back to audio only (true) or recovered (false). While
+     * it's on, no camera video is sent or received; tell the user why.
+     */
+    "audio-fallback": (active: boolean) => void;
+    /** The data-saver mode changed (room.setDataSaver()). */
+    "data-saver": (mode: DataSaverMode | "custom", settings: DataSaverSettings) => void;
+    /** Media data used so far in this call; fires every statsIntervalMs. */
+    "data-usage": (usage: DataUsage) => void;
+    /** An AI agent changed state: initializing, listening, thinking or speaking. */
+    "agent-state": (agent: Participant, state: AgentState) => void;
+    /**
+     * Live transcript of a conversation with an AI agent. Partial segments are
+     * re-sent with the same segment.id as words arrive; replace, don't append.
+     */
+    transcript: (segment: TranscriptSegment) => void;
+    /** An AI lesson started or changed: slide, whiteboard, who has the floor, quiz, timer, status. */
+    lesson: (lesson: LessonState) => void;
+    /** An AI lesson ended. */
+    "lesson-ended": (lessonId: string) => void;
+    /** Moderators only: the AI teacher raised a safeguarding or help alert. */
+    "lesson-alert": (lessonId: string, alert: LessonAlert) => void;
+    /** An AI participant flagged a point (hosts; everyone when its flags go to the room). */
+    "ai-flag": (agentId: string, flag: AiFlag) => void;
+    /** Hosts: an AI participant's minutes so far (after a "minutes" control, and when it leaves). */
+    "ai-minutes": (agentId: string, minutes: AiMinutes) => void;
+};
+/** Join a room. Resolves once you're in, rejects if the token is bad, the room is full, etc. */
+export declare function joinRoom(options: JoinOptions): Promise<Room>;
+export declare class Room extends Emitter<RoomEvents> {
+    #private;
+    readonly roomId: string;
+    readonly userId: string;
+    /** Your role: "teacher", "student", "observer", or your app's own label. */
+    /** Updated when your app's backend changes it during the call. */
+    role: string;
+    /** What you may do right now. Updated when a teacher/host changes it. */
+    permissions: Permissions;
+    /** Room-wide settings (locked, …). */
+    roomState: RoomState;
+    /** Teachers/hosts: who is in the waiting room now, first come first. */
+    waiting: Participant[];
+    /** Room metadata set by your app's backend (same as roomState.metadata). */
+    get metadata(): Record<string, unknown> | undefined;
+    /** Chat messages you've seen (public history + live, private ones to/from you), oldest first. Last 200. */
+    chat: ChatMessage[];
+    /** True if you may publish anything at all right now. */
+    get canPublish(): boolean;
+    /** Your own participant record (id changes after a reconnect). */
+    self: Participant | null;
+    /** The recording in progress, or null. See the "recording" event. */
+    recording: RecordingStatus | null;
+    connectionState: ConnectionState;
+    /** Raw partytracks objects for advanced use (device lists, transforms…). */
+    readonly media: {
+        partyTracks: PartyTracks;
+        mic: ReturnType<typeof getMic> | null;
+        camera: ReturnType<typeof getCamera> | null;
+        screen: ReturnType<typeof getScreenshare> | null;
+    };
+    /** @internal use joinRoom() */
+    constructor(options: JoinOptions);
+    /** All other participants currently in the room. */
+    get participants(): Participant[];
+    /** Current remote track for a participant, if any. */
+    getTrack(participantId: string, kind: TrackKind): MediaStreamTrack | undefined;
+    get localState(): ParticipantState;
+    toggleMic(): void;
+    setMic(on: boolean): void;
+    toggleCamera(): void;
+    setCamera(on: boolean): void;
+    /** Must be called from a click/tap handler (browser rule for screen capture). */
+    toggleScreenShare(): void;
+    /** Pick a specific mic/camera, e.g. from navigator.mediaDevices.enumerateDevices(). */
+    setMicDevice(device: MediaDeviceInfo): void;
+    setCameraDevice(device: MediaDeviceInfo): void;
+    /**
+     * Start the camera or mic again from scratch and turn it on. Use it for a
+     * "Try again" button after an "error" saying the device could not start
+     * (blocked, busy in another app, or stuck). Call it from a click/tap so the
+     * browser can ask for permission again.
+     */
+    restartDevice(kind: "mic" | "camera"): void;
+    /** Your own camera / screen preview track right now (also sent as "local-track" events). */
+    getLocalTrack(kind: "video" | "screenVideo"): MediaStreamTrack | null;
+    /** Play remote audio through this output device (speakers/headset). Not supported in every browser. */
+    setAudioOutputDevice(deviceId: string): void;
+    get audioOutputDevice(): string | null;
+    /** Current background effect (null = off). */
+    get backgroundEffect(): BackgroundEffectOptions | null;
+    /** True while RNNoise noise suppression is on. */
+    get noiseSuppression(): boolean;
+    /**
+     * Blur your background (true / { blurRadius }), replace it
+     * ({ backgroundImage: url }), or switch the effect off (false).
+     * Runs on-device with MediaPipe; loaded on first use.
+     */
+    setBackgroundEffect(effect: boolean | BackgroundEffectOptions): void;
+    /** Shorthand: setBackgroundEffect(on ? { blurRadius } : false). */
+    setBackgroundBlur(on: boolean, blurRadius?: number): void;
+    /** Switch RNNoise noise suppression on the mic on or off. */
+    setNoiseSuppression(on: boolean | NoiseSuppressionOptions): void;
+    /** Small app-defined state shared with everyone (hand raised, etc.). Max ~4KB. */
+    setCustomState(custom: Record<string, unknown>): void;
+    /**
+     * Teachers/hosts (permissions.moderate): allow or stop a user's mic, camera
+     * or screen share, e.g. { screen: true } to let a student present.
+     * Applies to all their connections and lasts until the room empties.
+     */
+    setPermissions(userId: string, permissions: Partial<Omit<Permissions, "moderate">>): void;
+    /**
+     * Teachers/hosts: turn off a user's devices (default: mic). They can turn
+     * them back on, unless `lock` is true (that also takes the permission away;
+     * give it back with setPermissions).
+     */
+    mute(userId: string, devices?: Device[], options?: {
+        lock?: boolean;
+    }): void;
+    /** Teachers/hosts: mute everyone who isn't a teacher/host (default: mics). */
+    muteAll(devices?: Device[], options?: {
+        lock?: boolean;
+    }): void;
+    /** Teachers/hosts: stop someone's screen share. */
+    stopScreenShare(userId: string): void;
+    /** Teachers/hosts: remove a user. `ban` keeps them out until the room empties. */
+    remove(userId: string, options?: {
+        ban?: boolean;
+    }): void;
+    /** Raise your hand. Raising it again keeps your place in the queue. */
+    raiseHand(): void;
+    /** Lower your own hand, or (teachers/hosts) someone else's. */
+    lowerHand(userId?: string): void;
+    /** Teachers/hosts: lower every raised hand. */
+    lowerAllHands(): void;
+    /** Everyone with a hand up (you included), first raised first. */
+    get raisedHands(): Participant[];
+    /**
+     * Send a chat message to everyone, or privately with { to: userId }.
+     * Students can only message teachers/hosts privately, and can't chat while a
+     * teacher has turned chat off (you get an `error` event).
+     */
+    sendChat(text: string, options?: {
+        to?: string;
+        everywhere?: boolean;
+    }): void;
+    /** Teachers/hosts: delete a chat message for everyone. */
+    deleteChat(id: string): void;
+    /** Teachers/hosts: turn chat on/off for everyone who isn't a teacher/host. */
+    setChatEnabled(enabled: boolean): void;
+    /**
+     * Teachers/hosts: put users in the spotlight for everyone (up to 6, in
+     * order; [] clears). Read it from room.roomState.spotlight / "room-state".
+     */
+    setSpotlight(userIds: string[]): void;
+    /**
+     * Teachers/hosts: start breakout rooms. Each group lists userIds; anyone not
+     * listed stays in the main room. Groups get ids "g1", "g2", … (room.roomState.breakouts).
+     */
+    startBreakouts(groups: {
+        name: string;
+        userIds: string[];
+    }[]): void;
+    /** Teachers/hosts: move someone to a group id (null = main room). */
+    moveToGroup(userId: string, group: string | null): void;
+    /** Teachers/hosts: join a breakout group yourself (null = back to the main room). */
+    visitGroup(group: string | null): void;
+    /** Teachers/hosts: end breakouts; everyone returns to the main room. */
+    endBreakouts(): void;
+    /** Your breakout group id, or null in the main room. */
+    get group(): string | null;
+    /** Teachers/hosts: turn the waiting room on/off (off admits everyone waiting). */
+    setWaitingRoom(on: boolean): void;
+    /** Teachers/hosts: let someone in from the waiting room ("*" = everyone). */
+    admit(userId: string): void;
+    /** Teachers/hosts: turn someone in the waiting room away. */
+    deny(userId: string): void;
+    /**
+     * Teachers/hosts: who attended and for how long (this room, last 30 days).
+     * Turn it into a spreadsheet with attendanceToCsv(report).
+     */
+    fetchAttendance(timeoutMs?: number): Promise<AttendanceReport>;
+    /** Teachers/hosts: while locked, only teachers/hosts can join. */
+    lockRoom(locked?: boolean): void;
+    /**
+     * Teachers/hosts (permissions.moderate): start recording the room to R2.
+     * Audio only by default; { video: true } records everything with the
+     * recorder bot (the kit must be deployed with it).
+     */
+    startRecording(options?: {
+        video?: boolean;
+    }): void;
+    /** Teachers/hosts (permissions.moderate): stop the recording. */
+    stopRecording(): void;
+    /**
+     * Start or stop receiving some of a participant's tracks, e.g. stop their
+     * video while their tile is off screen. Stopping really stops the media
+     * (no bandwidth used); starting again pulls it fresh.
+     */
+    setSubscribed(participantId: string, kinds: TrackKind | TrackKind[], on: boolean): void;
+    /** Whether you're set to receive this participant's track kind (if they publish it and you're allowed). */
+    isSubscribed(participantId: string, kind: TrackKind): boolean;
+    /**
+     * Receive a participant's video only while `el` (their tile) is on screen
+     * and the tab is visible. Video stops 1s after the tile leaves the screen
+     * (`hideDelayMs`) and comes back when it returns. Returns a function that
+     * stops watching (and leaves video on).
+     */
+    observeVisibility(el: Element, participantId: string, options?: {
+        kinds?: TrackKind[];
+        hideDelayMs?: number;
+    }): () => void;
+    /**
+     * Choose who may receive YOUR tracks. Enforced by the server: others only
+     * see (and can only pull) what you allow; anyone who loses access stops
+     * receiving within seconds. Kept until the room empties.
+     *
+     *   room.setTrackPermissions({ allowAll: true });                          // default
+     *   room.setTrackPermissions({ allowAll: false, allow: [{ userId: "t1" }] });
+     *   room.setTrackPermissions({ allowAll: false, allow: [{ userId: "t1", kinds: ["screenVideo"] }] });
+     */
+    setTrackPermissions(permissions: TrackPermissions): void;
+    /** AI agents currently in the room. */
+    get agents(): Participant[];
+    /** Type to an AI agent instead of speaking; it answers out loud. */
+    sendToAgent(agentId: string, text: string): void;
+    /** AI lessons running in this room (usually one). */
+    get lessons(): LessonState[];
+    /** The AI lesson running in this room, if any. */
+    get lesson(): LessonState | null;
+    /** AI participants in the room (agents with a role: contributor, scribe, co-teacher…). */
+    get aiParticipants(): Participant[];
+    /**
+     * "Ask AI": type a question to an AI participant (the alternative to asking
+     * the host or teacher). It answers in the chat, or out loud when its voice is
+     * on. `private`: only you see the answer, in chat. Needs the AI's
+     * directQuestions on unless you're a host. Saying its name in the call works too.
+     */
+    askAI(text: string, options?: {
+        agentId?: string;
+        private?: boolean;
+    }): void;
+    /**
+     * Hosts: steer an AI participant: { action: "pause" | "resume" | "recap" | "minutes" },
+     * { action: "settings", voice, directQuestions, flags, watchPolicy, knowledge },
+     * co-teachers { action: "teach", topic | planId } and { action: "stop-teaching" }.
+     */
+    controlAI(control: AiControl, agentId?: string | undefined): void;
+    /**
+     * Keep yourself out of what AI participants hear (true) or let them hear you
+     * again (false). Your speech and chat are then never handed to the AI.
+     * Shown to everyone as `participant.aiOptOut`.
+     */
+    setAiOptOut(optOut: boolean): void;
+    /** Type a question to the AI teacher. Raise your hand (raiseHand) to ask out loud instead. */
+    askLesson(text: string, lessonId?: string | undefined): void;
+    /**
+     * Moderators: steer the AI lesson, e.g. { action: "pause" }, { action: "takeover" }
+     * (you speak, the AI listens and keeps notes), { action: "handback" },
+     * { action: "call-on", userId }, { action: "goto", section: 2 },
+     * { action: "scope", scope: "strict" }, { action: "note", text: "slow down" }.
+     */
+    controlLesson(control: LessonControl, lessonId?: string | undefined): void;
+    /**
+     * Send an app-level message to everyone else in the room (chat, reactions…),
+     * or with `to` only to those userIds. `topic` travels with it so you can route
+     * messages (e.g. "whiteboard").
+     * With end-to-end encryption on, it's encrypted first (other participants
+     * receive the original `data`; the server sees ciphertext).
+     */
+    send(data: unknown, options?: SendOptions): void;
+    /** End-to-end encryption status. `keyIndex` is the key you send with (-1 = off). */
+    get encryption(): {
+        enabled: boolean;
+        keyIndex: number;
+    };
+    /**
+     * Add or rotate the end-to-end encryption key. Give every participant the new
+     * key with a new index (0-255). With `use: false` it's only added for
+     * receiving, so you can hand it out first and switch everyone over after.
+     * The last 16 keys are kept for decrypting.
+     */
+    setEncryptionKey(key: E2EEKey, index: number, options?: {
+        use?: boolean;
+    }): Promise<void>;
+    /** Send an emoji reaction to everyone (e.g. "👍"). Max ~10 per 5 seconds. */
+    react(emoji: string): void;
+    /** Files shared in this room, oldest first. They're deleted when the room empties. */
+    get files(): SharedFile[];
+    /**
+     * Share a file with everyone in the room (needs the Worker's STORAGE bucket).
+     * Observers can't share. Max size is the Worker's MAX_FILE_MB (default 25).
+     */
+    shareFile(file: Blob, name?: string): Promise<SharedFile>;
+    /** Download a shared file's bytes. */
+    downloadFile(fileId: string): Promise<Blob>;
+    /**
+     * A link that downloads the file (carries your join token, so don't share it
+     * outside the room). `inline` shows PNG/JPEG/GIF/WebP images instead.
+     */
+    fileUrl(fileId: string, inline?: boolean): string;
+    /** Remove a file you shared (moderators can remove anyone's). */
+    deleteFile(fileId: string): Promise<void>;
+    /** True if you may run polls and moderate Q&A (moderators, or everyone in rooms without roles). */
+    get isHost(): boolean;
+    /** Polls in this room, oldest first. `counts` is empty while results are hidden from you. */
+    get polls(): Poll[];
+    /** Your vote in a poll (option indexes), if you voted. */
+    myVote(pollId: string): number[] | undefined;
+    /** Hosts: start a poll. */
+    createPoll(poll: PollInput): void;
+    /** Vote, or change your vote. One option index unless the poll allows multiple. */
+    vote(pollId: string, choices: number | number[]): void;
+    closePoll(pollId: string): void;
+    deletePoll(pollId: string): void;
+    /** Q&A questions, oldest first. Sort by `upvotes` for a "top questions" view. */
+    get questions(): Question[];
+    /** Did you upvote this question? */
+    hasUpvoted(questionId: string): boolean;
+    /** `anonymous` hides your name from everyone except hosts. Max 500 characters, 5 a minute. */
+    askQuestion(text: string, anonymous?: boolean): void;
+    upvoteQuestion(questionId: string, up?: boolean): void;
+    /** Hosts. */
+    markAnswered(questionId: string, answered?: boolean): void;
+    /** Hosts, or your own question. */
+    deleteQuestion(questionId: string): void;
+    /** Are captions on in this room, and with what settings. */
+    get captions(): CaptionsState;
+    /** Recent caption lines (the last 200 you've seen). Hosts can fetch the full transcript. */
+    get recentCaptions(): TranscriptLine[];
+    /** The latest AI summary of this call, if a host made one. */
+    get summary(): CallSummary | undefined;
+    /**
+     * Hosts: turn live captions on/off (needs Workers AI on the Worker).
+     * `language` ("en", "fr", …) improves accuracy; `translate` gives English captions for any language.
+     * `server`: transcribe every mic on the server (participants on any SDK get captioned, nobody uploads clips).
+     */
+    setCaptions(on: boolean, options?: {
+        language?: string;
+        translate?: boolean;
+        server?: boolean;
+    }): void;
+    /** The language you read captions in ("fr", "ha", …): lines arrive with a translation. null = as spoken. */
+    setCaptionLanguage(language: string | null): void;
+    /** The language you asked to read captions in (null = as spoken). */
+    get captionLanguage(): string | null;
+    /** Hosts: the whole transcript so far, as JSON lines, plain text or WebVTT. */
+    getTranscript(format?: "json" | "txt" | "vtt"): Promise<TranscriptLine[] | string>;
+    /** Hosts: summarize the transcript so far with AI. Everyone gets the `summary` event. */
+    summarize(style?: "meeting" | "lesson"): Promise<CallSummary>;
+    /** Swap in a fresh token before the current one expires. */
+    updateToken(token: string): void;
+    /**
+     * Choose how much video you want from one participant: "high" | "medium" |
+     * "low" | "off" (audio only for them). Adaptive limits can still lower it.
+     */
+    setVideoQuality(participantId: string, quality: VideoQuality): void;
+    /**
+     * Keep a participant's received video matched to the size of the element
+     * showing it (ResizeObserver). Returns a function that stops watching.
+     */
+    fitVideoQuality(participantId: string, el: HTMLElement): () => void;
+    /**
+     * Audio-only mode: stop receiving everyone's camera video and turn your own
+     * camera off. Screen shares still come through. Turning it off restores both.
+     */
+    setAudioOnly(on: boolean): void;
+    /** Audio only by choice: setAudioOnly(true), mode "audio" or the "audio" data saver. See also audioFallback. */
+    get audioOnly(): boolean;
+    /**
+     * Data saver for costly or weak mobile data. A preset ("off", "low",
+     * "minimal", "audio") or custom settings, e.g.
+     * `{ base: "low", activeSpeakerVideo: 2 }`. Applies straight away, both to
+     * what you send and what you receive. Your choice is shown to others as
+     * participant.state.dataSaver.
+     */
+    setDataSaver(input: DataSaverInput): void;
+    /** The current data-saver mode and what it does. */
+    get dataSaver(): {
+        mode: DataSaverMode | "custom";
+        settings: DataSaverSettings;
+    };
+    /** True while your connection has fallen back to audio only (see "audio-fallback"). */
+    get audioFallback(): boolean;
+    /**
+     * Turn the audio-first fallback on or off during the call. Turning it off
+     * while it's active brings video back now.
+     */
+    setAudioFallback(enabled: boolean): void;
+    /**
+     * Media data used in this call so far (uploaded + downloaded, as measured by
+     * WebRTC), the current rates and a per-hour projection. Updated every
+     * statsIntervalMs; also see the "data-usage" event and estimateDataUsage().
+     */
+    get dataUsage(): DataUsage;
+    /** Highest video quality the adaptive logic currently allows you to receive. */
+    get receiveCap(): VideoQuality;
+    /** Participant ids currently speaking, loudest first (includes room.self.id). */
+    get activeSpeakers(): string[];
+    /** Connection rating for a participant (use room.self.id for yourself). */
+    getConnectionQuality(participantId: string): ConnectionQuality | undefined;
+    /** Latest connection measurement (updated every statsIntervalMs). */
+    get linkStats(): LinkSample | null;
+    /** Leave the room, stop camera/mic and clean everything up. */
+    leave(reason?: string): void;
+    /** @internal */
+    _start(): Promise<void>;
+    /** Retry playing remote audio after a user gesture (if autoplay was blocked). */
+    resumeAudio(): void;
+}
+/** Attach a track to a <video> or <audio> element. */
+export declare function attachTrack(el: HTMLMediaElement, track: MediaStreamTrack | null): void;
+/** Read (not verify) the claims in a join token. */
+export declare function decodeClaims(token: string): JoinClaims;