@xtr-dev/rondevu-client 0.20.1 → 0.21.1

package/dist/connections/offerer.js

@@ -10,16 +10,16 @@ import { AsyncLock } from '../utils/async-lock.js';
 export class OffererConnection extends RondevuConnection {
     constructor(options) {
         // Force reconnectEnabled: false for offerer connections (offers are ephemeral)
-        super(undefined, {
-            ...options.config,
-            reconnectEnabled: false
-        });
+        super(undefined, { ...options.config, reconnectEnabled: false }, options.webrtcAdapter);
+        this._peerUsername = null;
         // Rotation tracking
         this.rotationLock = new AsyncLock();
         this.rotating = false;
         this.rotationAttempts = 0;
+        // ICE candidate buffering (for candidates received before answer is processed)
+        this.pendingIceCandidates = [];
         this.api = options.api;
-        this.serviceFqn = options.serviceFqn;
+        this.ownerUsername = options.ownerUsername;
         this.offerId = options.offerId;
         // Use the already-created peer connection and data channel
         this.pc = options.pc;
@@ -33,7 +33,7 @@ export class OffererConnection extends RondevuConnection {
         if (!this.pc)
             throw new Error('Peer connection not provided');
         // Setup peer connection event handlers
-        this.pc.onicecandidate = (event) => this.handleIceCandidate(event);
+        this.pc.onicecandidate = event => this.handleIceCandidate(event);
         this.pc.oniceconnectionstatechange = () => this.handleIceConnectionStateChange();
         this.pc.onconnectionstatechange = () => this.handleConnectionStateChange();
         this.pc.onicegatheringstatechange = () => this.handleIceGatheringStateChange();
@@ -67,8 +67,10 @@ export class OffererConnection extends RondevuConnection {
                 throw new Error('Received different answer after already processing one (protocol violation)');
             }
         }
-        // Validate state
-        if (this.state !== ConnectionState.SIGNALING && this.state !== ConnectionState.CHECKING) {
+        // Validate state - allow SIGNALING, CHECKING, and FAILED (for late-arriving answers before rotation)
+        if (this.state !== ConnectionState.SIGNALING &&
+            this.state !== ConnectionState.CHECKING &&
+            this.state !== ConnectionState.FAILED) {
             this.debug(`Cannot process answer in state ${this.state}`);
             return;
         }
@@ -80,8 +82,17 @@ export class OffererConnection extends RondevuConnection {
                 type: 'answer',
                 sdp,
             });
+            // Store the peer username
+            this._peerUsername = answererId;
             this.debug(`Answer processed successfully from ${answererId}`);
             this.emit('answer:processed', this.offerId, answererId);
+            // Apply any buffered ICE candidates that arrived before the answer
+            if (this.pendingIceCandidates.length > 0) {
+                this.debug(`Applying ${this.pendingIceCandidates.length} buffered ICE candidates`);
+                const buffered = this.pendingIceCandidates;
+                this.pendingIceCandidates = [];
+                this.applyIceCandidates(buffered);
+            }
         }
         catch (error) {
             // Reset flags on error so we can try again
@@ -118,11 +129,13 @@ export class OffererConnection extends RondevuConnection {
                 this.offerId = newOfferId;
                 this.pc = newPc;
                 this.dc = newDc || null;
-                // 3. Reset answer processing flags
+                // 3. Reset answer processing flags, peer username, and pending candidates
                 this.answerProcessed = false;
                 this.answerSdpFingerprint = null;
+                this._peerUsername = null;
+                this.pendingIceCandidates = [];
                 // 4. Setup event handlers for new peer connection
-                this.pc.onicecandidate = (event) => this.handleIceCandidate(event);
+                this.pc.onicecandidate = event => this.handleIceCandidate(event);
                 this.pc.oniceconnectionstatechange = () => this.handleIceConnectionStateChange();
                 this.pc.onconnectionstatechange = () => this.handleConnectionStateChange();
                 this.pc.onicegatheringstatechange = () => this.handleIceGatheringStateChange();
@@ -166,7 +179,7 @@ export class OffererConnection extends RondevuConnection {
             const data = encoder.encode(sdp);
             const hashBuffer = await crypto.subtle.digest('SHA-256', data);
             const hashArray = Array.from(new Uint8Array(hashBuffer));
-            return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+            return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
         }
         else {
             // Fallback: use simple string hash
@@ -186,14 +199,14 @@ export class OffererConnection extends RondevuConnection {
         this.debug('Generated local ICE candidate');
         // Send ICE candidate to server
         this.api
-            .addOfferIceCandidates(this.serviceFqn, this.offerId, [
+            .addOfferIceCandidates(this.offerId, [
             {
                 candidate: candidate.candidate,
                 sdpMLineIndex: candidate.sdpMLineIndex,
                 sdpMid: candidate.sdpMid,
             },
         ])
-            .catch((error) => {
+            .catch(error => {
             this.debug('Failed to send ICE candidate:', error);
         });
     }
@@ -204,10 +217,10 @@ export class OffererConnection extends RondevuConnection {
         return this.api;
     }
     /**
-     * Get the service FQN
+     * Get the owner username
      */
-    getServiceFqn() {
-        return this.serviceFqn;
+    getOwnerUsername() {
+        return this.ownerUsername;
     }
     /**
      * Offerers accept all ICE candidates (no filtering)
@@ -216,17 +229,25 @@ export class OffererConnection extends RondevuConnection {
         return null;
     }
     /**
-     * Attempt to reconnect
+     * Attempt to reconnect (required by abstract base class)
+     *
+     * For OffererConnection, traditional reconnection is NOT used.
+     * Instead, the OfferPool handles failures via offer rotation:
      *
-     * Note: For offerer connections, reconnection is handled by the Rondevu instance
-     * creating a new offer via fillOffers(). This method is a no-op.
+     * 1. When this connection fails, the 'failed' event is emitted
+     * 2. OfferPool detects the failure and calls createNewOfferForRotation()
+     * 3. The new offer is published to the server
+     * 4. This connection is rebound via rebindToOffer()
+     *
+     * This approach ensures the answerer always gets a fresh offer
+     * rather than trying to reconnect to a stale one.
+     *
+     * @see OfferPool.createNewOfferForRotation() - creates replacement offer
+     * @see OffererConnection.rebindToOffer() - rebinds connection to new offer
      */
     attemptReconnect() {
-        this.debug('Reconnection not applicable for offerer - new offer will be created by Rondevu instance');
-        // Offerer reconnection is handled externally by Rondevu.fillOffers()
-        // which creates entirely new offers. We don't reconnect the same offer.
-        // Just emit failure and let the parent handle it.
-        this.emit('reconnect:failed', new Error('Offerer reconnection handled by parent'));
+        this.debug('Reconnection delegated to OfferPool rotation mechanism');
+        this.emit('reconnect:failed', new Error('Offerer uses rotation, not reconnection'));
     }
     /**
      * Get the offer ID
@@ -234,5 +255,52 @@ export class OffererConnection extends RondevuConnection {
     getOfferId() {
         return this.offerId;
     }
+    /**
+     * Get the peer username (who answered this offer)
+     * Returns null if no answer has been processed yet
+     */
+    get peerUsername() {
+        return this._peerUsername;
+    }
+    /**
+     * Handle remote ICE candidates received from polling
+     * Called by OfferPool when poll:ice event is received
+     */
+    handleRemoteIceCandidates(candidates) {
+        if (!this.pc) {
+            this.debug('Cannot add ICE candidates: peer connection not initialized');
+            return;
+        }
+        // If answer hasn't been processed yet, buffer the candidates
+        if (!this.answerProcessed) {
+            this.debug(`Buffering ${candidates.length} ICE candidates (waiting for answer)`);
+            this.pendingIceCandidates.push(...candidates);
+            return;
+        }
+        // Answer is processed, apply candidates immediately
+        this.applyIceCandidates(candidates);
+    }
+    /**
+     * Apply ICE candidates to the peer connection
+     */
+    applyIceCandidates(candidates) {
+        if (!this.pc)
+            return;
+        for (const iceCandidate of candidates) {
+            // Offerer accepts answerer's candidates (no role filtering needed here
+            // since OfferPool already filters by offerId)
+            if (iceCandidate.candidate) {
+                const rtcCandidate = this.webrtcAdapter.createIceCandidate(iceCandidate.candidate);
+                this.pc
+                    .addIceCandidate(rtcCandidate)
+                    .then(() => {
+                    this.emit('ice:candidate:remote', rtcCandidate);
+                })
+                    .catch(error => {
+                    this.debug('Failed to add ICE candidate:', error);
+                });
+            }
+        }
+    }
 }
 OffererConnection.MAX_ROTATION_ATTEMPTS = 5;

package/dist/core/ice-config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ICE Configuration Types and Presets
+ *
+ * Provides typed ICE server presets for common WebRTC configurations.
+ */
+/**
+ * Available ICE server preset names
+ */
+export type IceServerPreset = 'rondevu' | 'rondevu-relay' | 'rondevu-ipv4' | 'rondevu-ipv4-relay' | 'google-stun' | 'public-stun';
+/**
+ * ICE preset configuration containing servers and optional transport policy.
+ * The iceTransportPolicy belongs on RTCConfiguration, not RTCIceServer.
+ */
+export interface IcePresetConfig {
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+}
+/**
+ * Pre-configured ICE server presets.
+ *
+ * - `rondevu`: Official Rondevu TURN/STUN servers (recommended)
+ * - `rondevu-relay`: Same as rondevu but forces relay mode (hides client IPs)
+ * - `rondevu-ipv4`: Direct IPv4 address (for networks with DNS issues)
+ * - `rondevu-ipv4-relay`: IPv4 with forced relay mode
+ * - `google-stun`: Google's free STUN servers (no relay, direct connections only)
+ * - `public-stun`: Multiple public STUN servers for redundancy
+ */
+export declare const ICE_SERVER_PRESETS: Record<IceServerPreset, IcePresetConfig>;
+/**
+ * Get the full RTCConfiguration for a preset or custom ICE servers.
+ *
+ * @param iceServers - Either a preset name or custom ICE servers array
+ * @returns Partial RTCConfiguration with iceServers and optional iceTransportPolicy
+ */
+export declare function getIceConfiguration(iceServers?: IceServerPreset | RTCIceServer[]): Pick<RTCConfiguration, 'iceServers' | 'iceTransportPolicy'>;

package/dist/core/ice-config.js

@@ -0,0 +1,111 @@
+/**
+ * ICE Configuration Types and Presets
+ *
+ * Provides typed ICE server presets for common WebRTC configurations.
+ */
+/**
+ * Pre-configured ICE server presets.
+ *
+ * - `rondevu`: Official Rondevu TURN/STUN servers (recommended)
+ * - `rondevu-relay`: Same as rondevu but forces relay mode (hides client IPs)
+ * - `rondevu-ipv4`: Direct IPv4 address (for networks with DNS issues)
+ * - `rondevu-ipv4-relay`: IPv4 with forced relay mode
+ * - `google-stun`: Google's free STUN servers (no relay, direct connections only)
+ * - `public-stun`: Multiple public STUN servers for redundancy
+ */
+export const ICE_SERVER_PRESETS = {
+    rondevu: {
+        iceServers: [
+            { urls: 'stun:relay.ronde.vu:3478' },
+            {
+                urls: [
+                    'turns:relay.ronde.vu:5349?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+    },
+    'rondevu-relay': {
+        iceServers: [
+            { urls: 'stun:relay.ronde.vu:3478' },
+            {
+                urls: [
+                    'turns:relay.ronde.vu:5349?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=tcp',
+                    'turn:relay.ronde.vu:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+        iceTransportPolicy: 'relay', // Force relay mode - hides client IPs
+    },
+    'rondevu-ipv4': {
+        iceServers: [
+            { urls: 'stun:57.129.61.67:3478' },
+            {
+                urls: [
+                    'turn:57.129.61.67:3478?transport=tcp',
+                    'turn:57.129.61.67:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+    },
+    'rondevu-ipv4-relay': {
+        iceServers: [
+            { urls: 'stun:57.129.61.67:3478' },
+            {
+                urls: [
+                    'turn:57.129.61.67:3478?transport=tcp',
+                    'turn:57.129.61.67:3478?transport=udp',
+                ],
+                username: 'rondevu',
+                credential: 'rondevu-public-turn',
+            },
+        ],
+        iceTransportPolicy: 'relay',
+    },
+    'google-stun': {
+        iceServers: [
+            { urls: 'stun:stun.l.google.com:19302' },
+            { urls: 'stun:stun1.l.google.com:19302' },
+        ],
+    },
+    'public-stun': {
+        iceServers: [
+            { urls: 'stun:stun.l.google.com:19302' },
+            { urls: 'stun:stun1.l.google.com:19302' },
+            { urls: 'stun:stun.cloudflare.com:3478' },
+            { urls: 'stun:stun.relay.metered.ca:80' },
+        ],
+    },
+};
+/**
+ * Get the full RTCConfiguration for a preset or custom ICE servers.
+ *
+ * @param iceServers - Either a preset name or custom ICE servers array
+ * @returns Partial RTCConfiguration with iceServers and optional iceTransportPolicy
+ */
+export function getIceConfiguration(iceServers) {
+    if (typeof iceServers === 'string') {
+        const preset = ICE_SERVER_PRESETS[iceServers];
+        return {
+            iceServers: preset.iceServers,
+            iceTransportPolicy: preset.iceTransportPolicy,
+        };
+    }
+    // Default to rondevu preset if no ICE servers specified
+    if (!iceServers) {
+        const preset = ICE_SERVER_PRESETS.rondevu;
+        return {
+            iceServers: preset.iceServers,
+            iceTransportPolicy: preset.iceTransportPolicy,
+        };
+    }
+    return { iceServers };
+}

package/dist/core/index.d.ts

@@ -1,22 +1,22 @@
 /**
  * @xtr-dev/rondevu-client
  * WebRTC peer signaling client
+ *
+ * Simple API:
+ *   const rondevu = await Rondevu.connect()
+ *
+ *   // Host: publish offers (auto-starts)
+ *   const offer = await rondevu.offer({ tags: ['chat'], maxOffers: 5 })
+ *   rondevu.on('connection:opened', (id, conn) => { ... })
+ *   // Later: offer.cancel()
+ *
+ *   // Guest: connect to a peer
+ *   const peer = await rondevu.peer({ tags: ['chat'] })
+ *   peer.on('open', () => peer.send('Hello!'))
  */
-export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
-export { RondevuAPI } from '../api/client.js';
-export { RpcBatcher } from '../api/batcher.js';
-export { RondevuConnection } from '../connections/base.js';
-export { OffererConnection } from '../connections/offerer.js';
-export { AnswererConnection } from '../connections/answerer.js';
-export { ExponentialBackoff } from '../utils/exponential-backoff.js';
-export { MessageBuffer } from '../utils/message-buffer.js';
-export { WebCryptoAdapter } from '../crypto/web.js';
-export { NodeCryptoAdapter } from '../crypto/node.js';
-export type { Signaler, Binnable, } from './types.js';
-export type { Keypair, OfferRequest, ServiceRequest, Service, ServiceOffer, IceCandidate, } from '../api/client.js';
-export type { RondevuOptions, PublishServiceOptions, ConnectToServiceOptions, ConnectionContext, OfferContext, OfferFactory, ActiveOffer, FindServiceOptions, ServiceResult, PaginatedServiceResult } from './rondevu.js';
-export type { CryptoAdapter } from '../crypto/adapter.js';
-export type { ConnectionConfig, } from '../connections/config.js';
-export type { ConnectionState, BufferedMessage, ReconnectInfo, StateChangeInfo, ConnectionEventMap, ConnectionEventName, ConnectionEventArgs, } from '../connections/events.js';
-export type { OffererOptions, } from '../connections/offerer.js';
-export type { AnswererOptions, } from '../connections/answerer.js';
+export { Rondevu } from './rondevu.js';
+export { Peer } from './peer.js';
+export { ICE_SERVER_PRESETS } from './ice-config.js';
+export type { RondevuOptions, OfferOptions, OfferHandle, DiscoverOptions, DiscoverResult, } from './rondevu.js';
+export type { PeerState, PeerOptions } from './peer.js';
+export type { IceServerPreset } from './ice-config.js';

package/dist/core/index.js

@@ -1,17 +1,22 @@
 /**
  * @xtr-dev/rondevu-client
  * WebRTC peer signaling client
+ *
+ * Simple API:
+ *   const rondevu = await Rondevu.connect()
+ *
+ *   // Host: publish offers (auto-starts)
+ *   const offer = await rondevu.offer({ tags: ['chat'], maxOffers: 5 })
+ *   rondevu.on('connection:opened', (id, conn) => { ... })
+ *   // Later: offer.cancel()
+ *
+ *   // Guest: connect to a peer
+ *   const peer = await rondevu.peer({ tags: ['chat'] })
+ *   peer.on('open', () => peer.send('Hello!'))
  */
-export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
-export { RondevuAPI } from '../api/client.js';
-export { RpcBatcher } from '../api/batcher.js';
-// Export connection classes
-export { RondevuConnection } from '../connections/base.js';
-export { OffererConnection } from '../connections/offerer.js';
-export { AnswererConnection } from '../connections/answerer.js';
-// Export utilities
-export { ExponentialBackoff } from '../utils/exponential-backoff.js';
-export { MessageBuffer } from '../utils/message-buffer.js';
-// Export crypto adapters
-export { WebCryptoAdapter } from '../crypto/web.js';
-export { NodeCryptoAdapter } from '../crypto/node.js';
+// Main entry point
+export { Rondevu } from './rondevu.js';
+// Simplified peer connection
+export { Peer } from './peer.js';
+// ICE server configuration presets
+export { ICE_SERVER_PRESETS } from './ice-config.js';

package/dist/core/offer-pool.d.ts

@@ -2,53 +2,59 @@ import { EventEmitter } from 'eventemitter3';
 import { RondevuAPI } from '../api/client.js';
 import { OffererConnection } from '../connections/offerer.js';
 import { ConnectionConfig } from '../connections/config.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
+import type { PollAnswerEvent, PollIceEvent } from './polling-manager.js';
 export type OfferFactory = (pc: RTCPeerConnection) => Promise<{
     dc?: RTCDataChannel;
     offer: RTCSessionDescriptionInit;
 }>;
 export interface OfferPoolOptions {
     api: RondevuAPI;
-    serviceFqn: string;
+    tags: string[];
+    ownerUsername: string;
     maxOffers: number;
     offerFactory: OfferFactory;
     ttl: number;
     iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    webrtcAdapter: WebRTCAdapter;
     connectionConfig?: Partial<ConnectionConfig>;
     debugEnabled?: boolean;
 }
 interface OfferPoolEvents {
     'connection:opened': (offerId: string, connection: OffererConnection) => void;
-    'offer:created': (offerId: string, serviceFqn: string) => void;
+    'offer:created': (offerId: string, tags: string[]) => void;
     'offer:failed': (offerId: string, error: Error) => void;
     'connection:rotated': (oldOfferId: string, newOfferId: string, connection: OffererConnection) => void;
 }
 /**
- * OfferPool manages a pool of WebRTC offers for a published service.
+ * OfferPool manages a pool of WebRTC offers for published tags.
  * Maintains a target number of active offers and automatically replaces
  * offers that fail or get answered.
  */
 export declare class OfferPool extends EventEmitter<OfferPoolEvents> {
     private readonly api;
-    private readonly serviceFqn;
+    private readonly tags;
+    private readonly ownerUsername;
     private readonly maxOffers;
     private readonly offerFactory;
     private readonly ttl;
     private readonly iceServers;
+    private readonly iceTransportPolicy?;
+    private readonly webrtcAdapter;
     private readonly connectionConfig?;
     private readonly debugEnabled;
     private readonly activeConnections;
     private readonly fillLock;
     private running;
-    private pollingInterval;
-    private lastPollTimestamp;
-    private static readonly POLLING_INTERVAL_MS;
     constructor(options: OfferPoolOptions);
     /**
-     * Start filling offers and polling for answers
+     * Start filling offers
+     * Polling is managed externally by Rondevu's PollingManager
      */
     start(): Promise<void>;
     /**
-     * Stop filling offers and polling
+     * Stop filling offers
      * Closes all active connections
      */
     stop(): void;
@@ -73,6 +79,13 @@ export declare class OfferPool extends EventEmitter<OfferPoolEvents> {
      * Uses AsyncLock to prevent concurrent fills
      */
     private fillOffers;
+    /**
+     * Create and publish an offer to the server.
+     * Shared logic used by both createOffer() and createNewOfferForRotation().
+     *
+     * @returns The offer ID, RTCPeerConnection, and optional data channel
+     */
+    private createOfferAndPublish;
     /**
      * Create a new offer for rotation (reuses existing creation logic)
      * Similar to createOffer() but only creates the offer, doesn't create connection
@@ -83,9 +96,15 @@ export declare class OfferPool extends EventEmitter<OfferPoolEvents> {
      */
     private createOffer;
     /**
-     * Poll for answers and delegate to OffererConnections
+     * Handle poll:answer event from PollingManager
+     * Called by Rondevu when a poll:answer event is received
+     */
+    handlePollAnswer(data: PollAnswerEvent): Promise<void>;
+    /**
+     * Handle poll:ice event from PollingManager
+     * Called by Rondevu when a poll:ice event is received
      */
-    private pollInternal;
+    handlePollIce(data: PollIceEvent): void;
     /**
      * Debug logging (only if debug enabled)
      */