npm - @kyneta/webrtc-transport - Versions diffs - 1.3.1 → 1.4.0 - Mend

@kyneta/webrtc-transport 1.3.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/index.d.ts +125 -122
package/dist/index.d.ts.map +1 -0
package/dist/index.js +249 -222
package/dist/index.js.map +1 -1
package/package.json +9 -9
package/src/__tests__/webrtc-transport.test.ts +7 -7
package/src/webrtc-transport.ts +2 -2

package/dist/index.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
-import { Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport';
+import { GeneratedChannel, Transport, TransportFactory } from "@kyneta/transport";
+//#region src/data-channel-like.d.ts
 /**
  * Minimal interface for a WebRTC-style data channel.
  *
@@ -27,61 +28,62 @@ import { Transport, GeneratedChannel, TransportFactory } from '@kyneta/transport
  * the WebRTC connection lifecycle independently.
  */
 interface DataChannelLike {
-    /**
-     * Current state of the data channel.
-     *
-     * The transport treats `"open"` as sendable; all other values
-     * (including `"connecting"`, `"closing"`, `"closed"`) as not sendable.
-     *
-     * For native `RTCDataChannel`, this is one of:
-     * `"connecting" | "open" | "closing" | "closed"`.
-     *
-     * Wrappers may return any string — the transport only checks `=== "open"`.
-     */
-    readonly readyState: string;
-    /**
-     * Binary type hint for incoming data.
-     *
-     * The transport writes `"arraybuffer"` on attach as a best-effort hint.
-     * It does NOT depend on this being respected — the message handler
-     * accepts both `ArrayBuffer` and `Uint8Array` data regardless.
-     *
-     * For native `RTCDataChannel`, this controls whether `MessageEvent.data`
-     * is an `ArrayBuffer` or a `Blob`. For wrappers that ignore this
-     * property (e.g. simple-peer bridges), the write is harmless.
-     */
-    binaryType: string;
-    /**
-     * Send binary data through the data channel.
-     *
-     * The transport always sends `Uint8Array` instances (CBOR-encoded
-     * wire frames, optionally fragmented). Native `RTCDataChannel.send`
-     * accepts `ArrayBufferView` (which `Uint8Array` satisfies), so
-     * conformance is structural.
-     */
-    send(data: Uint8Array): void;
-    /**
-     * Register an event listener.
-     *
-     * The transport uses this for `"open"`, `"close"`, `"error"`, and
-     * `"message"` events. For `"message"` events, the transport reads
-     * `event.data` and handles both `ArrayBuffer` and `Uint8Array`.
-     *
-     * @param type - Event type string
-     * @param listener - Callback. The `event` parameter is untyped to
-     *   avoid coupling to DOM `Event` / `MessageEvent` types.
-     */
-    addEventListener(type: string, listener: (event: any) => void): void;
-    /**
-     * Remove a previously registered event listener.
-     *
-     * Called during `detachDataChannel()` to clean up all four event
-     * listeners. The transport always passes the same function reference
-     * that was used in `addEventListener`.
-     */
-    removeEventListener(type: string, listener: (event: any) => void): void;
+  /**
+   * Current state of the data channel.
+   *
+   * The transport treats `"open"` as sendable; all other values
+   * (including `"connecting"`, `"closing"`, `"closed"`) as not sendable.
+   *
+   * For native `RTCDataChannel`, this is one of:
+   * `"connecting" | "open" | "closing" | "closed"`.
+   *
+   * Wrappers may return any string — the transport only checks `=== "open"`.
+   */
+  readonly readyState: string;
+  /**
+   * Binary type hint for incoming data.
+   *
+   * The transport writes `"arraybuffer"` on attach as a best-effort hint.
+   * It does NOT depend on this being respected — the message handler
+   * accepts both `ArrayBuffer` and `Uint8Array` data regardless.
+   *
+   * For native `RTCDataChannel`, this controls whether `MessageEvent.data`
+   * is an `ArrayBuffer` or a `Blob`. For wrappers that ignore this
+   * property (e.g. simple-peer bridges), the write is harmless.
+   */
+  binaryType: string;
+  /**
+   * Send binary data through the data channel.
+   *
+   * The transport always sends `Uint8Array` instances (CBOR-encoded
+   * wire frames, optionally fragmented). Native `RTCDataChannel.send`
+   * accepts `ArrayBufferView` (which `Uint8Array` satisfies), so
+   * conformance is structural.
+   */
+  send(data: Uint8Array): void;
+  /**
+   * Register an event listener.
+   *
+   * The transport uses this for `"open"`, `"close"`, `"error"`, and
+   * `"message"` events. For `"message"` events, the transport reads
+   * `event.data` and handles both `ArrayBuffer` and `Uint8Array`.
+   *
+   * @param type - Event type string
+   * @param listener - Callback. The `event` parameter is untyped to
+   *   avoid coupling to DOM `Event` / `MessageEvent` types.
+   */
+  addEventListener(type: string, listener: (event: any) => void): void;
+  /**
+   * Remove a previously registered event listener.
+   *
+   * Called during `detachDataChannel()` to clean up all four event
+   * listeners. The transport always passes the same function reference
+   * that was used in `addEventListener`.
+   */
+  removeEventListener(type: string, listener: (event: any) => void): void;
 }
+//#endregion
+//#region src/webrtc-transport.d.ts
 /**
  * Default fragment threshold in bytes.
  *
@@ -96,20 +98,20 @@ declare const DEFAULT_FRAGMENT_THRESHOLD: number;
  * Configuration options for the WebRTC transport.
  */
 interface WebrtcTransportOptions {
-    /**
-     * Fragment threshold in bytes. Messages larger than this are fragmented
-     * for SCTP compatibility. Set to 0 to disable fragmentation (not recommended).
-     *
-     * @default 204800 (200KB)
-     */
-    fragmentThreshold?: number;
+  /**
+   * Fragment threshold in bytes. Messages larger than this are fragmented
+   * for SCTP compatibility. Set to 0 to disable fragmentation (not recommended).
+   *
+   * @default 204800 (200KB)
+   */
+  fragmentThreshold?: number;
 }
 /**
  * Context for each attached data channel — stored per remotePeerId.
  */
 type DataChannelContext = {
-    remotePeerId: string;
-    channel: DataChannelLike;
+  remotePeerId: string;
+  channel: DataChannelLike;
 };
 /**
  * WebRTC data channel transport for @kyneta/exchange.
@@ -130,7 +132,7 @@ type DataChannelContext = {
  * const webrtcTransport = createWebrtcTransport()
  *
  * const exchange = new Exchange({
- *   identity: { peerId: "alice", name: "Alice" },
+ *   id: { peerId: "alice", name: "Alice" },
  *   transports: [webrtcTransport],
  * })
  *
@@ -149,61 +151,61 @@ type DataChannelContext = {
  * WebRTC connection lifecycle independently.
  */
 declare class WebrtcTransport extends Transport<DataChannelContext> {
-    #private;
-    constructor(options?: WebrtcTransportOptions);
-    /**
-     * Generate a channel for a data channel context.
-     *
-     * Called internally by the `Transport` base class when `addChannel()` is
-     * invoked. Users never call this directly — use `attachDataChannel()`.
-     */
-    protected generate(context: DataChannelContext): GeneratedChannel;
-    /**
-     * Called when the transport starts.
-     *
-     * No-op for WebRTC — channels are added dynamically via
-     * `attachDataChannel()`, not at start time.
-     */
-    onStart(): Promise<void>;
-    /**
-     * Called when the transport stops.
-     *
-     * Detaches all attached data channels and cleans up resources.
-     */
-    onStop(): Promise<void>;
-    /**
-     * Attach a data channel for a remote peer.
-     *
-     * Creates an internal sync channel when the data channel is open
-     * (or waits for the `"open"` event if still connecting). The sync
-     * channel triggers the establishment handshake with the remote peer.
-     *
-     * If a data channel is already attached for this peer, the old one
-     * is detached first.
-     *
-     * @param remotePeerId - The stable peer ID of the remote peer
-     * @param channel - Any object satisfying `DataChannelLike`
-     * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`
-     */
-    attachDataChannel(remotePeerId: string, channel: DataChannelLike): () => void;
-    /**
-     * Detach a data channel for a remote peer.
-     *
-     * Removes the sync channel, cleans up event listeners, and disposes
-     * the reassembler. Does NOT close the data channel — the application
-     * manages the WebRTC connection lifecycle.
-     *
-     * @param remotePeerId - The peer ID to detach
-     */
-    detachDataChannel(remotePeerId: string): void;
-    /**
-     * Check if a data channel is attached for a peer.
-     */
-    hasDataChannel(remotePeerId: string): boolean;
-    /**
-     * Get all peer IDs with attached data channels.
-     */
-    getAttachedPeerIds(): string[];
+  #private;
+  constructor(options?: WebrtcTransportOptions);
+  /**
+   * Generate a channel for a data channel context.
+   *
+   * Called internally by the `Transport` base class when `addChannel()` is
+   * invoked. Users never call this directly — use `attachDataChannel()`.
+   */
+  protected generate(context: DataChannelContext): GeneratedChannel;
+  /**
+   * Called when the transport starts.
+   *
+   * No-op for WebRTC — channels are added dynamically via
+   * `attachDataChannel()`, not at start time.
+   */
+  onStart(): Promise<void>;
+  /**
+   * Called when the transport stops.
+   *
+   * Detaches all attached data channels and cleans up resources.
+   */
+  onStop(): Promise<void>;
+  /**
+   * Attach a data channel for a remote peer.
+   *
+   * Creates an internal sync channel when the data channel is open
+   * (or waits for the `"open"` event if still connecting). The sync
+   * channel triggers the establishment handshake with the remote peer.
+   *
+   * If a data channel is already attached for this peer, the old one
+   * is detached first.
+   *
+   * @param remotePeerId - The stable peer ID of the remote peer
+   * @param channel - Any object satisfying `DataChannelLike`
+   * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`
+   */
+  attachDataChannel(remotePeerId: string, channel: DataChannelLike): () => void;
+  /**
+   * Detach a data channel for a remote peer.
+   *
+   * Removes the sync channel, cleans up event listeners, and disposes
+   * the reassembler. Does NOT close the data channel — the application
+   * manages the WebRTC connection lifecycle.
+   *
+   * @param remotePeerId - The peer ID to detach
+   */
+  detachDataChannel(remotePeerId: string): void;
+  /**
+   * Check if a data channel is attached for a peer.
+   */
+  hasDataChannel(remotePeerId: string): boolean;
+  /**
+   * Get all peer IDs with attached data channels.
+   */
+  getAttachedPeerIds(): string[];
 }
 /**
  * Create a WebRTC transport factory for use with `Exchange`.
@@ -222,11 +224,12 @@ declare class WebrtcTransport extends Transport<DataChannelContext> {
  * import { createWebrtcTransport } from "@kyneta/webrtc-transport"
  *
  * const exchange = new Exchange({
- *   identity: { peerId: "alice", name: "Alice" },
+ *   id: { peerId: "alice", name: "Alice" },
  *   transports: [createWebrtcTransport()],
  * })
  * ```
  */
 declare function createWebrtcTransport(options?: WebrtcTransportOptions): TransportFactory;
+//#endregion
 export { DEFAULT_FRAGMENT_THRESHOLD, type DataChannelLike, WebrtcTransport, type WebrtcTransportOptions, createWebrtcTransport };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/data-channel-like.ts","../src/webrtc-transport.ts"],"mappings":";;;;;;AA6CA;;;;;;;;;;;;;;;;;;;;;;ACJA;UDIiB,eAAA;;;;ACKjB;;;;;AAQC;;;WDDU,UAAA;ECWT;;;;;AAwDF;;;;;;EDtDE,UAAA;EC2GiB;;;;;;;;EDjGjB,IAAA,CAAK,IAAA,EAAM,UAAA;;;;;;;;;;;;EAaX,gBAAA,CAAiB,IAAA,UAAc,QAAA,GAAW,KAAA;ECoHxC;;;;;;;ED3GF,mBAAA,CAAoB,IAAA,UAAc,QAAA,GAAW,KAAA;AAAA;;;AAzD/C;;;;;;;;;AAAA,cCJa,0BAAA;;;;UASI,sBAAA;EDoDK;;;;;;EC7CpB,iBAAA;AAAA;AAhBF;;;AAAA,KA0BK,kBAAA;EACH,YAAA;EACA,OAAA,EAAS,eAAA;AAAA;;;;AAXV;;;;;;;;;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;cAAa,eAAA,SAAwB,SAAA,CAAU,kBAAA;EAAA;cAWjC,OAAA,GAAU,sBAAA;EA0EpB;;;;;;EAAA,UA1DQ,QAAA,CAAS,OAAA,EAAS,kBAAA,GAAqB,gBAAA;EA+JjD;;;AAuHF;;;EA5PQ,OAAA,CAAA,GAAW,OAAA;EA6PP;;;;;EAtPJ,MAAA,CAAA,GAAU,OAAA;;;;;;;;;;;;;;;EAwBhB,iBAAA,CACE,YAAA,UACA,OAAA,EAAS,eAAA;;;;;;;;;;EAyEX,iBAAA,CAAkB,YAAA;;;;EAoBlB,cAAA,CAAe,YAAA;;;;EAOf,kBAAA,CAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;iBAuHc,qBAAA,CACd,OAAA,GAAU,sBAAA,GACT,gBAAA"}

package/dist/index.js CHANGED Viewed

@@ -1,228 +1,255 @@
-// src/webrtc-transport.ts
 import { Transport } from "@kyneta/transport";
-import {
-  decodeBinaryMessages,
-  encodeBinaryAndSend,
-  FragmentReassembler
-} from "@kyneta/wire";
-var DEFAULT_FRAGMENT_THRESHOLD = 200 * 1024;
+import { FragmentReassembler, decodeBinaryMessages, encodeBinaryAndSend } from "@kyneta/wire";
+//#region src/webrtc-transport.ts
+/**
+* Default fragment threshold in bytes.
+*
+* SCTP (the underlying transport for WebRTC data channels) has a message
+* size limit of approximately 256KB. 200KB provides a safe margin.
+*
+* This differs from the WebSocket transport's 100KB default, which
+* targets AWS API Gateway's 128KB limit. WebRTC has no such gateway.
+*/
+const DEFAULT_FRAGMENT_THRESHOLD = 200 * 1024;
+/**
+* WebRTC data channel transport for @kyneta/exchange.
+*
+* Follows a "Bring Your Own Data Channel" (BYODC) design — the application
+* manages WebRTC connections and attaches data channels to this transport
+* for kyneta document synchronization.
+*
+* Uses binary CBOR encoding with transport-level fragmentation via
+* `@kyneta/wire` — the same pipeline as the WebSocket transport.
+*
+* ## Usage
+*
+* ```typescript
+* import { Exchange } from "@kyneta/exchange"
+* import { createWebrtcTransport } from "@kyneta/webrtc-transport"
+*
+* const webrtcTransport = createWebrtcTransport()
+*
+* const exchange = new Exchange({
+*   id: { peerId: "alice", name: "Alice" },
+*   transports: [webrtcTransport],
+* })
+*
+* // When a WebRTC connection is established:
+* const cleanup = transport.attachDataChannel(remotePeerId, dataChannel)
+*
+* // When done:
+* cleanup() // or transport.detachDataChannel(remotePeerId)
+* ```
+*
+* ## Ownership
+*
+* The transport does NOT own the data channel. `detachDataChannel()`
+* removes the sync channel and event listeners but does not close the
+* data channel or the peer connection. The application manages the
+* WebRTC connection lifecycle independently.
+*/
 var WebrtcTransport = class extends Transport {
-  /**
-   * Map of remotePeerId → attached channel tracking.
-   */
-  #attachedChannels = /* @__PURE__ */ new Map();
-  /**
-   * Fragment threshold in bytes.
-   */
-  #fragmentThreshold;
-  constructor(options) {
-    super({ transportType: "webrtc-datachannel" });
-    this.#fragmentThreshold = options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD;
-  }
-  // ==========================================================================
-  // Transport abstract method implementations
-  // ==========================================================================
-  /**
-   * Generate a channel for a data channel context.
-   *
-   * Called internally by the `Transport` base class when `addChannel()` is
-   * invoked. Users never call this directly — use `attachDataChannel()`.
-   */
-  generate(context) {
-    const { channel } = context;
-    return {
-      transportType: this.transportType,
-      send: (msg) => {
-        if (channel.readyState !== "open") {
-          return;
-        }
-        encodeBinaryAndSend(
-          msg,
-          this.#fragmentThreshold,
-          (data) => channel.send(data)
-        );
-      },
-      stop: () => {
-      }
-    };
-  }
-  /**
-   * Called when the transport starts.
-   *
-   * No-op for WebRTC — channels are added dynamically via
-   * `attachDataChannel()`, not at start time.
-   */
-  async onStart() {
-  }
-  /**
-   * Called when the transport stops.
-   *
-   * Detaches all attached data channels and cleans up resources.
-   */
-  async onStop() {
-    for (const remotePeerId of [...this.#attachedChannels.keys()]) {
-      this.detachDataChannel(remotePeerId);
-    }
-  }
-  // ==========================================================================
-  // Public API — data channel management
-  // ==========================================================================
-  /**
-   * Attach a data channel for a remote peer.
-   *
-   * Creates an internal sync channel when the data channel is open
-   * (or waits for the `"open"` event if still connecting). The sync
-   * channel triggers the establishment handshake with the remote peer.
-   *
-   * If a data channel is already attached for this peer, the old one
-   * is detached first.
-   *
-   * @param remotePeerId - The stable peer ID of the remote peer
-   * @param channel - Any object satisfying `DataChannelLike`
-   * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`
-   */
-  attachDataChannel(remotePeerId, channel) {
-    if (this.#attachedChannels.has(remotePeerId)) {
-      this.detachDataChannel(remotePeerId);
-    }
-    channel.binaryType = "arraybuffer";
-    const reassembler = new FragmentReassembler({ timeoutMs: 1e4 });
-    const onOpen = () => {
-      this.#createSyncChannel(remotePeerId);
-    };
-    const onClose = () => {
-      this.#removeSyncChannel(remotePeerId);
-    };
-    const onError = () => {
-      this.#removeSyncChannel(remotePeerId);
-    };
-    const onMessage = (event) => {
-      this.#handleMessage(remotePeerId, event);
-    };
-    const cleanup = () => {
-      channel.removeEventListener("open", onOpen);
-      channel.removeEventListener("close", onClose);
-      channel.removeEventListener("error", onError);
-      channel.removeEventListener("message", onMessage);
-    };
-    channel.addEventListener("open", onOpen);
-    channel.addEventListener("close", onClose);
-    channel.addEventListener("error", onError);
-    channel.addEventListener("message", onMessage);
-    const attached = {
-      remotePeerId,
-      channel,
-      channelId: null,
-      reassembler,
-      cleanup
-    };
-    this.#attachedChannels.set(remotePeerId, attached);
-    if (channel.readyState === "open") {
-      this.#createSyncChannel(remotePeerId);
-    }
-    return () => this.detachDataChannel(remotePeerId);
-  }
-  /**
-   * Detach a data channel for a remote peer.
-   *
-   * Removes the sync channel, cleans up event listeners, and disposes
-   * the reassembler. Does NOT close the data channel — the application
-   * manages the WebRTC connection lifecycle.
-   *
-   * @param remotePeerId - The peer ID to detach
-   */
-  detachDataChannel(remotePeerId) {
-    const attached = this.#attachedChannels.get(remotePeerId);
-    if (!attached) return;
-    this.#removeSyncChannel(remotePeerId);
-    attached.reassembler.dispose();
-    attached.cleanup();
-    this.#attachedChannels.delete(remotePeerId);
-  }
-  /**
-   * Check if a data channel is attached for a peer.
-   */
-  hasDataChannel(remotePeerId) {
-    return this.#attachedChannels.has(remotePeerId);
-  }
-  /**
-   * Get all peer IDs with attached data channels.
-   */
-  getAttachedPeerIds() {
-    return [...this.#attachedChannels.keys()];
-  }
-  // ==========================================================================
-  // Internal — sync channel lifecycle
-  // ==========================================================================
-  /**
-   * Create an internal sync channel for an attached data channel.
-   *
-   * Called when the data channel's `"open"` event fires (or immediately
-   * if already open on attach). The sync channel is registered with the
-   * Transport base class, which triggers the establishment handshake.
-   */
-  #createSyncChannel(remotePeerId) {
-    const attached = this.#attachedChannels.get(remotePeerId);
-    if (!attached) return;
-    if (attached.channelId !== null) return;
-    const syncChannel = this.addChannel({
-      remotePeerId,
-      channel: attached.channel
-    });
-    attached.channelId = syncChannel.channelId;
-    this.establishChannel(syncChannel.channelId);
-  }
-  /**
-   * Remove the internal sync channel for a peer.
-   */
-  #removeSyncChannel(remotePeerId) {
-    const attached = this.#attachedChannels.get(remotePeerId);
-    if (!attached || attached.channelId === null) return;
-    this.removeChannel(attached.channelId);
-    attached.channelId = null;
-  }
-  // ==========================================================================
-  // Internal — message handling
-  // ==========================================================================
-  /**
-   * Handle an incoming message from a data channel.
-   *
-   * Extracts binary data from the event, feeding both `ArrayBuffer`
-   * (native RTCDataChannel with binaryType "arraybuffer") and
-   * `Uint8Array` (simple-peer and other wrappers) into the shared
-   * decode pipeline.
-   */
-  #handleMessage(remotePeerId, event) {
-    const attached = this.#attachedChannels.get(remotePeerId);
-    if (!attached || attached.channelId === null) return;
-    const syncChannel = this.channels.get(attached.channelId);
-    if (!syncChannel) return;
-    const raw = event.data;
-    const bytes = raw instanceof ArrayBuffer ? new Uint8Array(raw) : raw instanceof Uint8Array ? raw : null;
-    if (!bytes) {
-      return;
-    }
-    try {
-      const messages = decodeBinaryMessages(bytes, attached.reassembler);
-      if (messages) {
-        for (const msg of messages) {
-          syncChannel.onReceive(msg);
-        }
-      }
-    } catch (error) {
-      console.error(
-        `[webrtc-transport] Failed to decode message from peer ${remotePeerId}:`,
-        error
-      );
-    }
-  }
+	/**
+	* Map of remotePeerId → attached channel tracking.
+	*/
+	#attachedChannels = /* @__PURE__ */ new Map();
+	/**
+	* Fragment threshold in bytes.
+	*/
+	#fragmentThreshold;
+	constructor(options) {
+		super({ transportType: "webrtc-datachannel" });
+		this.#fragmentThreshold = options?.fragmentThreshold ?? 204800;
+	}
+	/**
+	* Generate a channel for a data channel context.
+	*
+	* Called internally by the `Transport` base class when `addChannel()` is
+	* invoked. Users never call this directly — use `attachDataChannel()`.
+	*/
+	generate(context) {
+		const { channel } = context;
+		return {
+			transportType: this.transportType,
+			send: (msg) => {
+				if (channel.readyState !== "open") return;
+				encodeBinaryAndSend(msg, this.#fragmentThreshold, (data) => channel.send(data));
+			},
+			stop: () => {}
+		};
+	}
+	/**
+	* Called when the transport starts.
+	*
+	* No-op for WebRTC — channels are added dynamically via
+	* `attachDataChannel()`, not at start time.
+	*/
+	async onStart() {}
+	/**
+	* Called when the transport stops.
+	*
+	* Detaches all attached data channels and cleans up resources.
+	*/
+	async onStop() {
+		for (const remotePeerId of [...this.#attachedChannels.keys()]) this.detachDataChannel(remotePeerId);
+	}
+	/**
+	* Attach a data channel for a remote peer.
+	*
+	* Creates an internal sync channel when the data channel is open
+	* (or waits for the `"open"` event if still connecting). The sync
+	* channel triggers the establishment handshake with the remote peer.
+	*
+	* If a data channel is already attached for this peer, the old one
+	* is detached first.
+	*
+	* @param remotePeerId - The stable peer ID of the remote peer
+	* @param channel - Any object satisfying `DataChannelLike`
+	* @returns A cleanup function that calls `detachDataChannel(remotePeerId)`
+	*/
+	attachDataChannel(remotePeerId, channel) {
+		if (this.#attachedChannels.has(remotePeerId)) this.detachDataChannel(remotePeerId);
+		channel.binaryType = "arraybuffer";
+		const reassembler = new FragmentReassembler({ timeoutMs: 1e4 });
+		const onOpen = () => {
+			this.#createSyncChannel(remotePeerId);
+		};
+		const onClose = () => {
+			this.#removeSyncChannel(remotePeerId);
+		};
+		const onError = () => {
+			this.#removeSyncChannel(remotePeerId);
+		};
+		const onMessage = (event) => {
+			this.#handleMessage(remotePeerId, event);
+		};
+		const cleanup = () => {
+			channel.removeEventListener("open", onOpen);
+			channel.removeEventListener("close", onClose);
+			channel.removeEventListener("error", onError);
+			channel.removeEventListener("message", onMessage);
+		};
+		channel.addEventListener("open", onOpen);
+		channel.addEventListener("close", onClose);
+		channel.addEventListener("error", onError);
+		channel.addEventListener("message", onMessage);
+		const attached = {
+			remotePeerId,
+			channel,
+			channelId: null,
+			reassembler,
+			cleanup
+		};
+		this.#attachedChannels.set(remotePeerId, attached);
+		if (channel.readyState === "open") this.#createSyncChannel(remotePeerId);
+		return () => this.detachDataChannel(remotePeerId);
+	}
+	/**
+	* Detach a data channel for a remote peer.
+	*
+	* Removes the sync channel, cleans up event listeners, and disposes
+	* the reassembler. Does NOT close the data channel — the application
+	* manages the WebRTC connection lifecycle.
+	*
+	* @param remotePeerId - The peer ID to detach
+	*/
+	detachDataChannel(remotePeerId) {
+		const attached = this.#attachedChannels.get(remotePeerId);
+		if (!attached) return;
+		this.#removeSyncChannel(remotePeerId);
+		attached.reassembler.dispose();
+		attached.cleanup();
+		this.#attachedChannels.delete(remotePeerId);
+	}
+	/**
+	* Check if a data channel is attached for a peer.
+	*/
+	hasDataChannel(remotePeerId) {
+		return this.#attachedChannels.has(remotePeerId);
+	}
+	/**
+	* Get all peer IDs with attached data channels.
+	*/
+	getAttachedPeerIds() {
+		return [...this.#attachedChannels.keys()];
+	}
+	/**
+	* Create an internal sync channel for an attached data channel.
+	*
+	* Called when the data channel's `"open"` event fires (or immediately
+	* if already open on attach). The sync channel is registered with the
+	* Transport base class, which triggers the establishment handshake.
+	*/
+	#createSyncChannel(remotePeerId) {
+		const attached = this.#attachedChannels.get(remotePeerId);
+		if (!attached) return;
+		if (attached.channelId !== null) return;
+		const syncChannel = this.addChannel({
+			remotePeerId,
+			channel: attached.channel
+		});
+		attached.channelId = syncChannel.channelId;
+		this.establishChannel(syncChannel.channelId);
+	}
+	/**
+	* Remove the internal sync channel for a peer.
+	*/
+	#removeSyncChannel(remotePeerId) {
+		const attached = this.#attachedChannels.get(remotePeerId);
+		if (!attached || attached.channelId === null) return;
+		this.removeChannel(attached.channelId);
+		attached.channelId = null;
+	}
+	/**
+	* Handle an incoming message from a data channel.
+	*
+	* Extracts binary data from the event, feeding both `ArrayBuffer`
+	* (native RTCDataChannel with binaryType "arraybuffer") and
+	* `Uint8Array` (simple-peer and other wrappers) into the shared
+	* decode pipeline.
+	*/
+	#handleMessage(remotePeerId, event) {
+		const attached = this.#attachedChannels.get(remotePeerId);
+		if (!attached || attached.channelId === null) return;
+		const syncChannel = this.channels.get(attached.channelId);
+		if (!syncChannel) return;
+		const raw = event.data;
+		const bytes = raw instanceof ArrayBuffer ? new Uint8Array(raw) : raw instanceof Uint8Array ? raw : null;
+		if (!bytes) return;
+		try {
+			const messages = decodeBinaryMessages(bytes, attached.reassembler);
+			if (messages) for (const msg of messages) syncChannel.onReceive(msg);
+		} catch (error) {
+			console.error(`[webrtc-transport] Failed to decode message from peer ${remotePeerId}:`, error);
+		}
+	}
 };
+/**
+* Create a WebRTC transport factory for use with `Exchange`.
+*
+* Returns a `TransportFactory` — pass directly to
+* `Exchange({ transports: [...] })`. The returned transport instance
+* exposes `attachDataChannel()` / `detachDataChannel()` for BYODC
+* data channel management.
+*
+* To access the transport instance after creation, use
+* `exchange.getTransport("webrtc-datachannel")`.
+*
+* @example
+* ```typescript
+* import { Exchange } from "@kyneta/exchange"
+* import { createWebrtcTransport } from "@kyneta/webrtc-transport"
+*
+* const exchange = new Exchange({
+*   id: { peerId: "alice", name: "Alice" },
+*   transports: [createWebrtcTransport()],
+* })
+* ```
+*/
 function createWebrtcTransport(options) {
-  return () => new WebrtcTransport(options);
+	return () => new WebrtcTransport(options);
 }
-export {
-  DEFAULT_FRAGMENT_THRESHOLD,
-  WebrtcTransport,
-  createWebrtcTransport
-};
+//#endregion
+export { DEFAULT_FRAGMENT_THRESHOLD, WebrtcTransport, createWebrtcTransport };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/webrtc-transport.ts"],"sourcesContent":["// webrtc-transport — BYODC WebRTC data channel transport for @kyneta/exchange.\n//\n// \"Bring Your Own Data Channel\" design: the application manages WebRTC\n// connections (signaling, ICE, media streams). This transport attaches\n// to already-established data channels for kyneta document sync.\n//\n// Uses the shared binary pipeline from @kyneta/wire (same as WebSocket):\n// encodeBinaryAndSend — outbound: encode → fragment → sendFn\n// decodeBinaryMessages — inbound: reassemble → decode → ChannelMsg[]\n//\n// The transport accepts any object satisfying `DataChannelLike` — a\n// 5-member interface that native RTCDataChannel satisfies structurally\n// and that libraries like simple-peer can conform to via a trivial bridge.\n\nimport type {\n ChannelId,\n ChannelMsg,\n GeneratedChannel,\n TransportFactory,\n} from \"@kyneta/transport\"\nimport { Transport } from \"@kyneta/transport\"\nimport {\n decodeBinaryMessages,\n encodeBinaryAndSend,\n FragmentReassembler,\n} from \"@kyneta/wire\"\nimport type { DataChannelLike } from \"./data-channel-like.js\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/*\n Default fragment threshold in bytes.\n \n SCTP (the underlying transport for WebRTC data channels) has a message\n * size limit of approximately 256KB. 200KB provides a safe margin.\n \n This differs from the WebSocket transport's 100KB default, which\n * targets AWS API Gateway's 128KB limit. WebRTC has no such gateway.\n /\nexport const DEFAULT_FRAGMENT_THRESHOLD = 200 1024\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/*\n Configuration options for the WebRTC transport.\n /\nexport interface WebrtcTransportOptions {\n /\n Fragment threshold in bytes. Messages larger than this are fragmented\n * for SCTP compatibility. Set to 0 to disable fragmentation (not recommended).\n \n @default 204800 (200KB)\n /\n fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\n/\n Context for each attached data channel — stored per remotePeerId.\n /\ntype DataChannelContext = {\n remotePeerId: string\n channel: DataChannelLike\n}\n\n/\n Internal tracking for an attached data channel.\n /\ntype AttachedChannel = {\n remotePeerId: string\n channel: DataChannelLike\n channelId: ChannelId \| null\n reassembler: FragmentReassembler\n cleanup: () => void\n}\n\n// ---------------------------------------------------------------------------\n// WebrtcTransport\n// ---------------------------------------------------------------------------\n\n/\n WebRTC data channel transport for @kyneta/exchange.\n \n Follows a \"Bring Your Own Data Channel\" (BYODC) design — the application\n * manages WebRTC connections and attaches data channels to this transport\n * for kyneta document synchronization.\n \n Uses binary CBOR encoding with transport-level fragmentation via\n * `@kyneta/wire` — the same pipeline as the WebSocket transport.\n \n ## Usage\n \n ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n \n const webrtcTransport = createWebrtcTransport()\n \n const exchange = new Exchange({\n * identity: { peerId: \"alice\", name: \"Alice\" },\n * transports: [webrtcTransport],\n * })\n \n // When a WebRTC connection is established:\n * const cleanup = transport.attachDataChannel(remotePeerId, dataChannel)\n \n // When done:\n * cleanup() // or transport.detachDataChannel(remotePeerId)\n * ```\n \n ## Ownership\n \n The transport does NOT own the data channel. `detachDataChannel()`\n * removes the sync channel and event listeners but does not close the\n * data channel or the peer connection. The application manages the\n * WebRTC connection lifecycle independently.\n /\nexport class WebrtcTransport extends Transport<DataChannelContext> {\n /\n Map of remotePeerId → attached channel tracking.\n /\n readonly #attachedChannels = new Map<string, AttachedChannel>()\n\n /\n Fragment threshold in bytes.\n /\n readonly #fragmentThreshold: number\n\n constructor(options?: WebrtcTransportOptions) {\n super({ transportType: \"webrtc-datachannel\" })\n this.#fragmentThreshold =\n options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n }\n\n // ==========================================================================\n // Transport abstract method implementations\n // ==========================================================================\n\n /\n Generate a channel for a data channel context.\n \n Called internally by the `Transport` base class when `addChannel()` is\n * invoked. Users never call this directly — use `attachDataChannel()`.\n /\n protected generate(context: DataChannelContext): GeneratedChannel {\n const { channel } = context\n\n return {\n transportType: this.transportType,\n send: (msg: ChannelMsg) => {\n if (channel.readyState !== \"open\") {\n return\n }\n encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>\n channel.send(data),\n )\n },\n stop: () => {\n // Cleanup is handled by detachDataChannel().\n // This callback fires when the internal channel is removed.\n },\n }\n }\n\n /\n Called when the transport starts.\n \n No-op for WebRTC — channels are added dynamically via\n * `attachDataChannel()`, not at start time.\n /\n async onStart(): Promise<void> {}\n\n /\n Called when the transport stops.\n \n Detaches all attached data channels and cleans up resources.\n /\n async onStop(): Promise<void> {\n for (const remotePeerId of [...this.#attachedChannels.keys()]) {\n this.detachDataChannel(remotePeerId)\n }\n }\n\n // ==========================================================================\n // Public API — data channel management\n // ==========================================================================\n\n /\n Attach a data channel for a remote peer.\n \n Creates an internal sync channel when the data channel is open\n * (or waits for the `\"open\"` event if still connecting). The sync\n * channel triggers the establishment handshake with the remote peer.\n \n If a data channel is already attached for this peer, the old one\n * is detached first.\n \n @param remotePeerId - The stable peer ID of the remote peer\n * @param channel - Any object satisfying `DataChannelLike`\n * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`\n /\n attachDataChannel(\n remotePeerId: string,\n channel: DataChannelLike,\n ): () => void {\n // Detach existing channel for this peer if any\n if (this.#attachedChannels.has(remotePeerId)) {\n this.detachDataChannel(remotePeerId)\n }\n\n // Best-effort: request arraybuffer mode for incoming data.\n // The message handler doesn't depend on this — it accepts both\n // ArrayBuffer and Uint8Array regardless.\n channel.binaryType = \"arraybuffer\"\n\n // Create reassembler for this data channel\n const reassembler = new FragmentReassembler({ timeoutMs: 10_000 })\n\n // Event handlers — stored as named functions for removeEventListener\n const onOpen = () => {\n this.#createSyncChannel(remotePeerId)\n }\n\n const onClose = () => {\n this.#removeSyncChannel(remotePeerId)\n }\n\n const onError = () => {\n this.#removeSyncChannel(remotePeerId)\n }\n\n const onMessage = (event: any) => {\n this.#handleMessage(remotePeerId, event)\n }\n\n // Cleanup function to remove all event listeners\n const cleanup = () => {\n channel.removeEventListener(\"open\", onOpen)\n channel.removeEventListener(\"close\", onClose)\n channel.removeEventListener(\"error\", onError)\n channel.removeEventListener(\"message\", onMessage)\n }\n\n // Register event listeners\n channel.addEventListener(\"open\", onOpen)\n channel.addEventListener(\"close\", onClose)\n channel.addEventListener(\"error\", onError)\n channel.addEventListener(\"message\", onMessage)\n\n // Track the attached channel\n const attached: AttachedChannel = {\n remotePeerId,\n channel,\n channelId: null,\n reassembler,\n cleanup,\n }\n this.#attachedChannels.set(remotePeerId, attached)\n\n // If the channel is already open, create the sync channel immediately\n if (channel.readyState === \"open\") {\n this.#createSyncChannel(remotePeerId)\n }\n\n return () => this.detachDataChannel(remotePeerId)\n }\n\n /\n Detach a data channel for a remote peer.\n \n Removes the sync channel, cleans up event listeners, and disposes\n * the reassembler. Does NOT close the data channel — the application\n * manages the WebRTC connection lifecycle.\n \n @param remotePeerId - The peer ID to detach\n /\n detachDataChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached) return\n\n // Remove the sync channel if it exists\n this.#removeSyncChannel(remotePeerId)\n\n // Dispose the reassembler to clean up timers\n attached.reassembler.dispose()\n\n // Remove event listeners from the data channel\n attached.cleanup()\n\n // Remove from tracking\n this.#attachedChannels.delete(remotePeerId)\n }\n\n /\n Check if a data channel is attached for a peer.\n /\n hasDataChannel(remotePeerId: string): boolean {\n return this.#attachedChannels.has(remotePeerId)\n }\n\n /\n Get all peer IDs with attached data channels.\n /\n getAttachedPeerIds(): string[] {\n return [...this.#attachedChannels.keys()]\n }\n\n // ==========================================================================\n // Internal — sync channel lifecycle\n // ==========================================================================\n\n /\n Create an internal sync channel for an attached data channel.\n \n Called when the data channel's `\"open\"` event fires (or immediately\n * if already open on attach). The sync channel is registered with the\n * Transport base class, which triggers the establishment handshake.\n /\n #createSyncChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached) return\n\n // Don't create if already exists\n if (attached.channelId !== null) return\n\n // addChannel() creates and registers the sync channel\n const syncChannel = this.addChannel({\n remotePeerId,\n channel: attached.channel,\n })\n attached.channelId = syncChannel.channelId\n\n // Start the establishment handshake\n this.establishChannel(syncChannel.channelId)\n }\n\n /\n Remove the internal sync channel for a peer.\n /\n #removeSyncChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached \|\| attached.channelId === null) return\n\n this.removeChannel(attached.channelId)\n attached.channelId = null\n }\n\n // ==========================================================================\n // Internal — message handling\n // ==========================================================================\n\n /\n Handle an incoming message from a data channel.\n \n Extracts binary data from the event, feeding both `ArrayBuffer`\n * (native RTCDataChannel with binaryType \"arraybuffer\") and\n * `Uint8Array` (simple-peer and other wrappers) into the shared\n * decode pipeline.\n /\n #handleMessage(remotePeerId: string, event: any): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached \|\| attached.channelId === null) return\n\n const syncChannel = this.channels.get(attached.channelId)\n if (!syncChannel) return\n\n // Extract bytes — robust to both ArrayBuffer and Uint8Array\n const raw = event.data\n const bytes =\n raw instanceof ArrayBuffer\n ? new Uint8Array(raw)\n : raw instanceof Uint8Array\n ? raw\n : null\n\n if (!bytes) {\n // Unexpected data type (e.g. string) — ignore silently\n return\n }\n\n try {\n const messages = decodeBinaryMessages(bytes, attached.reassembler)\n if (messages) {\n for (const msg of messages) {\n syncChannel.onReceive(msg)\n }\n }\n } catch (error) {\n console.error(\n `[webrtc-transport] Failed to decode message from peer ${remotePeerId}:`,\n error,\n )\n }\n }\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\n/\n Create a WebRTC transport factory for use with `Exchange`.\n \n Returns a `TransportFactory` — pass directly to\n * `Exchange({ transports: [...] })`. The returned transport instance\n * exposes `attachDataChannel()` / `detachDataChannel()` for BYODC\n * data channel management.\n \n To access the transport instance after creation, use\n * `exchange.getTransport(\"webrtc-datachannel\")`.\n \n @example\n * ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n \n const exchange = new Exchange({\n * identity: { peerId: \"alice\", name: \"Alice\" },\n * transports: [createWebrtcTransport()],\n * })\n * ```\n */\nexport function createWebrtcTransport(\n options?: WebrtcTransportOptions,\n): TransportFactory {\n return () => new WebrtcTransport(options)\n}\n"],"mappings":"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","names":[]}
1	+ {"version":3,"file":"index.js","names":["#attachedChannels","#fragmentThreshold","#createSyncChannel","#removeSyncChannel","#handleMessage"],"sources":["../src/webrtc-transport.ts"],"sourcesContent":["// webrtc-transport — BYODC WebRTC data channel transport for @kyneta/exchange.\n//\n// \"Bring Your Own Data Channel\" design: the application manages WebRTC\n// connections (signaling, ICE, media streams). This transport attaches\n// to already-established data channels for kyneta document sync.\n//\n// Uses the shared binary pipeline from @kyneta/wire (same as WebSocket):\n// encodeBinaryAndSend — outbound: encode → fragment → sendFn\n// decodeBinaryMessages — inbound: reassemble → decode → ChannelMsg[]\n//\n// The transport accepts any object satisfying `DataChannelLike` — a\n// 5-member interface that native RTCDataChannel satisfies structurally\n// and that libraries like simple-peer can conform to via a trivial bridge.\n\nimport type {\n ChannelId,\n ChannelMsg,\n GeneratedChannel,\n TransportFactory,\n} from \"@kyneta/transport\"\nimport { Transport } from \"@kyneta/transport\"\nimport {\n decodeBinaryMessages,\n encodeBinaryAndSend,\n FragmentReassembler,\n} from \"@kyneta/wire\"\nimport type { DataChannelLike } from \"./data-channel-like.js\"\n\n// ---------------------------------------------------------------------------\n// Constants\n// ---------------------------------------------------------------------------\n\n/*\n Default fragment threshold in bytes.\n \n SCTP (the underlying transport for WebRTC data channels) has a message\n * size limit of approximately 256KB. 200KB provides a safe margin.\n \n This differs from the WebSocket transport's 100KB default, which\n * targets AWS API Gateway's 128KB limit. WebRTC has no such gateway.\n /\nexport const DEFAULT_FRAGMENT_THRESHOLD = 200 1024\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\n/*\n Configuration options for the WebRTC transport.\n /\nexport interface WebrtcTransportOptions {\n /\n Fragment threshold in bytes. Messages larger than this are fragmented\n * for SCTP compatibility. Set to 0 to disable fragmentation (not recommended).\n \n @default 204800 (200KB)\n /\n fragmentThreshold?: number\n}\n\n// ---------------------------------------------------------------------------\n// Internal types\n// ---------------------------------------------------------------------------\n\n/\n Context for each attached data channel — stored per remotePeerId.\n /\ntype DataChannelContext = {\n remotePeerId: string\n channel: DataChannelLike\n}\n\n/\n Internal tracking for an attached data channel.\n /\ntype AttachedChannel = {\n remotePeerId: string\n channel: DataChannelLike\n channelId: ChannelId \| null\n reassembler: FragmentReassembler\n cleanup: () => void\n}\n\n// ---------------------------------------------------------------------------\n// WebrtcTransport\n// ---------------------------------------------------------------------------\n\n/\n WebRTC data channel transport for @kyneta/exchange.\n \n Follows a \"Bring Your Own Data Channel\" (BYODC) design — the application\n * manages WebRTC connections and attaches data channels to this transport\n * for kyneta document synchronization.\n \n Uses binary CBOR encoding with transport-level fragmentation via\n * `@kyneta/wire` — the same pipeline as the WebSocket transport.\n \n ## Usage\n \n ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n \n const webrtcTransport = createWebrtcTransport()\n \n const exchange = new Exchange({\n * id: { peerId: \"alice\", name: \"Alice\" },\n * transports: [webrtcTransport],\n * })\n \n // When a WebRTC connection is established:\n * const cleanup = transport.attachDataChannel(remotePeerId, dataChannel)\n \n // When done:\n * cleanup() // or transport.detachDataChannel(remotePeerId)\n * ```\n \n ## Ownership\n \n The transport does NOT own the data channel. `detachDataChannel()`\n * removes the sync channel and event listeners but does not close the\n * data channel or the peer connection. The application manages the\n * WebRTC connection lifecycle independently.\n /\nexport class WebrtcTransport extends Transport<DataChannelContext> {\n /\n Map of remotePeerId → attached channel tracking.\n /\n readonly #attachedChannels = new Map<string, AttachedChannel>()\n\n /\n Fragment threshold in bytes.\n /\n readonly #fragmentThreshold: number\n\n constructor(options?: WebrtcTransportOptions) {\n super({ transportType: \"webrtc-datachannel\" })\n this.#fragmentThreshold =\n options?.fragmentThreshold ?? DEFAULT_FRAGMENT_THRESHOLD\n }\n\n // ==========================================================================\n // Transport abstract method implementations\n // ==========================================================================\n\n /\n Generate a channel for a data channel context.\n \n Called internally by the `Transport` base class when `addChannel()` is\n * invoked. Users never call this directly — use `attachDataChannel()`.\n /\n protected generate(context: DataChannelContext): GeneratedChannel {\n const { channel } = context\n\n return {\n transportType: this.transportType,\n send: (msg: ChannelMsg) => {\n if (channel.readyState !== \"open\") {\n return\n }\n encodeBinaryAndSend(msg, this.#fragmentThreshold, data =>\n channel.send(data),\n )\n },\n stop: () => {\n // Cleanup is handled by detachDataChannel().\n // This callback fires when the internal channel is removed.\n },\n }\n }\n\n /\n Called when the transport starts.\n \n No-op for WebRTC — channels are added dynamically via\n * `attachDataChannel()`, not at start time.\n /\n async onStart(): Promise<void> {}\n\n /\n Called when the transport stops.\n \n Detaches all attached data channels and cleans up resources.\n /\n async onStop(): Promise<void> {\n for (const remotePeerId of [...this.#attachedChannels.keys()]) {\n this.detachDataChannel(remotePeerId)\n }\n }\n\n // ==========================================================================\n // Public API — data channel management\n // ==========================================================================\n\n /\n Attach a data channel for a remote peer.\n \n Creates an internal sync channel when the data channel is open\n * (or waits for the `\"open\"` event if still connecting). The sync\n * channel triggers the establishment handshake with the remote peer.\n \n If a data channel is already attached for this peer, the old one\n * is detached first.\n \n @param remotePeerId - The stable peer ID of the remote peer\n * @param channel - Any object satisfying `DataChannelLike`\n * @returns A cleanup function that calls `detachDataChannel(remotePeerId)`\n /\n attachDataChannel(\n remotePeerId: string,\n channel: DataChannelLike,\n ): () => void {\n // Detach existing channel for this peer if any\n if (this.#attachedChannels.has(remotePeerId)) {\n this.detachDataChannel(remotePeerId)\n }\n\n // Best-effort: request arraybuffer mode for incoming data.\n // The message handler doesn't depend on this — it accepts both\n // ArrayBuffer and Uint8Array regardless.\n channel.binaryType = \"arraybuffer\"\n\n // Create reassembler for this data channel\n const reassembler = new FragmentReassembler({ timeoutMs: 10_000 })\n\n // Event handlers — stored as named functions for removeEventListener\n const onOpen = () => {\n this.#createSyncChannel(remotePeerId)\n }\n\n const onClose = () => {\n this.#removeSyncChannel(remotePeerId)\n }\n\n const onError = () => {\n this.#removeSyncChannel(remotePeerId)\n }\n\n const onMessage = (event: any) => {\n this.#handleMessage(remotePeerId, event)\n }\n\n // Cleanup function to remove all event listeners\n const cleanup = () => {\n channel.removeEventListener(\"open\", onOpen)\n channel.removeEventListener(\"close\", onClose)\n channel.removeEventListener(\"error\", onError)\n channel.removeEventListener(\"message\", onMessage)\n }\n\n // Register event listeners\n channel.addEventListener(\"open\", onOpen)\n channel.addEventListener(\"close\", onClose)\n channel.addEventListener(\"error\", onError)\n channel.addEventListener(\"message\", onMessage)\n\n // Track the attached channel\n const attached: AttachedChannel = {\n remotePeerId,\n channel,\n channelId: null,\n reassembler,\n cleanup,\n }\n this.#attachedChannels.set(remotePeerId, attached)\n\n // If the channel is already open, create the sync channel immediately\n if (channel.readyState === \"open\") {\n this.#createSyncChannel(remotePeerId)\n }\n\n return () => this.detachDataChannel(remotePeerId)\n }\n\n /\n Detach a data channel for a remote peer.\n \n Removes the sync channel, cleans up event listeners, and disposes\n * the reassembler. Does NOT close the data channel — the application\n * manages the WebRTC connection lifecycle.\n \n @param remotePeerId - The peer ID to detach\n /\n detachDataChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached) return\n\n // Remove the sync channel if it exists\n this.#removeSyncChannel(remotePeerId)\n\n // Dispose the reassembler to clean up timers\n attached.reassembler.dispose()\n\n // Remove event listeners from the data channel\n attached.cleanup()\n\n // Remove from tracking\n this.#attachedChannels.delete(remotePeerId)\n }\n\n /\n Check if a data channel is attached for a peer.\n /\n hasDataChannel(remotePeerId: string): boolean {\n return this.#attachedChannels.has(remotePeerId)\n }\n\n /\n Get all peer IDs with attached data channels.\n /\n getAttachedPeerIds(): string[] {\n return [...this.#attachedChannels.keys()]\n }\n\n // ==========================================================================\n // Internal — sync channel lifecycle\n // ==========================================================================\n\n /\n Create an internal sync channel for an attached data channel.\n \n Called when the data channel's `\"open\"` event fires (or immediately\n * if already open on attach). The sync channel is registered with the\n * Transport base class, which triggers the establishment handshake.\n /\n #createSyncChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached) return\n\n // Don't create if already exists\n if (attached.channelId !== null) return\n\n // addChannel() creates and registers the sync channel\n const syncChannel = this.addChannel({\n remotePeerId,\n channel: attached.channel,\n })\n attached.channelId = syncChannel.channelId\n\n // Start the establishment handshake\n this.establishChannel(syncChannel.channelId)\n }\n\n /\n Remove the internal sync channel for a peer.\n /\n #removeSyncChannel(remotePeerId: string): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached \|\| attached.channelId === null) return\n\n this.removeChannel(attached.channelId)\n attached.channelId = null\n }\n\n // ==========================================================================\n // Internal — message handling\n // ==========================================================================\n\n /\n Handle an incoming message from a data channel.\n \n Extracts binary data from the event, feeding both `ArrayBuffer`\n * (native RTCDataChannel with binaryType \"arraybuffer\") and\n * `Uint8Array` (simple-peer and other wrappers) into the shared\n * decode pipeline.\n /\n #handleMessage(remotePeerId: string, event: any): void {\n const attached = this.#attachedChannels.get(remotePeerId)\n if (!attached \|\| attached.channelId === null) return\n\n const syncChannel = this.channels.get(attached.channelId)\n if (!syncChannel) return\n\n // Extract bytes — robust to both ArrayBuffer and Uint8Array\n const raw = event.data\n const bytes =\n raw instanceof ArrayBuffer\n ? new Uint8Array(raw)\n : raw instanceof Uint8Array\n ? raw\n : null\n\n if (!bytes) {\n // Unexpected data type (e.g. string) — ignore silently\n return\n }\n\n try {\n const messages = decodeBinaryMessages(bytes, attached.reassembler)\n if (messages) {\n for (const msg of messages) {\n syncChannel.onReceive(msg)\n }\n }\n } catch (error) {\n console.error(\n `[webrtc-transport] Failed to decode message from peer ${remotePeerId}:`,\n error,\n )\n }\n }\n}\n\n// ---------------------------------------------------------------------------\n// Factory function\n// ---------------------------------------------------------------------------\n\n/\n Create a WebRTC transport factory for use with `Exchange`.\n \n Returns a `TransportFactory` — pass directly to\n * `Exchange({ transports: [...] })`. The returned transport instance\n * exposes `attachDataChannel()` / `detachDataChannel()` for BYODC\n * data channel management.\n \n To access the transport instance after creation, use\n * `exchange.getTransport(\"webrtc-datachannel\")`.\n \n @example\n * ```typescript\n * import { Exchange } from \"@kyneta/exchange\"\n * import { createWebrtcTransport } from \"@kyneta/webrtc-transport\"\n \n const exchange = new Exchange({\n * id: { peerId: \"alice\", name: \"Alice\" },\n * transports: [createWebrtcTransport()],\n * })\n * ```\n */\nexport function createWebrtcTransport(\n options?: WebrtcTransportOptions,\n): TransportFactory {\n return () => new WebrtcTransport(options)\n}\n"],"mappings":"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"}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/webrtc-transport",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "WebRTC data channel transport for @kyneta/exchange — BYODC (Bring Your Own Data Channel) with DataChannelLike interface",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -25,21 +25,21 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kyneta/transport": "^1.3.1",
-    "@kyneta/wire": "^1.3.1"
+    "@kyneta/transport": "^1.4.0",
+    "@kyneta/wire": "^1.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",
-    "tsup": "^8.5.0",
+    "tsdown": "^0.21.9",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17",
-    "@kyneta/exchange": "^1.3.1",
-    "@kyneta/wire": "^1.3.1",
-    "@kyneta/schema": "^1.3.1",
-    "@kyneta/transport": "^1.3.1"
+    "@kyneta/exchange": "^1.4.0",
+    "@kyneta/wire": "^1.4.0",
+    "@kyneta/schema": "^1.4.0",
+    "@kyneta/transport": "^1.4.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "test": "verify logic",
     "verify": "verify"
   }

package/src/__tests__/webrtc-transport.test.ts CHANGED Viewed

@@ -45,9 +45,9 @@ async function initializeTransport(
   return ctx
 }
-/** A minimal establish-request message for send/receive tests. */
+/** A minimal establish message for send/receive tests. */
 const TEST_MSG: ChannelMsg = {
-  type: "establish-request",
+  type: "establish",
   identity: { peerId: "remote", name: "R", type: "user" },
 }
@@ -210,7 +210,7 @@ describe("Receive", () => {
     if (!callArgs)
       throw new Error("expected onChannelReceive to have been called")
     const [, receivedMsg] = callArgs
-    expect(receivedMsg.type).toBe("establish-request")
+    expect(receivedMsg.type).toBe("establish")
     expect((receivedMsg as any).identity.peerId).toBe("remote")
   })
@@ -229,7 +229,7 @@ describe("Receive", () => {
     if (!callArgs)
       throw new Error("expected onChannelReceive to have been called")
     const [, receivedMsg] = callArgs
-    expect(receivedMsg.type).toBe("establish-request")
+    expect(receivedMsg.type).toBe("establish")
     expect((receivedMsg as any).identity.peerId).toBe("remote")
   })
@@ -303,7 +303,7 @@ describe("Fragmentation", () => {
     // binary frame may exceed it if the CBOR encoding + frame header is large enough.
     // Use a message with enough payload to guarantee fragmentation.
     const largeMsg: ChannelMsg = {
-      type: "establish-request",
+      type: "establish",
       identity: {
         peerId: `a]very-long-peer-id-${"x".repeat(200)}`,
         name: `A Long Name ${"y".repeat(200)}`,
@@ -326,7 +326,7 @@ describe("Fragmentation", () => {
     // Build a message large enough to guarantee multiple fragments at chunk size 50
     const largeMsg: ChannelMsg = {
-      type: "establish-request",
+      type: "establish",
       identity: {
         peerId: `peer-${"z".repeat(200)}`,
         name: `Name-${"w".repeat(200)}`,
@@ -364,7 +364,7 @@ describe("Fragmentation", () => {
     if (!callArgs)
       throw new Error("expected onChannelReceive to have been called")
     const [, receivedMsg] = callArgs
-    expect(receivedMsg.type).toBe("establish-request")
+    expect(receivedMsg.type).toBe("establish")
     expect((receivedMsg as any).identity.peerId).toBe(`peer-${"z".repeat(200)}`)
   })
 })

package/src/webrtc-transport.ts CHANGED Viewed

@@ -104,7 +104,7 @@ type AttachedChannel = {
  * const webrtcTransport = createWebrtcTransport()
  *
  * const exchange = new Exchange({
- *   identity: { peerId: "alice", name: "Alice" },
+ *   id: { peerId: "alice", name: "Alice" },
  *   transports: [webrtcTransport],
  * })
  *
@@ -422,7 +422,7 @@ export class WebrtcTransport extends Transport<DataChannelContext> {
  * import { createWebrtcTransport } from "@kyneta/webrtc-transport"
  *
  * const exchange = new Exchange({
- *   identity: { peerId: "alice", name: "Alice" },
+ *   id: { peerId: "alice", name: "Alice" },
  *   transports: [createWebrtcTransport()],
  * })
  * ```