@xloon/xms-client 0.1.0

package/dist/room.d.ts

@@ -0,0 +1,201 @@
+import type { WebSocketFactory } from './signaling.js';
+import type { ParticipantInfo, ProtocolError, TrackInfo } from './protocol.js';
+export interface JoinOptions {
+    /** Signaling WebSocket URL, e.g. wss://media.example.com/ws/signaling */
+    url: string;
+    roomId: string;
+    /** Join token minted by the app backend (POST /api/v1/rooms/{roomId}/tokens). */
+    token: string;
+    /** Used only when the token carries no name. */
+    displayName?: string;
+    /** Subscribe to every publisher (all tracks) automatically and keep those subscriptions in step
+     *  with publisher changes. Default true. Turn off to choose publishers/tracks yourself. */
+    autoSubscribe?: boolean;
+    /** Returns a fresh join token from your backend. Used only when rejoining after a dropped
+     *  connection and the server rejects the current token (e.g. it expired); without it, an expired
+     *  token ends reconnection with `disconnected`. */
+    getToken?: () => Promise<string>;
+    /** For tests: delay before the first reconnect attempt (default 1000; doubles each attempt). */
+    reconnectDelayMs?: number;
+    /** For tests. */
+    webSocketFactory?: WebSocketFactory;
+    /** For tests. */
+    createPeerConnection?: (config: RTCConfiguration) => RTCPeerConnection;
+}
+export interface PublishOptions {
+    /** Send video as 3 simulcast layers (rids "l", "m", "h", lowest first) so each subscriber can be
+     *  given the quality it needs. Default true. */
+    simulcast?: boolean;
+}
+export interface SubscribeOptions {
+    /** Which of the publisher's tracks to receive (TrackInfo.trackId); all when omitted. */
+    trackIds?: string[];
+    /** trackId -> simulcast rid to start on; the server defaults to the highest layer. */
+    layers?: Record<string, string>;
+}
+export interface RemoteParticipant extends ParticipantInfo {
+    /** Tracks this participant currently publishes (empty when not publishing). */
+    tracks: TrackInfo[];
+}
+export interface RemoteTrack {
+    participantId: string;
+    trackId: string;
+    kind: 'audio' | 'video';
+    track: MediaStreamTrack;
+}
+export interface RoomEvents {
+    participantJoined: RemoteParticipant;
+    participantLeft: {
+        participantId: string;
+        reason: string;
+    };
+    publisherAdded: RemoteParticipant;
+    publisherUpdated: RemoteParticipant;
+    publisherRemoved: {
+        participantId: string;
+    };
+    trackMuted: {
+        participantId: string;
+        trackId: string;
+        muted: boolean;
+    };
+    /** Media for a subscribed track started arriving. */
+    track: RemoteTrack;
+    /** A subscribed track stopped (unsubscribed, unpublished, or the participant left). */
+    trackEnded: {
+        participantId: string;
+        trackId: string;
+    };
+    chat: {
+        participantId: string;
+        text: string;
+        timestampMillis: number;
+    };
+    /** App data another participant sent with {@link XmsRoom.sendData}. */
+    data: {
+        participantId: string;
+        type: string;
+        payload: unknown;
+        timestampMillis: number;
+    };
+    recordingStarted: {
+        recordingId: string;
+    };
+    recordingStopped: {
+        recordingId: string;
+    };
+    error: ProtocolError & {
+        transportId?: string | null;
+    };
+    /** The connection dropped (or a media connection failed) and the room is being rejoined; emitted
+     *  per attempt. Remote tracks have ended (trackEnded); they come back as new `track` events. */
+    reconnecting: {
+        attempt: number;
+    };
+    /** Rejoined under a new localParticipantId: your tracks are published again (mute kept) and
+     *  subscriptions are being restored. */
+    reconnected: {
+        participantId: string;
+    };
+    /** Final: after {@link XmsRoom.leave}, or when rejoining gave up. */
+    disconnected: {
+        code: number;
+        reason: string;
+    };
+}
+type Handler<E extends keyof RoomEvents> = (data: RoomEvents[E]) => void;
+export declare class XmsRoom {
+    readonly roomId: string;
+    private readonly options;
+    private signaling;
+    private participantId;
+    private token;
+    private iceServers;
+    private readonly autoSubscribe;
+    private readonly newPeerConnection;
+    private readonly remote;
+    private readonly subscriptions;
+    /** What each subscription asked for, so it can be restored after a rejoin. */
+    private readonly subscribeOptions;
+    private readonly published;
+    /** Our participantIds from before rejoins: the server may list them until it notices they're gone. */
+    private readonly previousIds;
+    /** PeerConnections that have connected at least once. */
+    private readonly connectedPcs;
+    private readonly listeners;
+    /** Serializes negotiations per transport: key "pub" or a publisherId. */
+    private readonly queues;
+    private publisherPc;
+    private left;
+    private reconnecting;
+    /** Connects, authenticates and joins. Existing publishers are subscribed to automatically unless
+     *  {@link JoinOptions.autoSubscribe} is false. If the connection later drops, the room is rejoined
+     *  automatically (see the reconnecting/reconnected events). */
+    static join(options: JoinOptions): Promise<XmsRoom>;
+    private constructor();
+    /** This client's participantId; a new one after each rejoin. */
+    get localParticipantId(): string;
+    /** Other participants currently in the room. */
+    get participants(): RemoteParticipant[];
+    on<E extends keyof RoomEvents>(event: E, handler: Handler<E>): () => void;
+    /**
+     * Publishes the stream's tracks. Call again to add a track later (e.g. turn the camera on after
+     * joining audio-only): a track whose kind is already published replaces that one in place, a
+     * new kind is added and the publish transport is renegotiated.
+     */
+    publish(stream: MediaStream, options?: PublishOptions): Promise<void>;
+    private publishTracks;
+    /** Stops sending one kind of track (e.g. turn the camera off for good, freeing its bandwidth);
+     *  other participants see a publisherUpdated without it. Use {@link setMuted} for a quick toggle. */
+    unpublishTrack(kind: 'audio' | 'video'): Promise<void>;
+    /** Mutes/unmutes a published track: stops its media locally and tells the room (trackMuted). */
+    setMuted(kind: 'audio' | 'video', muted: boolean): Promise<void>;
+    /** Replaces the outgoing track of that kind without renegotiating (e.g. camera <-> screen). */
+    replaceTrack(kind: 'audio' | 'video', track: MediaStreamTrack): Promise<void>;
+    /** Stops publishing entirely (stays in the room). */
+    unpublish(): Promise<void>;
+    private ensurePublisherPc;
+    private negotiatePublisher;
+    /**
+     * Subscribes to a publisher (all its tracks unless {@link SubscribeOptions.trackIds} narrows it).
+     * Calling again for the same publisher renegotiates that subscription to the new track set.
+     */
+    subscribe(participantId: string, options?: SubscribeOptions): Promise<void>;
+    /** Switches which simulcast layer (a TrackInfo.rids entry) of a subscribed track is received. */
+    setLayer(participantId: string, trackId: string, rid: string): Promise<void>;
+    unsubscribe(participantId: string): Promise<void>;
+    private createSubscription;
+    /** After a renegotiation that dropped tracks, their receivers have ended: report them. */
+    private sweepEndedTracks;
+    private closeSubscription;
+    sendChat(text: string): Promise<void>;
+    /** Sends app data (reactions, raise-hand, cursors, ...) to everyone else in the room, or only to
+     *  `options.to`. `type` is your own label (1-64 chars); `payload` any JSON, at most 16 KB. Not
+     *  echoed back to you; at most 50 per second. */
+    sendData(type: string, payload: unknown, options?: {
+        to?: string[];
+    }): Promise<void>;
+    /** Leaves the room and releases every transport. Local media tracks are left to the caller. */
+    leave(): Promise<void>;
+    /** The underlying PeerConnections, for diagnostics (getStats) and tests. */
+    peerConnections(): {
+        publisher: RTCPeerConnection | null;
+        subscribers: Record<string, RTCPeerConnection>;
+    };
+    /** Takes in a room.join result: the room's participants and publishers, and the subscriptions to
+     *  set up. On a rejoin, reports how the room changed while we were away instead of a fresh list. */
+    private applyJoin;
+    private reconnectIfFailed;
+    /** Drops every transport and the signaling connection, then rejoins with backoff. */
+    private reconnect;
+    private rejoin;
+    private connectAndJoinRefreshingToken;
+    /** Publishes the tracks we had published before the rejoin (still live ones), mute state included. */
+    private republish;
+    private bindSignalingEvents;
+    private upsertParticipant;
+    private enqueue;
+    private closePeerConnection;
+    private emit;
+}
+export {};