@ravenkash/rtc 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,622 @@
+import { EffectsPipeline } from '@ravenkash/effects';
+
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+interface Logger {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+
+interface RTCClientConfig {
+    /** The RTC token your backend minted through Raven's Control API. Never mint one in the browser. */
+    token: string;
+    /**
+     * RTC infrastructure URL to connect to. It's the `endpoint` field out of
+     * the same mint response as `token`. Forward both through untouched;
+     * don't build this by hand.
+     */
+    endpoint: string;
+    /**
+     * The `iceServers` array from the same mint response. Optional so tests
+     * and advanced setups can skip it, but ordinarily you just forward it.
+     * Don't go configuring STUN/TURN by hand.
+     */
+    iceServers?: RTCIceServer[];
+    logLevel?: LogLevel;
+    /** Defaults to true. Set false to disable automatic reconnect on network loss. */
+    autoReconnect?: boolean;
+    /**
+     * Base URL for best-effort connection telemetry. Comes from the
+     * `telemetryUrl` field of the same token-mint response as `token` and
+     * `endpoint`; never build it yourself. Leave it out, or set
+     * `telemetry: false`, to turn telemetry off completely. RTC never
+     * depends on it either way. See docs/telemetry.md.
+     */
+    telemetryUrl?: string;
+    /** Defaults to true. Set false to switch telemetry off; RTC never needs it (Phase 9 spec §31). */
+    telemetry?: boolean;
+}
+interface ResolvedRTCClientConfig {
+    token: string;
+    endpoint: string;
+    iceServers?: RTCIceServer[];
+    logLevel: LogLevel;
+    autoReconnect: boolean;
+    telemetryUrl?: string;
+    telemetry: boolean;
+}
+
+/**
+ * One flattened WebRTC stats sample.
+ *
+ * Duck-typed instead of bound to any particular source, which is how this
+ * file survived the move off LiveKit's stats objects to reading an
+ * `RTCStatsReport` directly (see `internal/telemetry/rtc-stats.ts`). Every
+ * field is a raw WebRTC stat in the units the spec uses, so seconds, not
+ * milliseconds. `normalizeTrackStats` below translates into Raven's own
+ * vocabulary.
+ */
+interface RawTrackStats {
+    type?: 'audio' | 'video';
+    /** Epoch ms: when this sample was taken. Bitrate is a delta against a previous one. */
+    timestamp: number;
+    /** Seconds, per the WebRTC spec. */
+    jitter?: number;
+    packetsLost?: number;
+    packetsSent?: number;
+    packetsReceived?: number;
+    /** Seconds. Only ever set on an outbound audio stream; WebRTC reports no RTT for video or for the receive direction. */
+    roundTripTime?: number;
+    bytesSent?: number;
+    bytesReceived?: number;
+    /** Receive-direction video only. WebRTC doesn't surface it for audio or for sending. */
+    mimeType?: string;
+    frameWidth?: number;
+    frameHeight?: number;
+    framesPerSecond?: number;
+}
+/**
+ * Raven's own normalized shape. A raw WebRTC stats object never appears on
+ * a public class.
+ *
+ * Every field is optional, and gets omitted, not set to `0` or
+ * `null` when the browser or SFU didn't report it. "0% packet loss" and
+ * "we don't know" are different facts, and this will not fabricate the
+ * first to cover for the second.
+ */
+interface TrackStats {
+    kind: TrackKind;
+    /** 'send' for a track we published, 'receive' for one we subscribed to. */
+    direction: 'send' | 'receive';
+    /** Bytes/sec, from two consecutive samples. Undefined on a track's first sample, since there's nothing to take a delta against yet. */
+    bitrateBps?: number;
+    packetsLost?: number;
+    /** 0-100. The module doc explains why it's an approximation and not a WebRTC-spec figure. */
+    packetLossPercent?: number;
+    jitterMs?: number;
+    roundTripTimeMs?: number;
+    /** Only set for a received video track. See `RawTrackStats.mimeType`. */
+    codec?: string;
+    frameWidth?: number;
+    frameHeight?: number;
+    framesPerSecond?: number;
+}
+
+type TrackKind = 'camera' | 'microphone' | 'screenShare' | 'unknown';
+/**
+ * A structural interface, not a concrete class, so a track can be backed by
+ * a raw `MediaStreamTrack` (what the native adapter does) or by a test
+ * double, with neither having to inherit anything.
+ */
+interface TrackDelegate {
+    readonly mediaStreamTrack: MediaStreamTrack;
+    readonly mediaStream?: MediaStream;
+    readonly isMuted: boolean;
+    attach(element?: HTMLMediaElement): HTMLMediaElement;
+    detach(element?: HTMLMediaElement): HTMLMediaElement | HTMLMediaElement[];
+}
+/** Base class for local and remote tracks alike. Never leaks RTCRtpSender/Receiver. */
+declare abstract class Track {
+    readonly kind: TrackKind;
+    protected readonly delegate: TrackDelegate;
+    constructor(delegate: TrackDelegate, kind: TrackKind);
+    /** The underlying native track, for the rare occasion you need to go deeper. */
+    get mediaStreamTrack(): MediaStreamTrack;
+    get mediaStream(): MediaStream | undefined;
+    get isMuted(): boolean;
+    /** Attaches this track to a `<video>`/`<audio>` element, creating one if omitted. */
+    attach(element?: HTMLMediaElement): HTMLMediaElement;
+    /** Detaches this track from one element, or from all elements if omitted. */
+    detach(element?: HTMLMediaElement): HTMLMediaElement[];
+}
+interface LocalTrackDelegate extends TrackDelegate {
+    mute(): Promise<unknown>;
+    unmute(): Promise<unknown>;
+    /**
+     * Optional, so a delegate that predates stats support (or a test double
+     * that doesn't care) still satisfies this interface untouched. Purely
+     * additive, never required. The array form covers video, where a
+     * simulcast sender reports one `outbound-rtp` entry per encoding layer
+     * instead of a single stream.
+     */
+    getSenderStats?(): Promise<RawTrackStats | RawTrackStats[] | undefined>;
+    /**
+     * Swaps the underlying MediaStreamTrack on an already-published sender.
+     * `RTCRtpSender.replaceTrack()` manages this without renegotiating, so
+     * nobody else in the room sees a thing. Optional for the same reason as
+     * getSenderStats: a delegate predating Raven Effects still satisfies
+     * this interface, and LocalTrack.attachEffects() checks for it rather
+     * than assuming every delegate has it.
+     */
+    replaceTrack?(track: MediaStreamTrack, userProvidedTrack?: boolean): Promise<unknown>;
+}
+interface RemoteTrackDelegate extends TrackDelegate {
+    /** Optional for the same reason as `LocalTrackDelegate.getSenderStats`. */
+    getReceiverStats?(): Promise<RawTrackStats | undefined>;
+}
+/** A locally captured track (camera, microphone or screen share), published or not. */
+declare class LocalTrack extends Track {
+    private readonly localDelegate;
+    private lastSample?;
+    private attachedEffectsPipeline?;
+    private preEffectsMediaStreamTrack?;
+    constructor(delegate: LocalTrackDelegate, kind: TrackKind);
+    mute(): Promise<void>;
+    unmute(): Promise<void>;
+    /** Stops the underlying device capture. Publish state belongs to Room.unpublish(). */
+    stop(): void;
+    /**
+     * Where Raven Effects (`@ravenkash/effects`) plugs in. The chain is
+     * Camera → Raven Video Track → Effects Pipeline → Processed Video Track →
+     * Raven RTC.
+     *
+     * Runs `pipeline` against this track's live camera feed and, if the track
+     * is already published, swaps the sender's `MediaStreamTrack` in place
+     * through the adapter's `replaceTrack()`. No renegotiation, no reconnect,
+     * audio and the rest of the room untouched. Camera only for now; screen
+     * share and microphone aren't supported.
+     *
+     * Can't run the pipeline on this device (no WebGL2, Canvas2D or
+     * captureStream)? It falls back to the original track on its own. The
+     * call keeps working either way.
+     */
+    attachEffects(pipeline: EffectsPipeline): Promise<void>;
+    /** Goes back to the unmodified camera track and frees the pipeline's engine resources. */
+    detachEffects(): Promise<void>;
+    /**
+     * Live send-side stats for this track: bitrate, packet loss, jitter, RTT
+     * (audio only), resolution and fps (video only).
+     *
+     * You get `undefined`, not a zeroed-out object, when the adapter can't
+     * supply them, either because the delegate has no `getSenderStats` or
+     * because the underlying call resolved to nothing. The module doc covers
+     * why that distinction matters.
+     *
+     * Call it periodically instead of once. `Room.getConnectionStats()` does,
+     * every few seconds. Bitrate needs two samples to compute, so the first
+     * call after a track starts always omits it.
+     */
+    getStats(): Promise<TrackStats | undefined>;
+}
+/** A track received from a remote participant, via the SFU. */
+declare class RemoteTrack extends Track {
+    private readonly remoteDelegate;
+    private lastSample?;
+    constructor(delegate: RemoteTrackDelegate, kind: TrackKind);
+    /** Live receive-side stats. `LocalTrack.getStats()` covers the shape and the caveats. */
+    getStats(): Promise<TrackStats | undefined>;
+}
+
+/** Fields the local user and remote participants have in common. */
+declare abstract class Participant {
+    private _identity;
+    /** Opaque application metadata set when the RTC token was minted. */
+    readonly metadata?: string;
+    constructor(identity: string, metadata?: string);
+    /** The RTC token's participant identity. Stable for the whole session. */
+    get identity(): string;
+    /**
+     * @internal Called once by the SFU adapter just after connect() resolves.
+     * The constructor runs before the server has confirmed identity, so this
+     * patches it in afterwards.
+     */
+    _setIdentity(identity: string): void;
+}
+declare class LocalParticipant extends Participant {
+    /** Tracks this participant has published, in publish order. Mutated by Room. */
+    readonly tracks: LocalTrack[];
+}
+declare class RemoteParticipant extends Participant {
+    /** Tracks subscribed from this participant, in subscribe order. Mutated by Room. */
+    readonly tracks: RemoteTrack[];
+}
+
+type SdkConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'failed';
+/**
+ * A coarse quality signal, reported by the SFU. The client doesn't derive
+ * it from raw stats; it's whatever the SFU itself computed. The SFU has by
+ * far the better view: it sees loss and jitter on every leg of the room,
+ * not just this one client's.
+ *
+ * `'unknown'` covers both "not connected yet" and "the SFU has nothing to
+ * say", which is the honest answer either way. It's also the usual answer
+ * right now, since Raven's SFU doesn't compute a quality verdict yet. See
+ * `RavenAdapter.getConnectionQuality`.
+ */
+type ConnectionQuality = 'excellent' | 'good' | 'poor' | 'lost' | 'unknown';
+type DeviceKind = 'videoinput' | 'audioinput' | 'audiooutput';
+interface DeviceInfo {
+    deviceId: string;
+    label: string;
+    kind: DeviceKind;
+}
+interface SFUAdapterEventMap {
+    connectionStateChanged: (state: SdkConnectionState) => void;
+    participantJoined: (participant: RemoteParticipant) => void;
+    participantLeft: (participant: RemoteParticipant) => void;
+    trackPublished: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackUnpublished: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackSubscribed: (track: RemoteTrack, participant: RemoteParticipant) => void;
+    trackUnsubscribed: (track: RemoteTrack, participant: RemoteParticipant) => void;
+    /** Phase 11 addition. Lets a UI show a muted indicator without polling `track.isMuted`. */
+    trackMuted: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackUnmuted: (kind: TrackKind, participant: RemoteParticipant) => void;
+    localTrackPublished: (track: LocalTrack) => void;
+    localTrackUnpublished: (track: LocalTrack) => void;
+    dataReceived: (payload: Uint8Array, participant?: RemoteParticipant) => void;
+    mediaError: (error: Error) => void;
+}
+/**
+ * The boundary between the public Room API and whatever actually
+ * implements the connection.
+ *
+ * This interface is the reason swapping LiveKit out for Raven's own SFU
+ * didn't touch the public API. `Room` and `RTCClient` are written against
+ * it, never against a particular implementation, so trading
+ * `internal/sfu/livekit-adapter.ts` for `internal/sfu/raven-adapter.ts`
+ * came down to one line in the default factory. It also lets tests drive
+ * Room/Client logic through a fake adapter instead of a real browser and
+ * WebRTC stack.
+ */
+interface SFUAdapter {
+    readonly connectionState: SdkConnectionState;
+    readonly localParticipant: LocalParticipant;
+    readonly remoteParticipants: Map<string, RemoteParticipant>;
+    /** The SFU's own read on this connection's health right now. */
+    getConnectionQuality(): ConnectionQuality;
+    /**
+     * Live ICE and signaling state, where the implementation can see it.
+     *
+     * Optional, because not every adapter owns an `RTCPeerConnection` to read
+     * it from. The LiveKit adapter didn't, which is why
+     * `Room.getDiagnostics()` reported these as `undefined` for so long. The
+     * native adapter does, so a bug report now carries the states that
+     * actually explain a failed connection.
+     */
+    getIceConnectionState?(): string | undefined;
+    getSignalingState?(): string | undefined;
+    /**
+     * The SFU's own view of the connection. It can disagree with the local
+     * one, and that disagreement is frequently the entire diagnosis.
+     */
+    getRemoteConnectionState?(): {
+        iceState?: string;
+        peerState?: string;
+    };
+    connect(endpoint: string, token: string, iceServers?: RTCIceServer[]): Promise<void>;
+    disconnect(): Promise<void>;
+    on<E extends keyof SFUAdapterEventMap>(event: E, handler: SFUAdapterEventMap[E]): void;
+    off<E extends keyof SFUAdapterEventMap>(event: E, handler: SFUAdapterEventMap[E]): void;
+    enableCamera(enabled: boolean): Promise<LocalTrack | undefined>;
+    enableMicrophone(enabled: boolean): Promise<LocalTrack | undefined>;
+    enableScreenShare(enabled: boolean): Promise<LocalTrack | undefined>;
+    publish(track: LocalTrack): Promise<void>;
+    unpublish(track: LocalTrack): Promise<void>;
+    sendData(payload: Uint8Array<ArrayBuffer>): Promise<void>;
+    getDevices(kind?: DeviceKind): Promise<DeviceInfo[]>;
+    /**
+     * Phase 11 widened this from `'videoinput' | 'audioinput'` to the full
+     * `DeviceKind`. Purely additive: every existing caller passing one of the
+     * original two values carries on unaffected. What it buys is
+     * `'audiooutput'`, i.e. speaker selection, on browsers that support
+     * `setSinkId`.
+     */
+    setDevice(kind: DeviceKind, deviceId: string): Promise<void>;
+}
+
+/** Stable typed error codes the SDK raises. Never a raw browser DOMException. */
+type RTCErrorCode = 'INVALID_TOKEN' | 'TOKEN_EXPIRED' | 'ROOM_NOT_FOUND' | 'CONNECTION_FAILED' | 'PERMISSION_DENIED' | 'CAMERA_PERMISSION_DENIED' | 'MICROPHONE_PERMISSION_DENIED' | 'DEVICE_NOT_FOUND' | 'NETWORK_ERROR' | 'SIGNALING_ERROR' | 'MEDIA_ERROR'
+/**
+ * The platform simply can't do this. Screen sharing on a mobile browser
+ * with no `getDisplayMedia`, say.
+ *
+ * Added in the native-RTC release, and kept separate from `MEDIA_ERROR`
+ * on purpose. "This device has no such capability" is a permanent fact a
+ * UI should act on by hiding the button; `MEDIA_ERROR` is a failure worth
+ * retrying. Spec §16 requires telling the two apart. Purely additive, so
+ * no existing code changed meaning.
+ */
+ | 'NOT_SUPPORTED' | 'TIMEOUT';
+/** The only error type this SDK throws, or emits on the `error` event. */
+declare class RTCError extends Error {
+    readonly code: RTCErrorCode;
+    readonly cause?: unknown;
+    constructor(code: RTCErrorCode, message: string, cause?: unknown);
+}
+declare function isRTCError(value: unknown): value is RTCError;
+
+/** Minimal typed pub/sub. No dependency, and it keeps the bundle small. */
+declare class TypedEventEmitter<EventMap extends {
+    [K in keyof EventMap]: (...args: never[]) => void;
+}> {
+    private listeners;
+    on<E extends keyof EventMap>(event: E, handler: EventMap[E]): this;
+    off<E extends keyof EventMap>(event: E, handler: EventMap[E]): this;
+    once<E extends keyof EventMap>(event: E, handler: EventMap[E]): this;
+    removeAllListeners(event?: keyof EventMap): this;
+    protected emit<E extends keyof EventMap>(event: E, ...args: Parameters<EventMap[E]>): void;
+}
+
+interface TelemetryClient {
+    readonly connectionId: string;
+    /**
+     * Fire and forget. Never hands back a promise anyone is meant to await,
+     * never throws. See docs/telemetry.md#reliability and Phase 9 spec §11:
+     * "RTC must continue working even if telemetry fails."
+     */
+    send(type: string, data?: Record<string, unknown>): void;
+}
+
+type ConnectionState = SdkConnectionState;
+/**
+ * A diagnostic snapshot that's safe to paste straight into a bug report.
+ * No tokens, no secrets, nothing sensitive.
+ *
+ * Anything we don't know comes back `undefined`; nothing here is guessed.
+ * `iceConnectionState` and `signalingState` were always `undefined` under
+ * the LiveKit adapter, which never exposed them. The native adapter does,
+ * so they now carry the states that actually explain a failed connection.
+ */
+interface ConnectionDiagnostics {
+    connectionState: ConnectionState;
+    iceConnectionState?: string;
+    signalingState?: string;
+    /**
+     * What the SFU makes of this connection. Worth sitting next to the local
+     * states, because the two can disagree, and "server says failed, browser
+     * says connected" is a diagnosis, not a contradiction.
+     */
+    remoteIceConnectionState?: string;
+    remotePeerConnectionState?: string;
+    reconnectCount: number;
+    sdkVersion: string;
+    platform: string;
+    browser: string;
+}
+/**
+ * Live media-quality stats. A separate `async` method rather than another
+ * field on `getDiagnostics()`, and that's on purpose. `getDiagnostics()`
+ * is synchronous and cheap so you can call it from anywhere at any time.
+ * Collecting real WebRTC stats is neither: it costs at least one round
+ * trip through the browser's stats API per track, and squashing per-track
+ * numbers into one flat object throws away the very thing that made them
+ * useful in a room full of people.
+ */
+interface ConnectionStats {
+    connectionState: ConnectionState;
+    /** The SFU's own read on connection health. See `ConnectionQuality`. */
+    connectionQuality: ConnectionQuality;
+    /** One entry per track this side has published. */
+    local: TrackStats[];
+    /** One entry per subscribed track, across all remote participants. */
+    remote: TrackStats[];
+}
+interface RoomEventMap {
+    connectionStateChanged: (state: ConnectionState) => void;
+    connected: () => void;
+    disconnected: () => void;
+    reconnecting: () => void;
+    reconnected: () => void;
+    participantJoined: (participant: RemoteParticipant) => void;
+    participantLeft: (participant: RemoteParticipant) => void;
+    trackPublished: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackUnpublished: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackSubscribed: (track: RemoteTrack, participant: RemoteParticipant) => void;
+    trackUnsubscribed: (track: RemoteTrack, participant: RemoteParticipant) => void;
+    /** Phase 11 addition. A remote participant muted or unmuted a track they'd already published. */
+    trackMuted: (kind: TrackKind, participant: RemoteParticipant) => void;
+    trackUnmuted: (kind: TrackKind, participant: RemoteParticipant) => void;
+    localTrackPublished: (track: LocalTrack) => void;
+    localTrackUnpublished: (track: LocalTrack) => void;
+    dataReceived: (payload: Uint8Array, participant?: RemoteParticipant) => void;
+    error: (error: RTCError) => void;
+}
+/**
+ * A joined room. You get one from `client.join(roomId)`; don't build it
+ * yourself. It owns participant and track state plus every room-scoped
+ * action. No SDP, ICE candidates or RTCPeerConnection leak out here.
+ */
+declare class Room extends TypedEventEmitter<RoomEventMap> {
+    readonly roomId: string;
+    /** Stable for the whole life of this connection. This is the id to quote in a bug report (Phase 9 spec §8). */
+    readonly connectionId: string;
+    readonly localParticipant: LocalParticipant;
+    private readonly adapter;
+    private readonly logger;
+    private readonly telemetry;
+    private reconnectCount;
+    private statsTimer?;
+    /**
+     * How often the stats monitor samples and reports. Often enough that a
+     * dashboard showing "now" isn't showing you five minutes ago, rarely
+     * enough that it doesn't hammer the telemetry endpoint on a call where
+     * dozens of participants are all doing exactly this.
+     */
+    private static readonly STATS_INTERVAL_MS;
+    /** @internal Use `client.join(roomId)`. The telemetry client defaults to a no-op, so tests and advanced setups can build a Room directly without wiring one up. */
+    constructor(adapter: SFUAdapter, roomId: string, logger: Logger, telemetry?: TelemetryClient);
+    get remoteParticipants(): RemoteParticipant[];
+    get connectionState(): ConnectionState;
+    private wireAdapterEvents;
+    /**
+     * A non-secret diagnostic snapshot for support and debugging.
+     *
+     * Synchronous and cheap by design, so you can call it from anywhere at
+     * any time, error handlers included. Live media stats are a separate
+     * `async` call; see `getConnectionStats()`.
+     */
+    getDiagnostics(): ConnectionDiagnostics;
+    /**
+     * Live media-quality stats for every published and subscribed track.
+     * RTT, jitter, packet loss, bitrate, codec, resolution/fps, and the
+     * SFU's own connection-quality read. `ConnectionStats` explains why this
+     * is kept apart from `getDiagnostics()`.
+     *
+     * Call it whenever you like, including before anything is published or
+     * subscribed. You just get empty `local`/`remote` arrays then, not an
+     * error.
+     */
+    getConnectionStats(): Promise<ConnectionStats>;
+    /**
+     * Polls `getConnectionStats()` on a timer and ships the result as
+     * telemetry, so the dashboard's RTC view (spec §23) has numbers to show
+     * without every developer wiring it up by hand. Best-effort, same as
+     * every other telemetry event here: failures get swallowed. A hiccup
+     * collecting stats is no reason to disturb the call it's describing.
+     */
+    private startStatsMonitor;
+    private stopStatsMonitor;
+    /** Captures and publishes the camera in one go. Resolves to the published track. */
+    enableCamera(): Promise<LocalTrack | undefined>;
+    /** Stops publishing and releases the camera. */
+    disableCamera(): Promise<void>;
+    /** Captures and publishes the microphone in one call. Resolves to the published track. */
+    enableMicrophone(): Promise<LocalTrack | undefined>;
+    /** Stops publishing and releases the microphone. */
+    disableMicrophone(): Promise<void>;
+    /** Captures and publishes a screen share in one call. */
+    enableScreenShare(): Promise<LocalTrack | undefined>;
+    disableScreenShare(): Promise<void>;
+    /** Publishes a track you made with `client.createCameraTrack()` and friends. */
+    publish(track: LocalTrack): Promise<void>;
+    unpublish(track: LocalTrack): Promise<void>;
+    /** Switches the active camera without republishing. */
+    setCameraDevice(deviceId: string): Promise<void>;
+    /** Switches the active microphone without republishing. */
+    setMicrophoneDevice(deviceId: string): Promise<void>;
+    /**
+     * Switches the audio output ("speaker") device for this room's remote
+     * audio elements. Phase 11 addition. Not supported everywhere: Safari
+     * has no `HTMLMediaElement.setSinkId`. Browsers that don't implement it
+     * get a `DEVICE_NOT_FOUND` throw instead of a silent no-op.
+     */
+    setSpeakerDevice(deviceId: string): Promise<void>;
+    /**
+     * Sends a small payload to everyone, or to specific people if the
+     * underlying SFU adapter supports targeting. Requires the token's
+     * `publishData` grant; throws PERMISSION_DENIED without it.
+     */
+    sendData(payload: string | Uint8Array): Promise<void>;
+    /**
+     * Resolves once the media connection is genuinely up.
+     *
+     * # Why this exists
+     *
+     * `client.join()` resolves when the **control plane** lets you in: room
+     * joined, you know who else is here, you can publish. The media
+     * connection finishes a moment later, once ICE and DTLS are done, which
+     * means `connectionState` sits at `'connecting'` for a short window
+     * after `join()` returns. That's the honest shape of an SFU connection,
+     * and it's why `'connected'` is an event, not something joining
+     * guarantees you.
+     *
+     * Most callers need none of this. `enableCamera()` and
+     * `enableMicrophone()` work fine inside that window, and the `connected`
+     * event is what you want driving a UI. This is for code that genuinely
+     * has to block: a test, or a flow that mustn't move on until media is
+     * live.
+     *
+     * Resolves straight away if already connected. Rejects on `'failed'` and
+     * on timeout, rather than handing back a connection that isn't there.
+     *
+     * Careful: a subscriber joining a room where nobody is publishing can
+     * quite legitimately stay `'connecting'`. With no tracks on either side
+     * there's nothing to negotiate, so waiting here times out on a
+     * connection that isn't broken at all. Where you can, drive the UI off
+     * the `connected` event instead of blocking on this.
+     */
+    waitUntilConnected(timeoutMs?: number): Promise<void>;
+    /** Leaves the room, stops local tracks and closes the underlying connection. */
+    leave(): Promise<void>;
+}
+
+type AdapterFactory = (logger: Logger, autoReconnect: boolean) => SFUAdapter;
+/**
+ * The SDK's entry point. Holds your RTC token and endpoint and gets you
+ * into a room. Everything per-room lives on the `Room` it hands back.
+ */
+declare class RTCClient {
+    private readonly config;
+    private readonly logger;
+    private readonly adapterFactory;
+    private currentRoom?;
+    /**
+     * @internal Use `createRTCClient(config)`. The second param exists purely
+     * so tests can inject a fake SFUAdapter without a real browser and WebRTC
+     * stack. Not part of the public config.
+     */
+    constructor(config: ResolvedRTCClientConfig, adapterFactory?: AdapterFactory);
+    /**
+     * Joins the room this client's token was minted for. `roomId` has to
+     * match that room; pass a different one and you get `ROOM_NOT_FOUND`
+     * straight away, before any connection is attempted.
+     */
+    join(roomId: string): Promise<Room>;
+    /** Leaves the most recently joined room, if there is one. Same as `.leave()` on that `Room`. */
+    leave(): Promise<void>;
+    /** Captures a camera track without joining or publishing. Pair it with `room.publish(track)`. */
+    createCameraTrack(deviceId?: string): Promise<LocalTrack>;
+    /** Captures a microphone track without joining or publishing. Pair it with `room.publish(track)`. */
+    createMicrophoneTrack(deviceId?: string): Promise<LocalTrack>;
+    /** Captures a screen-share track without joining or publishing. Pair it with `room.publish(track)`. */
+    createScreenShareTrack(): Promise<LocalTrack>;
+    /** Lists available devices. Labels only fill in once permission has been granted at least once. */
+    getDevices(kind?: DeviceKind): Promise<DeviceInfo[]>;
+    /**
+     * Subscribes to devices coming and going (Phase 11 addition), like a USB
+     * webcam being plugged in or yanked out. Returns an unsubscribe function.
+     *
+     * In an environment with no `navigator.mediaDevices` this is a no-op with
+     * an immediately-callable unsubscribe, rather than a throw. It's an
+     * optional convenience, not a capability anything depends on.
+     */
+    onDeviceChange(callback: () => void): () => void;
+    /** Switches the active camera on the currently joined room. */
+    setCamera(deviceId: string): Promise<void>;
+    /** Switches the active microphone on the currently joined room. */
+    setMicrophone(deviceId: string): Promise<void>;
+    /** Diagnostic snapshot of the currently joined room. See `Room.getDiagnostics()`. */
+    getDiagnostics(): ConnectionDiagnostics;
+}
+/**
+ * Creates an RTC client from a token your backend minted. `token` and
+ * `endpoint` come straight out of that same mint response. Don't build
+ * them by hand, and never mint a token in the browser.
+ */
+declare function createRTCClient(config: RTCClientConfig): RTCClient;
+
+/**
+ * Phase 11 addition. Feature-detects what the SDK actually needs, instead
+ * of keeping a user-agent allowlist that goes stale the moment you write
+ * it. See docs/sdk/web.md#browser-support for the documented matrix.
+ */
+interface BrowserSupportDetails {
+    supported: boolean;
+    missing: string[];
+}
+declare function getBrowserSupportDetails(): BrowserSupportDetails;
+/** A simple yes/no wrapper over `getBrowserSupportDetails()`. */
+declare function isBrowserSupported(): boolean;
+
+export { type BrowserSupportDetails, type ConnectionDiagnostics, type ConnectionQuality, type ConnectionState, type ConnectionStats, type DeviceInfo, type DeviceKind, LocalParticipant, LocalTrack, type LocalTrackDelegate, type LogLevel, Participant, RTCClient, type RTCClientConfig, RTCError, type RTCErrorCode, RemoteParticipant, RemoteTrack, type RemoteTrackDelegate, Room, type RoomEventMap, Track, type TrackDelegate, type TrackKind, type TrackStats, createRTCClient, getBrowserSupportDetails, isBrowserSupported, isRTCError };