@fishjam-cloud/webrtc-client 0.25.0-rc.2 → 0.25.0

package/dist/index.d.mts

@@ -2,6 +2,7 @@ import { BinaryWriter, BinaryReader } from '@bufbuild/protobuf/wire';
 import TypedEmitter from 'typed-emitter';
 
 declare const getLogger: (enableLogging: boolean) => {
+    readonly debug: (arg: unknown, ...args: unknown[]) => void;
     readonly warn: (arg: unknown, ...args: unknown[]) => void;
     readonly error: (arg: unknown, ...args: unknown[]) => void;
 };
@@ -417,6 +418,20 @@ interface WebRTCEndpointEvents {
         trackId: string;
         metadata: unknown;
     }) => void;
+    /**
+     * Emitted when data channels (for both reliable and lossy) are created and ready to send data.
+     * This event is fired after calling connectDataChannels().
+     */
+    dataChannelsReady: () => void;
+    /**
+     * Emitted when data is received on any data channel.
+     * The payload includes the channel type (reliable/lossy) and the binary data.
+     */
+    dataChannelPayload: (payload: DataChannelMessagePayload) => void;
+    /**
+     * Emitted when any data channel errors.
+     */
+    dataChannelsError: (error: Error) => void;
 }
 /**
  * Interface describing Endpoint.
@@ -439,6 +454,39 @@ interface Endpoint {
      */
     tracks: Map<string, TrackContext>;
 }
+/**
+ * Options for publishing or subscribing to data.
+ */
+interface DataChannelOptions {
+    /**
+     * If true, uses the reliable data channel (ordered, guaranteed delivery).
+     * If false, uses the lossy data channel (unordered, low latency).
+     */
+    reliable: boolean;
+}
+/**
+ * Callback type for receiving data from a data channel.
+ * @param data - The received data as a Uint8Array
+ */
+type DataCallback = (data: Uint8Array) => void;
+/**
+ * Internal type for channel classification
+ * @internal
+ */
+type DataChannelType = 'reliable' | 'lossy';
+/**
+ * Payload for data received events from data channels.
+ */
+interface DataChannelMessagePayload {
+    /**
+     * The type of channel the data was received on.
+     */
+    channelType: DataChannelType;
+    /**
+     * The binary payload data.
+     */
+    data: Uint8Array;
+}
 type WebRTCEndpointProps = {
     /**
      * Enables Fishjam SDK's debug logs in the console.
@@ -460,6 +508,7 @@ declare class ConnectionManager {
     removeTrack: (sender: RTCRtpSender) => void;
     findSender: (mediaStreamTrackId: MediaStreamTrackId) => RTCRtpSender;
     addIceCandidate: (iceCandidate: RTCIceCandidate) => Promise<void>;
+    createDataChannel: (label: string, config: RTCDataChannelInit) => RTCDataChannel;
 }
 
 declare const TrackContextImpl_base: new () => TypedEmitter<Required<TrackContextEvents>>;
@@ -493,6 +542,7 @@ declare class WebRTCEndpoint extends WebRTCEndpoint_base {
     private readonly remote;
     private readonly local;
     private readonly commandsQueue;
+    private readonly dataChannelManager;
     private proposedIceServers;
     private logger;
     bandwidthEstimation: bigint;
@@ -556,6 +606,7 @@ declare class WebRTCEndpoint extends WebRTCEndpoint_base {
     getRemoteEndpoints(): Record<string, EndpointWithTrackContext>;
     getLocalEndpoint(): EndpointWithTrackContext;
     getBandwidthEstimation(): bigint;
+    getDataChannelsReadiness(): boolean;
     private handleMediaEvent;
     private onSdpAnswer;
     /**
@@ -760,6 +811,54 @@ declare class WebRTCEndpoint extends WebRTCEndpoint_base {
      * that endpoint was removed in {@link WebRTCEndpointEvents.endpointRemoved},
      */
     disconnect: () => void;
+    /**
+     * Create both reliable and lossy data channel.
+     * This method must be called before publishData() can be used.
+     * Emits the 'dataChannelsReady' event when both channels are open and ready.
+     *
+     * @example
+     * ```ts
+     * const webrtc = new WebRTCEndpoint();
+     *
+     * webrtc.on('dataChannelsReady', () => {
+     *   console.log('Data channels ready, can now send data');
+     *   webrtc.publishData(new TextEncoder().encode('Hello'), { reliable: true });
+     * });
+     *
+     * webrtc.connectDataChannels();
+     * ```
+     */
+    connectDataChannels: () => Promise<void>;
+    /**
+     * Publish data through a data channel.
+     * The data channels must be created first by calling connectDataChannels() 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
+     *
+     * @example
+     * ```ts
+     * // Subscribe to incoming data
+     * webrtc.on('dataReceived', ({ channelType, data }) => {
+     *   console.log(`Received on ${channelType}:`, new TextDecoder().decode(data));
+     * });
+     *
+     * webrtc.on('dataChannelsReady', () => {
+     *   // Send reliable data
+     *   const data = new TextEncoder().encode('Hello World');
+     *   webrtc.publishData(data, { reliable: true });
+     *
+     *   // Send lossy data for low-latency updates
+     *   const gameState = new Uint8Array([1, 2, 3, 4, 5]);
+     *   webrtc.publishData(gameState, { reliable: false });
+     * });
+     *
+     * webrtc.connectDataChannels();
+     * ```
+     */
+    publishData: (data: Uint8Array, options: DataChannelOptions) => void;
     /**
      * Cleans up {@link WebRTCEndpoint} instance.
      */
@@ -777,4 +876,4 @@ declare class WebRTCEndpoint extends WebRTCEndpoint_base {
     private onIceConnectionStateChange;
 }
 
-export { type BandwidthLimit, type EncodingReason, type Endpoint, type Logger, type MediaEvent, type SerializedMediaEvent, type SimulcastBandwidthLimit, MediaEvent_Track_SimulcastConfig as SimulcastConfig, type TrackBandwidthLimit, type TrackContext, type TrackContextEvents, type TrackKind, type VadStatus, Variant, WebRTCEndpoint, type WebRTCEndpointEvents, getLogger };
+export { type BandwidthLimit, type DataCallback, type DataChannelMessagePayload, type DataChannelOptions, type DataChannelType, type EncodingReason, type Endpoint, type Logger, type MediaEvent, type SerializedMediaEvent, type SimulcastBandwidthLimit, MediaEvent_Track_SimulcastConfig as SimulcastConfig, type TrackBandwidthLimit, type TrackContext, type TrackContextEvents, type TrackKind, type VadStatus, Variant, WebRTCEndpoint, type WebRTCEndpointEvents, getLogger };

package/dist/index.mjs

@@ -1,6 +1,9 @@
 // src/logger.ts
 var FISHJAM_PREFIX = "[FISHJAM]";
 var getLogger = (enableLogging) => ({
+  debug: (arg, ...args) => {
+    if (enableLogging) console.debug(FISHJAM_PREFIX, arg, ...args);
+  },
   warn: (arg, ...args) => {
     if (enableLogging) console.warn(FISHJAM_PREFIX, arg, ...args);
   },
@@ -1393,7 +1396,7 @@ function isSet2(value) {
 }
 
 // src/webRTCEndpoint.ts
-import EventEmitter2 from "events";
+import EventEmitter3 from "events";
 import { v4 as uuidv4 } from "uuid";
 
 // src/CommandsQueue.ts
@@ -1527,6 +1530,306 @@ var ConnectionManager = class {
   addIceCandidate = async (iceCandidate) => {
     await this.connection.addIceCandidate(iceCandidate);
   };
+  createDataChannel = (label, config) => {
+    return this.connection.createDataChannel(label, config);
+  };
+};
+
+// src/dataChannels/DataChannelManager.ts
+import { EventEmitter } from "events";
+
+// src/dataChannels/DataChannel.ts
+var DataChannel = class {
+  constructor(type, logger) {
+    this.type = type;
+    this.logger = logger;
+  }
+  channel = null;
+  dataCallback = null;
+  openCallback = null;
+  errorCallback = null;
+  _status = "init";
+  /**
+   * Get the current status of the data channel
+   */
+  get status() {
+    return this._status;
+  }
+  /**
+   * Set the underlying RTCDataChannel and set up event listeners
+   */
+  setChannel(channel) {
+    this._status = "creating";
+    this.channel = channel;
+    this.setupListeners();
+  }
+  /**
+   * Set callback to be called when the channel is opened
+   */
+  setOnOpen(callback) {
+    this.openCallback = callback;
+  }
+  /**
+   * Set callback to be called when the channel errors
+   */
+  setOnError(callback) {
+    this.errorCallback = callback;
+  }
+  /**
+   * Send data through the channel
+   * @param data - The data to send as Uint8Array
+   */
+  send(data) {
+    if (!this.channel || this._status !== "open") {
+      this.logger.warn(`Cannot send data on ${this.type} channel: channel not ready (status: ${this._status})`);
+      return;
+    }
+    try {
+      this.channel.send(data);
+    } catch (error) {
+      this.logger.error(`Error sending data on ${this.type} channel:`, error);
+    }
+  }
+  /**
+   * Set the callback for receiving data
+   * @param callback - Function to call when data is received
+   */
+  setCallback(callback) {
+    this.dataCallback = callback;
+  }
+  /**
+   * Close the data channel
+   */
+  close() {
+    if (this.channel) {
+      this.channel.close();
+    }
+    this._status = "closed";
+    this.dataCallback = null;
+  }
+  /**
+   * Set up event listeners for the RTCDataChannel
+   * @private
+   */
+  setupListeners() {
+    if (!this.channel) return;
+    this.channel.onopen = () => {
+      this._status = "open";
+      this.logger.debug(`Data channel ${this.type} opened`);
+      this.openCallback?.();
+    };
+    this.channel.onclose = () => {
+      this._status = "closed";
+      this.logger.debug(`Data channel ${this.type} closed`);
+    };
+    this.channel.onerror = (event) => {
+      this.logger.error(`Data channel ${this.type} error:`, event);
+      this.errorCallback?.(event);
+    };
+    this.channel.onmessage = (event) => {
+      this.handleMessage(event.data);
+    };
+  }
+  /**
+   * Handle incoming message data
+   * @private
+   */
+  handleMessage(data) {
+    if (!this.dataCallback) {
+      this.logger.warn(`Received data on ${this.type} channel but no callback is set`);
+      return;
+    }
+    try {
+      let uint8Data;
+      if (data instanceof ArrayBuffer) {
+        uint8Data = new Uint8Array(data);
+      } else if (data instanceof Uint8Array) {
+        uint8Data = data;
+      } else if (typeof data === "string") {
+        uint8Data = new TextEncoder().encode(data);
+      } else if (data instanceof Blob) {
+        const reader = new FileReader();
+        reader.onload = () => {
+          if (reader.result instanceof ArrayBuffer) {
+            this.dataCallback?.(new Uint8Array(reader.result));
+          }
+        };
+        reader.readAsArrayBuffer(data);
+        return;
+      } else {
+        this.logger.warn(`Received unsupported data type on ${this.type} channel:`, typeof data);
+        return;
+      }
+      this.dataCallback(uint8Data);
+    } catch (error) {
+      this.logger.error(`Error handling message on ${this.type} channel:`, error);
+    }
+  }
+};
+
+// src/dataChannels/DataChannelManager.ts
+var DataChannelManager = class extends EventEmitter {
+  constructor(createDataChannel, triggerRenegotiation, logger) {
+    super();
+    this.createDataChannel = createDataChannel;
+    this.triggerRenegotiation = triggerRenegotiation;
+    this.logger = logger;
+  }
+  reliableChannel = null;
+  lossyChannel = null;
+  /**
+   * Initialize channels and trigger renegotiation.
+   * Returns when both channels are open or throws if any channel errors.
+   */
+  async connect() {
+    if (this.getChannelsReadiness()) return;
+    this.createChannels();
+    this.triggerRenegotiation();
+    await this.waitForChannelsReady();
+  }
+  /**
+   * Wait for both channels to be ready or throw on error.
+   * @private
+   */
+  waitForChannelsReady() {
+    if (this.getChannelsReadiness()) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const onReady = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (type, error) => {
+        cleanup();
+        reject(new Error(`Data channel ${type} error: ${error}`));
+      };
+      const cleanup = () => {
+        this.removeListener("ready", onReady);
+        this.removeListener("error", onError);
+      };
+      this.on("ready", onReady);
+      this.on("error", onError);
+    });
+  }
+  /**
+   * Publish data through a data channel.
+   * Throws an error if the channel doesn't exist or isn't ready.
+   * @param data - The data to send as Uint8Array
+   * @param options - Options specifying which channel to use
+   * @throws Error if the channel doesn't exist or isn't open
+   */
+  publishData(data, options) {
+    const type = options.reliable ? "reliable" : "lossy";
+    const channel = type === "reliable" ? this.reliableChannel : this.lossyChannel;
+    if (!channel) {
+      throw new Error(
+        `Cannot publish data: ${type} channel not created. Call connectDataPublishers() first or enable negotiateOnConnect.`
+      );
+    }
+    if (channel.status !== "open") {
+      throw new Error(
+        `Cannot publish data: ${type} channel not ready (status: ${channel.status}). Wait for dataChannelsReady event.`
+      );
+    }
+    channel.send(data);
+  }
+  /**
+   * Close all data channels and remove all event listeners.
+   * Called during cleanup/disconnect.
+   */
+  cleanup() {
+    this.logger.warn("Cleaning up data channels");
+    if (this.reliableChannel) {
+      this.reliableChannel.close();
+      this.reliableChannel = null;
+    }
+    if (this.lossyChannel) {
+      this.lossyChannel.close();
+      this.lossyChannel = null;
+    }
+    this.removeAllListeners();
+  }
+  /**
+   * Check if both data channels are open and ready to send data.
+   * @returns true if both channels are open and ready, false otherwise
+   */
+  getChannelsReadiness() {
+    return this.reliableChannel?.status === "open" && this.lossyChannel?.status === "open";
+  }
+  createChannels() {
+    this.createChannel("reliable");
+    this.createChannel("lossy");
+  }
+  /**
+   * Create a single data channel.
+   * @private
+   */
+  createChannel(type) {
+    const channel = this.getOrCreateChannelWrapper(type);
+    if (channel.status !== "init") return;
+    const label = type;
+    const config = type === "reliable" ? { ordered: true } : { ordered: false, maxRetransmits: 0 };
+    const rtcChannel = this.createDataChannel(label, config);
+    channel.setOnOpen(() => this.onChannelOpen(type));
+    channel.setOnError((error) => this.onChannelError(type, error));
+    channel.setChannel(rtcChannel);
+    this.logger.warn(`Created ${type} data channel`);
+  }
+  /**
+   * Called when a data channel opens.
+   * Emits channelOpen event and checks if both channels are open.
+   * @private
+   */
+  onChannelOpen(type) {
+    this.logger.warn(`Data channel ${type} opened`);
+    this.emit("channelOpen", type);
+    const bothReady = this.reliableChannel && this.reliableChannel.status === "open" && this.lossyChannel && this.lossyChannel.status === "open";
+    if (bothReady) {
+      this.logger.warn("All data publishers ready");
+      this.emit("ready");
+    }
+  }
+  /**
+   * Called when a data channel errors.
+   * @private
+   */
+  onChannelError(type, error) {
+    this.logger.error(`Data channel ${type} error:`, error);
+    this.emit("error", type, error);
+  }
+  /**
+   * Handle data received from a channel and emit the dataReceived event.
+   * @param type - The type of channel the data was received on
+   * @param data - The received binary data
+   * @private
+   */
+  onDataReceived(type, data) {
+    const payload = {
+      channelType: type,
+      data
+    };
+    this.emit("data", payload);
+  }
+  /**
+   * Get existing channel wrapper or create a new one (without RTCDataChannel).
+   * @param type - The type of channel
+   * @returns The DataChannel wrapper instance
+   * @private
+   */
+  getOrCreateChannelWrapper(type) {
+    if (type === "reliable") {
+      if (!this.reliableChannel) {
+        this.reliableChannel = new DataChannel(type, this.logger);
+        this.reliableChannel.setCallback((data) => this.onDataReceived(type, data));
+      }
+      return this.reliableChannel;
+    } else {
+      if (!this.lossyChannel) {
+        this.lossyChannel = new DataChannel(type, this.logger);
+        this.lossyChannel.setCallback((data) => this.onDataReceived(type, data));
+      }
+      return this.lossyChannel;
+    }
+  }
 };
 
 // src/deferred.ts
@@ -3609,9 +3912,9 @@ function deserializeServerMediaEvent(serializedMediaEvent) {
 }
 
 // src/internal.ts
-import EventEmitter from "events";
+import EventEmitter2 from "events";
 var isTrackKind = (kind) => kind === "audio" || kind === "video";
-var TrackContextImpl = class extends EventEmitter {
+var TrackContextImpl = class extends EventEmitter2 {
   constructor(endpoint, trackId, metadata, simulcastConfig = { enabled: false, enabledVariants: [], disabledVariants: [] }) {
     super();
     this.endpoint = endpoint;
@@ -4422,11 +4725,12 @@ var Remote = class {
 };
 
 // src/webRTCEndpoint.ts
-var WebRTCEndpoint = class extends EventEmitter2 {
+var WebRTCEndpoint = class extends EventEmitter3 {
   localTrackManager;
   remote;
   local;
   commandsQueue;
+  dataChannelManager;
   proposedIceServers = [];
   logger;
   bandwidthEstimation = BigInt(0);
@@ -4443,6 +4747,25 @@ var WebRTCEndpoint = class extends EventEmitter2 {
     this.local = new Local(emit, sendEvent);
     this.localTrackManager = new LocalTrackManager(this.local, sendEvent);
     this.commandsQueue = new CommandsQueue(this.localTrackManager);
+    const createDataChannelFn = (label, init) => {
+      if (!this.connectionManager) {
+        this.connectionManager = new ConnectionManager(this.proposedIceServers);
+      }
+      return this.connectionManager.createDataChannel(label, init);
+    };
+    const triggerRenegotiationFn = () => {
+      this.sendMediaEvent({ renegotiateTracks: MediaEvent_RenegotiateTracks.create() });
+    };
+    this.dataChannelManager = new DataChannelManager(createDataChannelFn, triggerRenegotiationFn, this.logger);
+    this.dataChannelManager.on("ready", () => {
+      this.emit("dataChannelsReady");
+    });
+    this.dataChannelManager.on("data", (payload) => {
+      this.emit("dataChannelPayload", payload);
+    });
+    this.dataChannelManager.on("error", (_, event) => {
+      this.emit("dataChannelsError", new Error(`Data channel error event: ${event.type}`));
+    });
   }
   /**
    * Tries to connect to the RTC Engine. If user is successfully connected then {@link WebRTCEndpointEvents.connected}
@@ -4545,6 +4868,9 @@ var WebRTCEndpoint = class extends EventEmitter2 {
   getBandwidthEstimation() {
     return this.bandwidthEstimation;
   }
+  getDataChannelsReadiness() {
+    return this.dataChannelManager?.getChannelsReadiness() ?? false;
+  }
   handleMediaEvent = async (event) => {
     if (event.offerData) {
       await this.onOfferData(event.offerData);
@@ -4913,6 +5239,58 @@ var WebRTCEndpoint = class extends EventEmitter2 {
     this.emit("disconnectRequested", {});
     this.cleanUp();
   };
+  /**
+   * Create both reliable and lossy data channel.
+   * This method must be called before publishData() can be used.
+   * Emits the 'dataChannelsReady' event when both channels are open and ready.
+   *
+   * @example
+   * ```ts
+   * const webrtc = new WebRTCEndpoint();
+   *
+   * webrtc.on('dataChannelsReady', () => {
+   *   console.log('Data channels ready, can now send data');
+   *   webrtc.publishData(new TextEncoder().encode('Hello'), { reliable: true });
+   * });
+   *
+   * webrtc.connectDataChannels();
+   * ```
+   */
+  connectDataChannels = () => {
+    return this.dataChannelManager.connect();
+  };
+  /**
+   * Publish data through a data channel.
+   * The data channels must be created first by calling connectDataChannels() 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
+   *
+   * @example
+   * ```ts
+   * // Subscribe to incoming data
+   * webrtc.on('dataReceived', ({ channelType, data }) => {
+   *   console.log(`Received on ${channelType}:`, new TextDecoder().decode(data));
+   * });
+   *
+   * webrtc.on('dataChannelsReady', () => {
+   *   // Send reliable data
+   *   const data = new TextEncoder().encode('Hello World');
+   *   webrtc.publishData(data, { reliable: true });
+   *
+   *   // Send lossy data for low-latency updates
+   *   const gameState = new Uint8Array([1, 2, 3, 4, 5]);
+   *   webrtc.publishData(gameState, { reliable: false });
+   * });
+   *
+   * webrtc.connectDataChannels();
+   * ```
+   */
+  publishData = (data, options) => {
+    this.dataChannelManager.publishData(data, options);
+  };
   /**
    * Cleans up {@link WebRTCEndpoint} instance.
    */
@@ -4922,6 +5300,7 @@ var WebRTCEndpoint = class extends EventEmitter2 {
       this.connectionManager?.getConnection().close();
       this.commandsQueue.cleanUp();
       this.localTrackManager.cleanUp();
+      this.dataChannelManager?.cleanup();
     }
     this.connectionManager = void 0;
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fishjam-cloud/webrtc-client",
-  "version": "0.25.0-rc.2",
+  "version": "0.25.0",
   "description": "Typescript client library for ExWebRTC/WebRTC endpoint in Membrane RTC Engine",
   "license": "Apache-2.0",
   "author": "Fishjam Team",
@@ -75,6 +75,5 @@
     "*.(js|ts|tsx)": [
       "yarn lint"
     ]
-  },
-  "stableVersion": "0.24.0"
+  }
 }