@fishjam-cloud/ts-client 0.25.0 → 0.25.2

package/dist/ts-client/src/FishjamClient.d.ts

@@ -0,0 +1,438 @@
+import type { PeerMessage_SdkDeprecation } from '@fishjam-cloud/protobufs/fishjamPeer';
+import type { BandwidthLimit, DataCallback, DataChannelOptions, SimulcastConfig, TrackBandwidthLimit, Variant } from '@fishjam-cloud/webrtc-client';
+import type TypedEmitter from 'typed-emitter';
+import type { Component, ConnectConfig, CreateConfig, FishjamTrackContext, GenericMetadata, MessageEvents, Peer, TrackMetadata } from './types';
+declare const FishjamClient_base: {
+    new <P, S>(): TypedEmitter<MessageEvents<P, S>>;
+};
+/**
+ * FishjamClient is the main class to interact with Fishjam.
+ *
+ * @example
+ * ```typescript
+ * const client = new FishjamClient<PeerMetadata>();
+ * const peerToken = "YOUR_PEER_TOKEN";
+ *
+ * // You can listen to events emitted by the client
+ * client.on("joined", (peerId, peersInRoom) => {
+ *  console.log("join success");
+ * });
+ *
+ * // Start the peer connection
+ * client.connect({
+ *  peerMetadata: {},
+ *  isSimulcastOn: false,
+ *  token: peerToken
+ * });
+ *
+ * // Close the peer connection
+ * client.disconnect();
+ * ```
+ *
+ * You can register callbacks to handle the events emitted by the Client.
+ *
+ * @example
+ * ```typescript
+ *
+ * client.on("trackReady", (ctx) => {
+ *  console.log("On track ready");
+ * });
+ * ```
+ */
+export declare class FishjamClient<PeerMetadata = GenericMetadata, ServerMetadata = GenericMetadata> extends FishjamClient_base<PeerMetadata, ServerMetadata> {
+    private websocket;
+    private webrtc;
+    private removeEventListeners;
+    private debug;
+    private logger;
+    private clientType;
+    status: 'new' | 'initialized';
+    private connectConfig;
+    private isAudioOnlyConnection;
+    private reconnectManager;
+    private peerMessageQueue;
+    private sendStatisticsInterval;
+    constructor(config?: CreateConfig);
+    /**
+     * Uses the WebSocket connection and {@link !WebRTCEndpoint | WebRTCEndpoint} to join to the room. Registers the callbacks to
+     * handle the events emitted by the {@link !WebRTCEndpoint | WebRTCEndpoint}. Make sure that peer metadata is serializable.
+     *
+     * @example
+     * ```typescript
+     * const client = new FishjamClient<PeerMetadata>();
+     *
+     * client.connect({
+     *  peerMetadata: {},
+     *  token: peerToken
+     * });
+     * ```
+     *
+     * @param {ConnectConfig} config - Configuration object for the client
+     */
+    connect(config: ConnectConfig<PeerMetadata>): Promise<void>;
+    private initConnection;
+    private getUrl;
+    private initWebsocket;
+    handleSdkDeprecation(sdkDeprecation: PeerMessage_SdkDeprecation): void;
+    /**
+     * Retrieves statistics related to the RTCPeerConnection.
+     * These statistics provide insights into the performance and status of the connection.
+     *
+     * @return {Promise<RTCStatsReport>}
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/getStats | MDN Web Docs: RTCPeerConnection.getStats()}
+     */
+    getStatistics(selector?: MediaStreamTrack | null): Promise<RTCStatsReport>;
+    /**
+     * Returns a snapshot of currently received remote tracks.
+     *
+     * @example
+     * if (client.getRemoteTracks()[trackId]?.simulcastConfig?.enabled) {
+     *   client.setTargetTrackEncoding(trackId, encoding);
+     * }
+     */
+    getRemoteTracks(): Readonly<Record<string, FishjamTrackContext>>;
+    /**
+     * Returns a snapshot of currently received remote peers.
+     */
+    getRemotePeers(): Record<string, Peer<PeerMetadata, ServerMetadata>>;
+    getRemoteComponents(): Record<string, Component>;
+    getLocalPeer(): Peer<PeerMetadata, ServerMetadata> | null;
+    getBandwidthEstimation(): bigint;
+    private isConnectingRelatedEvent;
+    private setupCallbacks;
+    private sendStatistics;
+    /**
+     * Register a callback to be called when the event is emitted.
+     * Full list of callbacks can be found here {@link MessageEvents}.
+     *
+     * @example
+     * ```ts
+     * const callback = ()=>{  };
+     *
+     * client.on("onJoinSuccess", callback);
+     * ```
+     *
+     * @param event - Event name from {@link MessageEvents}
+     * @param listener - Callback function to be called when the event is emitted
+     * @returns This
+     */
+    on<E extends keyof MessageEvents<PeerMetadata, ServerMetadata>>(event: E, listener: MessageEvents<PeerMetadata, ServerMetadata>[E]): this;
+    /**
+     * Remove a callback from the list of callbacks to be called when the event is emitted.
+     *
+     * @example
+     * ```ts
+     * const callback = ()=>{  };
+     *
+     * client.on("onJoinSuccess", callback);
+     *
+     * client.off("onJoinSuccess", callback);
+     * ```
+     *
+     * @param event - Event name from {@link MessageEvents}
+     * @param listener - Reference to function to be removed from called callbacks
+     * @returns This
+     */
+    off<E extends keyof MessageEvents<PeerMetadata, ServerMetadata>>(event: E, listener: MessageEvents<PeerMetadata, ServerMetadata>[E]): this;
+    private handleWebRTCNotInitialized;
+    /**
+     * Adds track that will be sent to the RTC Engine.
+     *
+     * @example
+     * ```ts
+     * const localStream: MediaStream = new MediaStream();
+     * try {
+     *   const localAudioStream = await navigator.mediaDevices.getUserMedia(
+     *     { audio: true }
+     *   );
+     *   localAudioStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get microphone permission:", error);
+     * }
+     *
+     * try {
+     *   const localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     { video: true }
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *  console.error("Couldn't get camera permission:", error);
+     * }
+     *
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => client.addTrack(track, localStream));
+     * ```
+     *
+     * @param track - Audio or video track e.g. from your microphone or camera.
+     * @param trackMetadata - Any information about this track that other peers will receive in
+     * {@link MessageEvents.peerJoined}. E.g. this can source of the track - wheather it's screensharing, webcam or some
+     * other media device.
+     * @param simulcastConfig - Simulcast configuration. By default, simulcast is disabled. For more information refer to
+     * {@link !SimulcastConfig | SimulcastConfig}.
+     * @param maxBandwidth - Maximal bandwidth this track can use. Defaults to 0 which is unlimited. This option has no
+     * effect for simulcast and audio tracks. For simulcast tracks use {@link FishjamClient.setTrackBandwidth}.
+     * @returns {string} Returns id of added track
+     */
+    addTrack(track: MediaStreamTrack, trackMetadata?: TrackMetadata, simulcastConfig?: SimulcastConfig, maxBandwidth?: TrackBandwidthLimit): Promise<string>;
+    /**
+     * Replaces a track that is being sent to the RTC Engine.
+     *
+     * @example
+     * ```ts
+     * // setup camera
+     * let localStream: MediaStream = new MediaStream();
+     * try {
+     *   localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     VIDEO_CONSTRAINTS
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get camera permission:", error);
+     * }
+     * let oldTrackId;
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => trackId = webrtc.addTrack(track, localStream));
+     *
+     * // change camera
+     * const oldTrack = localStream.getVideoTracks()[0];
+     * let videoDeviceId = "abcd-1234";
+     * navigator.mediaDevices.getUserMedia({
+     *      video: {
+     *        ...(VIDEO_CONSTRAINTS as {}),
+     *        deviceId: {
+     *          exact: videoDeviceId,
+     *        },
+     *      }
+     *   })
+     *   .then((stream) => {
+     *     let videoTrack = stream.getVideoTracks()[0];
+     *     webrtc.replaceTrack(oldTrackId, videoTrack);
+     *   })
+     *   .catch((error) => {
+     *     console.error('Error switching camera', error);
+     *   })
+     * ```
+     *
+     * @param {string} trackId - Id of audio or video track to replace.
+     * @param {MediaStreamTrack} newTrack - New audio or video track.
+     * @returns {Promise<boolean>} Success
+     */
+    replaceTrack(trackId: string, newTrack: MediaStreamTrack | null): Promise<void>;
+    /**
+     * Updates maximum bandwidth for the track identified by trackId. This value directly translates to quality of the
+     * stream and, in case of video, to the amount of RTP packets being sent. In case trackId points at the simulcast
+     * track bandwidth is split between all of the variant streams proportionally to their resolution.
+     *
+     * @param {string} trackId
+     * @param {BandwidthLimit} bandwidth In kbps
+     * @returns {Promise<boolean>} Success
+     */
+    setTrackBandwidth(trackId: string, bandwidth: BandwidthLimit): Promise<boolean>;
+    /**
+     * Updates maximum bandwidth for the given simulcast encoding of the given track.
+     *
+     * @param {string} trackId - Id of the track
+     * @param {string} rid - Rid of the encoding
+     * @param {BandwidthLimit} bandwidth - Desired max bandwidth used by the encoding (in kbps)
+     * @returns
+     */
+    setEncodingBandwidth(trackId: string, rid: Variant, bandwidth: BandwidthLimit): Promise<boolean>;
+    /**
+     * Removes a track from connection that was being sent to the RTC Engine.
+     *
+     * @example
+     * ```ts
+     * // setup camera
+     * let localStream: MediaStream = new MediaStream();
+     * try {
+     *   localVideoStream = await navigator.mediaDevices.getUserMedia(
+     *     VIDEO_CONSTRAINTS
+     *   );
+     *   localVideoStream
+     *     .getTracks()
+     *     .forEach((track) => localStream.addTrack(track));
+     * } catch (error) {
+     *   console.error("Couldn't get camera permission:", error);
+     * }
+     *
+     * let trackId
+     * localStream
+     *  .getTracks()
+     *  .forEach((track) => trackId = webrtc.addTrack(track, localStream));
+     *
+     * // remove track
+     * webrtc.removeTrack(trackId)
+     * ```
+     *
+     * @param {string} trackId - Id of audio or video track to remove.
+     */
+    removeTrack(trackId: string): Promise<void>;
+    /**
+     * Sets track encoding that server should send to the client library.
+     *
+     * The encoding will be sent whenever it is available. If chosen encoding is temporarily unavailable, some other
+     * encoding will be sent until chosen encoding becomes active again.
+     *
+     * @example
+     * ```ts
+     * webrtc.setTargetTrackEncoding(incomingTrackCtx.trackId, "l")
+     * ```
+     *
+     * @param {string} trackId - Id of track
+     * @param {Encoding} encoding - Encoding to receive
+     */
+    setTargetTrackEncoding(trackId: string, encoding: Variant): void;
+    /**
+     * Enables track encoding so that it will be sent to the server.
+     *
+     * @example
+     * ```ts
+     * const trackId = webrtc.addTrack(track, stream, {}, {enabled: true, active_encodings: ["l", "m", "h"]});
+     * webrtc.disableTrackEncoding(trackId, "l");
+     * // wait some time
+     * webrtc.enableTrackEncoding(trackId, "l");
+     * ```
+     *
+     * @param {string} trackId - Id of track
+     * @param {Encoding} encoding - Encoding that will be enabled
+     */
+    enableTrackEncoding(trackId: string, encoding: Variant): Promise<void>;
+    /**
+     * Disables track encoding so that it will be no longer sent to the server.
+     *
+     * @example
+     * ```ts
+     * const trackId = webrtc.addTrack(track, stream, {}, {enabled: true, active_encodings: ["l", "m", "h"]});
+     * webrtc.disableTrackEncoding(trackId, "l");
+     * ```
+     *
+     * @param {string} trackId - Id of track
+     * @param {Encoding} encoding - Encoding that will be disabled
+     */
+    disableTrackEncoding(trackId: string, encoding: Variant): Promise<void>;
+    /**
+     * Updates the metadata for the current peer.
+     *
+     * @param peerMetadata - Data about this peer that other peers will receive upon joining.
+     *
+     * If the metadata is different from what is already tracked in the room, the event {@link MessageEvents.peerUpdated} will
+     * be emitted for other peers in the room.
+     */
+    updatePeerMetadata: (peerMetadata: PeerMetadata) => void;
+    /**
+     * Updates the metadata for a specific track.
+     *
+     * @param trackId - TrackId (generated in addTrack) of audio or video track.
+     * @param trackMetadata - Data about this track that other peers will receive upon joining.
+     *
+     * If the metadata is different from what is already tracked in the room, the event {@link MessageEvents.trackUpdated} will
+     * be emitted for other peers in the room.
+     */
+    updateTrackMetadata: (trackId: string, trackMetadata: TrackMetadata) => void;
+    isReconnecting(): boolean;
+    getDataChannelsReadiness(): boolean;
+    /**
+     * Leaves the room. This function should be called when user leaves the room in a clean way e.g. by clicking a
+     * dedicated, custom button `disconnect`. As a result there will be generated one more media event that should be sent
+     * to the RTC Engine. Thanks to it each other peer will be notified that peer left in {@link MessageEvents.peerLeft},
+     */
+    leave: () => void;
+    private isOpen;
+    /**
+     * Create both reliable and lossy data channel publishers.
+     * This method must be called before publishData() can be used (unless negotiateOnConnect is enabled).
+     * Emits the 'dataChannelsReady' event when both channels are open and ready.
+     *
+     * @throws Error if data channels are not enabled in the constructor config
+     *
+     * @example
+     * ```typescript
+     * const client = new FishjamClient({ dataChannels: {} });
+     *
+     * client.on('dataChannelsReady', () => {
+     *   console.log('Data channels ready, can now send data');
+     *   client.publishData(new TextEncoder().encode('Hello'), { reliable: true });
+     * });
+     *
+     * client.createDataChannels();
+     * ```
+     */
+    createDataChannels(): Promise<void>;
+    /**
+     * Publish data through a data channel.
+     * The data channels must be created first by calling createDataChannels() or enabling negotiateOnConnect.
+     * Throws an error if the channel doesn't exist or isn't ready yet.
+     *
+     * @param data - The data to send as Uint8Array
+     * @param options - Options specifying which channel to use (reliable or lossy)
+     * @throws Error if the channel doesn't exist or isn't ready, or if webrtc is not initialized
+     *
+     * @example
+     * ```typescript
+     * client.on('dataChannelsReady', () => {
+     *   // Send reliable data
+     *   const data = new TextEncoder().encode('Hello World');
+     *   client.publishData(data, { reliable: true });
+     *
+     *   // Send lossy data for low-latency updates
+     *   const gameState = new Uint8Array([1, 2, 3, 4, 5]);
+     *   client.publishData(gameState, { reliable: false });
+     * });
+     *
+     * client.createDataChannels();
+     * ```
+     */
+    publishData(data: Uint8Array, options: DataChannelOptions): void;
+    /**
+     * Subscribe to data from a specific channel type.
+     * Can be called before or after creating the data channels.
+     * If called before, the callback will be applied when the channel is created.
+     *
+     * @param callback - Function to call when data is received
+     * @param options - Options specifying which channel to subscribe to (reliable or lossy)
+     * @throws Error if webrtc is not initialized
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to reliable channel
+     * client.subscribeData((data) => {
+     *   const message = new TextDecoder().decode(data);
+     *   console.log('Received:', message);
+     * }, { reliable: true });
+     *
+     * // Subscribe to lossy channel
+     * client.subscribeData((data) => {
+     *   console.log('Received game state:', data);
+     * }, { reliable: false });
+     *
+     * // Then create publishers
+     * client.createDataChannels();
+     * ```
+     */
+    subscribeData(callback: DataCallback, options: DataChannelOptions): () => void;
+    /**
+     * Disconnect from the room, and close the websocket connection. Tries to leave the room gracefully, but if it fails,
+     * it will close the websocket anyway.
+     *
+     * @example
+     * ```typescript
+     * const client = new FishjamClient<PeerMetadata>();
+     *
+     * client.connect({ ... });
+     *
+     * client.disconnect();
+     * ```
+     */
+    disconnect(): void;
+    cleanup(): void;
+}
+export {};