@marianmeres/webrtc 1.2.6 → 1.3.0

package/AGENTS.md

@@ -159,6 +159,15 @@ interface WebRtcManagerConfig {
 }
 ```
 
+### GatherIceCandidatesOptions Interface
+
+```typescript
+interface GatherIceCandidatesOptions {
+  timeout?: number;                                    // Timeout in ms (default: 10000)
+  onCandidate?: (candidate: RTCIceCandidate | null) => void;  // Called for each candidate
+}
+```
+
 ### Properties (Getters)
 
 | Property | Type | Description |
@@ -205,6 +214,7 @@ interface WebRtcManagerConfig {
 | setRemoteDescription | `(description: RTCSessionDescriptionInit): Promise<boolean>` | Set remote SDP |
 | addIceCandidate | `(candidate: RTCIceCandidateInit \| null): Promise<boolean>` | Add ICE candidate |
 | iceRestart | `(): Promise<boolean>` | Perform ICE restart |
+| gatherIceCandidates | `(options?: GatherIceCandidatesOptions): Promise<void>` | Wait for ICE gathering to complete |
 | getLocalDescription | `(): RTCSessionDescription \| null` | Get local SDP |
 | getRemoteDescription | `(): RTCSessionDescription \| null` | Get remote SDP |
 | getStats | `(): Promise<RTCStatsReport \| null>` | Get connection statistics |

package/README.md

@@ -95,6 +95,35 @@ await manager.setLocalDescription(offer)
 await manager.setRemoteDescription(answer)
 await manager.addIceCandidate(candidate)
 await manager.iceRestart()                     // Trigger ICE restart
+await manager.gatherIceCandidates(options)     // Wait for ICE gathering to complete
+```
+
+### gatherIceCandidates(options?)
+
+Wait for ICE gathering to complete. Useful for HTTP POST signaling patterns where you need all ICE candidates bundled in the local description before sending to the server.
+
+**Options:** `timeout` (ms, default 10000), `onCandidate` (callback for each candidate)
+
+```typescript
+const offer = await manager.createOffer();
+await manager.setLocalDescription(offer);
+await manager.gatherIceCandidates({ timeout: 5000 });
+// Now manager.peerConnection.localDescription has all ICE candidates bundled
+```
+
+**Error Handling:** A timeout rejection does *not* transition the FSM to ERROR state. This is intentional - `gatherIceCandidates()` is a utility method, and a timeout means "gathering didn't complete in time", not "the connection failed". The consumer decides how to handle it:
+
+```typescript
+try {
+  await manager.gatherIceCandidates({ timeout: 5000 });
+} catch (e) {
+  if (e.message === "ICE gathering timeout") {
+    // Options:
+    // 1. Retry with longer timeout
+    // 2. Proceed anyway - localDescription may have partial candidates
+    // 3. Treat as fatal: manager.reset()
+  }
+}
 ```
 
 ### Data Channel Methods

package/dist/types.d.ts

@@ -156,3 +156,13 @@ export interface WebRtcEvents {
     /** Emitted when an error occurs. Payload: the Error object. */
     error: Error;
 }
+/**
+ * Options for waiting for ICE gathering to complete.
+ * Used with gatherIceCandidates() for HTTP POST signaling patterns.
+ */
+export interface GatherIceCandidatesOptions {
+    /** Timeout in milliseconds (default: 10000) */
+    timeout?: number;
+    /** Called for each ICE candidate as it's gathered */
+    onCandidate?: (candidate: RTCIceCandidate | null) => void;
+}

package/dist/webrtc-manager.d.ts

@@ -1,4 +1,4 @@
-import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcEvents } from "./types.js";
+import { type WebRtcFactory, type WebRtcManagerConfig, WebRtcState, type WebRtcEvents, type GatherIceCandidatesOptions } from "./types.js";
 /**
  * WebRTC connection manager with FSM-based lifecycle and event-driven architecture.
  *
@@ -203,6 +203,13 @@ export declare class WebRtcManager<TContext = unknown> {
      * @returns True if successful, false otherwise.
      */
     iceRestart(): Promise<boolean>;
+    /**
+     * Wait for ICE gathering to complete.
+     * Use this for HTTP POST signaling patterns where you need all ICE candidates
+     * bundled in the local description before sending to the server.
+     * @param options - Optional configuration for timeout and candidate callback.
+     */
+    gatherIceCandidates(options?: GatherIceCandidatesOptions): Promise<void>;
     /**
      * Returns the current local session description.
      * @returns The local description, or null if not set.

package/dist/webrtc-manager.js

@@ -675,6 +675,52 @@ export class WebRtcManager {
             return false;
         }
     }
+    /**
+     * Wait for ICE gathering to complete.
+     * Use this for HTTP POST signaling patterns where you need all ICE candidates
+     * bundled in the local description before sending to the server.
+     * @param options - Optional configuration for timeout and candidate callback.
+     */
+    gatherIceCandidates(options = {}) {
+        const { timeout = 10000, onCandidate } = options;
+        if (!this.#pc) {
+            return Promise.reject(new Error("Peer connection not initialized"));
+        }
+        const pc = this.#pc;
+        if (pc.iceGatheringState === "complete") {
+            this.#logDebug("ICE gathering already complete");
+            return Promise.resolve();
+        }
+        this.#logDebug("Waiting for ICE gathering to complete...");
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error("ICE gathering timeout"));
+            }, timeout);
+            const cleanup = () => {
+                clearTimeout(timer);
+                pc.removeEventListener("icegatheringstatechange", checkState);
+                pc.removeEventListener("icecandidate", handleCandidate);
+            };
+            const checkState = () => {
+                if (pc.iceGatheringState === "complete") {
+                    this.#logDebug("ICE gathering complete (via state change)");
+                    cleanup();
+                    resolve();
+                }
+            };
+            const handleCandidate = (event) => {
+                onCandidate?.(event.candidate);
+                if (event.candidate === null) {
+                    this.#logDebug("ICE gathering complete (null candidate)");
+                    cleanup();
+                    resolve();
+                }
+            };
+            pc.addEventListener("icegatheringstatechange", checkState);
+            pc.addEventListener("icecandidate", handleCandidate);
+        });
+    }
     /**
      * Returns the current local session description.
      * @returns The local description, or null if not set.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/webrtc",
-	"version": "1.2.6",
+	"version": "1.3.0",
 	"type": "module",
 	"main": "dist/mod.js",
 	"types": "dist/mod.d.ts",