@marianmeres/webrtc 1.0.2 → 1.1.0

package/AGENTS.md

@@ -4,7 +4,7 @@
 
 ```yaml
 name: "@marianmeres/webrtc"
-version: "0.0.2"
+version: "1.0.2"
 license: MIT
 author: Marian Meres
 repository: https://github.com/marianmeres/webrtc
@@ -27,12 +27,12 @@ A lightweight, framework-agnostic WebRTC manager providing:
 
 ```yaml
 production:
-  - "@marianmeres/fsm": "^2.3.0"
-  - "@marianmeres/pubsub": "^2.4.0"
+  - "@marianmeres/fsm": "^2.11.0"
+  - "@marianmeres/pubsub": "^2.4.4"
 development:
-  - "@std/assert": testing
-  - "@std/fs": file operations
-  - "@std/path": path utilities
+  - "@std/assert": "^1.0.16"
+  - "@std/fs": "^1.0.20"
+  - "@std/path": "^1.1.3"
 ```
 
 ## File Structure
@@ -123,10 +123,10 @@ Console-compatible logger interface for custom logging implementations.
 
 ```typescript
 interface Logger {
-  debug: (...args: any[]) => string;
-  log: (...args: any[]) => string;
-  warn: (...args: any[]) => string;
-  error: (...args: any[]) => string;
+  debug: (...args: any[]) => any;
+  log: (...args: any[]) => any;
+  warn: (...args: any[]) => any;
+  error: (...args: any[]) => any;
 }
 ```
 

package/API.md

@@ -687,10 +687,10 @@ Console-compatible logger interface for custom logging implementations.
 
 ```typescript
 interface Logger {
-  debug: (...args: any[]) => string;
-  log: (...args: any[]) => string;
-  warn: (...args: any[]) => string;
-  error: (...args: any[]) => string;
+  debug: (...args: any[]) => any;
+  log: (...args: any[]) => any;
+  warn: (...args: any[]) => any;
+  error: (...args: any[]) => any;
 }
 ```
 
@@ -759,6 +759,13 @@ interface WebRtcManagerConfig {
   /** Initial reconnection delay in ms (doubles each attempt). Default: 1000 */
   reconnectDelay?: number;
 
+  /** Callback to control whether reconnection should proceed */
+  shouldReconnect?: (context: {
+    attempt: number;
+    maxAttempts: number;
+    strategy: "ice-restart" | "full";
+  }) => boolean;
+
   /** Enable debug logging. Default: false */
   debug?: boolean;
 
@@ -947,3 +954,31 @@ manager.on('reconnecting', ({ attempt, strategy }) => {
   }
 });
 ```
+
+### Conditional Reconnection
+
+Use the `shouldReconnect` callback to suppress reconnection when the peer disconnected intentionally:
+
+```typescript
+let peerLeftIntentionally = false;
+
+const manager = new WebRtcManager(factory, {
+  autoReconnect: true,
+  shouldReconnect: ({ attempt, maxAttempts, strategy }) => {
+    // Return false to suppress reconnection
+    return !peerLeftIntentionally;
+  },
+});
+
+// Track intentional disconnects via data channel
+manager.on('data_channel_message', ({ data }) => {
+  if (JSON.parse(data).type === 'bye') {
+    peerLeftIntentionally = true;
+  }
+});
+```
+
+The callback receives:
+- `attempt`: Current attempt number (1-based)
+- `maxAttempts`: Configured maximum attempts
+- `strategy`: `"ice-restart"` or `"full"`

package/README.md

@@ -51,6 +51,7 @@ const manager = new WebRtcManager(factory, config);
 - `autoReconnect`: Enable automatic reconnection (default: false)
 - `maxReconnectAttempts`: Max reconnection attempts (default: 5)
 - `reconnectDelay`: Initial reconnection delay in ms (default: 1000)
+- `shouldReconnect`: Callback to control whether reconnection should proceed (see below)
 - `debug`: Enable debug logging (default: false)
 - `logger`: Custom logger instance implementing `Logger` interface (default: console)
 
@@ -129,6 +130,37 @@ const unsub = manager.subscribe((state) => {
 - `EVENT_MICROPHONE_FAILED`
 - `EVENT_ERROR`
 
+### Controlling Reconnection
+
+When `autoReconnect` is enabled, you can use the `shouldReconnect` callback to conditionally suppress reconnection attempts. This is useful when the remote peer disconnected intentionally (e.g., left the call) rather than due to network failure.
+
+```typescript
+let peerLeftIntentionally = false;
+
+const manager = new WebRtcManager(factory, {
+  autoReconnect: true,
+  shouldReconnect: ({ attempt, maxAttempts, strategy }) => {
+    if (peerLeftIntentionally) {
+      return false; // Don't reconnect
+    }
+    return true;
+  },
+});
+
+// Listen for "goodbye" message from peer before they disconnect
+manager.on(WebRtcManager.EVENT_DATA_CHANNEL_MESSAGE, ({ data }) => {
+  const msg = JSON.parse(data);
+  if (msg.type === 'bye') {
+    peerLeftIntentionally = true;
+  }
+});
+```
+
+The callback receives:
+- `attempt`: Current reconnection attempt (1-based)
+- `maxAttempts`: Configured maximum attempts
+- `strategy`: `"ice-restart"` (attempts 1-2) or `"full"` (attempts 3+)
+
 ## Examples
 
 ### Basic Usage (Vanilla JavaScript)

package/dist/types.d.ts

@@ -1,14 +1,18 @@
 /**
- * Console-compatible logger interface.
+ * Console-compatible logger interface (see @marianmeres/clog ).
  * Each method accepts variadic arguments and returns a string representation of the first argument.
  * This enables patterns like `throw new Error(logger.error("msg"))`.
  */
 export interface Logger {
-    debug: (...args: any[]) => string;
-    log: (...args: any[]) => string;
-    warn: (...args: any[]) => string;
-    error: (...args: any[]) => string;
+    debug: (...args: any[]) => any;
+    log: (...args: any[]) => any;
+    warn: (...args: any[]) => any;
+    error: (...args: any[]) => any;
 }
+/**
+ * Configuration options for WebRtcManager.
+ * All options are optional with sensible defaults.
+ */
 export interface WebRtcManagerConfig {
     /** Initial peer configuration (ICE servers, etc.) */
     peerConfig?: RTCConfiguration;
@@ -22,44 +26,109 @@ export interface WebRtcManagerConfig {
     maxReconnectAttempts?: number;
     /** Initial reconnection delay in ms. Doubles with each attempt. Defaults to 1000. */
     reconnectDelay?: number;
+    /**
+     * Callback to determine whether reconnection should be attempted.
+     * Called before each reconnection attempt when autoReconnect is enabled.
+     * Return false to suppress reconnection (e.g., when peer disconnected intentionally).
+     * If not provided, reconnection proceeds automatically up to maxReconnectAttempts.
+     */
+    shouldReconnect?: (context: {
+        /** Current reconnection attempt number (1-based) */
+        attempt: number;
+        /** Maximum configured reconnection attempts */
+        maxAttempts: number;
+        /** Strategy that will be used: "ice-restart" for first attempts, "full" for later */
+        strategy: "ice-restart" | "full";
+    }) => boolean;
     /** Enable debug logging. Defaults to false. */
     debug?: boolean;
     /** Custom logger instance. If not provided, falls back to console. */
     logger?: Logger;
 }
+/**
+ * Factory interface for creating WebRTC primitives.
+ * Allows dependency injection of browser APIs for testing and flexibility.
+ */
 export interface WebRtcFactory {
+    /**
+     * Creates a new RTCPeerConnection instance.
+     * @param config - Optional RTCConfiguration for ICE servers, certificates, etc.
+     * @returns A new RTCPeerConnection instance.
+     */
     createPeerConnection(config?: RTCConfiguration): RTCPeerConnection;
+    /**
+     * Requests access to user media (microphone/camera).
+     * @param constraints - Media constraints specifying audio/video requirements.
+     * @returns Promise resolving to a MediaStream.
+     */
     getUserMedia(constraints: MediaStreamConstraints): Promise<MediaStream>;
+    /**
+     * Enumerates all available media input and output devices.
+     * @returns Promise resolving to an array of MediaDeviceInfo objects.
+     */
     enumerateDevices(): Promise<MediaDeviceInfo[]>;
 }
+/**
+ * Possible states of the WebRTC connection lifecycle.
+ * The manager transitions between these states based on connection events.
+ */
 export declare enum WebRtcState {
+    /** Initial state, no resources allocated. */
     IDLE = "IDLE",
+    /** Creating peer connection and setting up media tracks. */
     INITIALIZING = "INITIALIZING",
+    /** Performing SDP offer/answer exchange. */
     CONNECTING = "CONNECTING",
+    /** Connection established, communication active. */
     CONNECTED = "CONNECTED",
+    /** Automatic reconnection in progress. */
     RECONNECTING = "RECONNECTING",
+    /** Connection closed, can be restarted. */
     DISCONNECTED = "DISCONNECTED",
+    /** Error state, requires reset() to recover. */
     ERROR = "ERROR"
 }
+/**
+ * Internal FSM events that trigger state transitions.
+ * These events are dispatched internally by the manager methods.
+ */
 export declare enum WebRtcFsmEvent {
+    /** Triggers transition from IDLE to INITIALIZING. */
     INIT = "initialize",
+    /** Triggers transition to CONNECTING state. */
     CONNECT = "connect",
+    /** Signals successful connection establishment. */
     CONNECTED = "connected",
+    /** Triggers transition to RECONNECTING state. */
     RECONNECTING = "reconnecting",
+    /** Triggers transition to DISCONNECTED state. */
     DISCONNECT = "disconnect",
+    /** Triggers transition to ERROR state. */
     ERROR = "error",
+    /** Resets the manager to IDLE state. */
     RESET = "reset"
 }
+/**
+ * Type definitions for all WebRTC manager events and their payloads.
+ * Use with the `on()` method to subscribe to specific events.
+ */
 export interface WebRtcEvents {
+    /** Emitted when connection state changes. Payload: the new WebRtcState. */
     state_change: WebRtcState;
+    /** Emitted when local media stream changes. Payload: MediaStream or null if disabled. */
     local_stream: MediaStream | null;
+    /** Emitted when remote media stream is received. Payload: MediaStream or null. */
     remote_stream: MediaStream | null;
+    /** Emitted when a data channel opens. Payload: the RTCDataChannel. */
     data_channel_open: RTCDataChannel;
+    /** Emitted when a data channel receives a message. Payload: channel and data. */
     data_channel_message: {
         channel: RTCDataChannel;
         data: any;
     };
+    /** Emitted when a data channel closes. Payload: the RTCDataChannel. */
     data_channel_close: RTCDataChannel;
+    /** Emitted when an ICE candidate is generated. Payload: RTCIceCandidate or null. */
     ice_candidate: RTCIceCandidate | null;
     /**
      * Emitted when reconnection is being attempted.
@@ -71,13 +140,17 @@ export interface WebRtcEvents {
         attempt: number;
         strategy: "ice-restart" | "full";
     };
+    /** Emitted when all reconnection attempts have failed. Payload: total attempts. */
     reconnect_failed: {
         attempts: number;
     };
+    /** Emitted when audio devices change. Payload: array of available audio inputs. */
     device_changed: MediaDeviceInfo[];
+    /** Emitted when microphone access or switching fails. */
     microphone_failed: {
         error?: any;
         reason?: string;
     };
+    /** Emitted when an error occurs. Payload: the Error object. */
     error: Error;
 }

package/dist/types.js

@@ -1,20 +1,42 @@
+/**
+ * Possible states of the WebRTC connection lifecycle.
+ * The manager transitions between these states based on connection events.
+ */
 export var WebRtcState;
 (function (WebRtcState) {
+    /** Initial state, no resources allocated. */
     WebRtcState["IDLE"] = "IDLE";
+    /** Creating peer connection and setting up media tracks. */
     WebRtcState["INITIALIZING"] = "INITIALIZING";
+    /** Performing SDP offer/answer exchange. */
     WebRtcState["CONNECTING"] = "CONNECTING";
+    /** Connection established, communication active. */
     WebRtcState["CONNECTED"] = "CONNECTED";
+    /** Automatic reconnection in progress. */
     WebRtcState["RECONNECTING"] = "RECONNECTING";
+    /** Connection closed, can be restarted. */
     WebRtcState["DISCONNECTED"] = "DISCONNECTED";
+    /** Error state, requires reset() to recover. */
     WebRtcState["ERROR"] = "ERROR";
 })(WebRtcState || (WebRtcState = {}));
+/**
+ * Internal FSM events that trigger state transitions.
+ * These events are dispatched internally by the manager methods.
+ */
 export var WebRtcFsmEvent;
 (function (WebRtcFsmEvent) {
+    /** Triggers transition from IDLE to INITIALIZING. */
     WebRtcFsmEvent["INIT"] = "initialize";
+    /** Triggers transition to CONNECTING state. */
     WebRtcFsmEvent["CONNECT"] = "connect";
+    /** Signals successful connection establishment. */
     WebRtcFsmEvent["CONNECTED"] = "connected";
+    /** Triggers transition to RECONNECTING state. */
     WebRtcFsmEvent["RECONNECTING"] = "reconnecting";
+    /** Triggers transition to DISCONNECTED state. */
     WebRtcFsmEvent["DISCONNECT"] = "disconnect";
+    /** Triggers transition to ERROR state. */
     WebRtcFsmEvent["ERROR"] = "error";
+    /** Resets the manager to IDLE state. */
     WebRtcFsmEvent["RESET"] = "reset";
 })(WebRtcFsmEvent || (WebRtcFsmEvent = {}));

package/dist/webrtc-manager.js

@@ -2,22 +2,26 @@ import { FSM } from "@marianmeres/fsm";
 import { PubSub } from "@marianmeres/pubsub";
 import { WebRtcState, WebRtcFsmEvent, } from "./types.js";
 /**
- * Default console-based logger that wraps console methods to satisfy the Logger interface.
+ * Default console-based logger that wraps console methods.
  * Returns string representation of the first argument for chaining.
  */
 const createDefaultLogger = () => ({
+    // deno-lint-ignore no-explicit-any
     debug: (...args) => {
         console.debug(...args);
         return String(args[0] ?? "");
     },
+    // deno-lint-ignore no-explicit-any
     log: (...args) => {
         console.log(...args);
         return String(args[0] ?? "");
     },
+    // deno-lint-ignore no-explicit-any
     warn: (...args) => {
         console.warn(...args);
         return String(args[0] ?? "");
     },
+    // deno-lint-ignore no-explicit-any
     error: (...args) => {
         console.error(...args);
         return String(args[0] ?? "");
@@ -173,6 +177,7 @@ export class WebRtcManager {
      * @param handler - Callback function that receives the event data.
      * @returns Unsubscribe function to remove the event listener.
      */
+    // deno-lint-ignore no-explicit-any
     on(event, handler) {
         return this.#pubsub.subscribe(event, handler);
     }
@@ -387,7 +392,9 @@ export class WebRtcManager {
             }
             catch (e) {
                 this.#logger.error("[WebRtcManager] Failed to get user media:", e);
-                this.#pubsub.publish(WebRtcManager.EVENT_MICROPHONE_FAILED, { error: e });
+                this.#pubsub.publish(WebRtcManager.EVENT_MICROPHONE_FAILED, {
+                    error: e,
+                });
                 return false;
             }
         }
@@ -678,11 +685,13 @@ export class WebRtcManager {
             this.#pubsub.publish(WebRtcManager.EVENT_STATE_CHANGE, newState);
         }
     }
+    // deno-lint-ignore no-explicit-any
     #debug(...args) {
         if (this.#config.debug) {
             this.#logger.debug("[WebRtcManager]", ...args);
         }
     }
+    // deno-lint-ignore no-explicit-any
     #error(error) {
         this.#logger.error("[WebRtcManager]", error);
         this.#dispatch(WebRtcFsmEvent.ERROR);
@@ -705,7 +714,12 @@ export class WebRtcManager {
                 this.#handleConnectionFailure();
             }
             else if (state === "disconnected" || state === "closed") {
-                this.#dispatch(WebRtcFsmEvent.DISCONNECT);
+                // Only dispatch if not already in a terminal state
+                if (this.state !== WebRtcState.DISCONNECTED &&
+                    this.state !== WebRtcState.ERROR &&
+                    this.state !== WebRtcState.IDLE) {
+                    this.#dispatch(WebRtcFsmEvent.DISCONNECT);
+                }
             }
         };
         this.#pc.ontrack = (event) => {
@@ -766,7 +780,12 @@ export class WebRtcManager {
     }
     #handleConnectionFailure() {
         this.#debug("Handling connection failure");
-        this.#dispatch(WebRtcFsmEvent.DISCONNECT);
+        // Only dispatch DISCONNECT if not already in a terminal state
+        if (this.state !== WebRtcState.DISCONNECTED &&
+            this.state !== WebRtcState.ERROR &&
+            this.state !== WebRtcState.IDLE) {
+            this.#dispatch(WebRtcFsmEvent.DISCONNECT);
+        }
         // Check if auto-reconnect is enabled
         if (!this.#config.autoReconnect) {
             this.#debug("Auto-reconnect disabled, not attempting reconnection");
@@ -781,6 +800,21 @@ export class WebRtcManager {
             });
             return;
         }
+        // Determine strategy for this attempt (next attempt number is current + 1)
+        const nextAttempt = this.#reconnectAttempts + 1;
+        const strategy = nextAttempt <= 2 ? "ice-restart" : "full";
+        // Check shouldReconnect callback if provided
+        if (this.#config.shouldReconnect) {
+            const shouldProceed = this.#config.shouldReconnect?.({
+                attempt: nextAttempt,
+                maxAttempts,
+                strategy,
+            });
+            if (!shouldProceed) {
+                this.#debug("Reconnection suppressed by shouldReconnect callback");
+                return;
+            }
+        }
         // Transition to RECONNECTING state
         this.#dispatch(WebRtcFsmEvent.RECONNECTING);
         // Attempt reconnection with exponential backoff
@@ -863,6 +897,7 @@ export class WebRtcManager {
             this.#pubsub.publish(WebRtcManager.EVENT_DATA_CHANNEL_CLOSE, dc);
             this.#dataChannels.delete(dc.label);
         };
+        // deno-lint-ignore no-explicit-any
         dc.onerror = (error) => {
             // Ignore "User-Initiated Abort" errors which occur during intentional close()
             const isUserAbort = error?.error?.message?.includes("User-Initiated Abort");

package/package.json

@@ -1,14 +1,20 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.0.2",
+	"version": "1.1.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/mod.d.ts",
+			"import": "./dist/mod.js"
+		}
+	},
 	"author": "Marian Meres",
 	"license": "MIT",
 	"dependencies": {
-		"@marianmeres/fsm": "^2.6.4",
-		"@marianmeres/pubsub": "^2.4.3"
+		"@marianmeres/fsm": "^2.11.0",
+		"@marianmeres/pubsub": "^2.4.4"
 	},
 	"repository": {
 		"type": "git",