@xtr-dev/rondevu-client 0.20.1 → 0.21.3

package/dist/core/offer-pool.js

@@ -2,7 +2,7 @@ import { EventEmitter } from 'eventemitter3';
 import { OffererConnection } from '../connections/offerer.js';
 import { AsyncLock } from '../utils/async-lock.js';
 /**
- * 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.
  */
@@ -13,19 +13,21 @@ export class OfferPool extends EventEmitter {
         this.activeConnections = new Map();
         this.fillLock = new AsyncLock();
         this.running = false;
-        this.pollingInterval = null;
-        this.lastPollTimestamp = 0;
         this.api = options.api;
-        this.serviceFqn = options.serviceFqn;
+        this.tags = options.tags;
+        this.ownerUsername = options.ownerUsername;
+        this.webrtcAdapter = options.webrtcAdapter;
         this.maxOffers = options.maxOffers;
         this.offerFactory = options.offerFactory;
         this.ttl = options.ttl;
         this.iceServers = options.iceServers;
+        this.iceTransportPolicy = options.iceTransportPolicy;
         this.connectionConfig = options.connectionConfig;
         this.debugEnabled = options.debugEnabled || false;
     }
     /**
-     * Start filling offers and polling for answers
+     * Start filling offers
+     * Polling is managed externally by Rondevu's PollingManager
      */
     async start() {
         if (this.running) {
@@ -36,23 +38,14 @@ export class OfferPool extends EventEmitter {
         this.running = true;
         // Fill initial offers
         await this.fillOffers();
-        // Start polling for answers
-        this.pollingInterval = setInterval(() => {
-            this.pollInternal();
-        }, OfferPool.POLLING_INTERVAL_MS);
     }
     /**
-     * Stop filling offers and polling
+     * Stop filling offers
      * Closes all active connections
      */
     stop() {
         this.debug('Stopping offer pool');
         this.running = false;
-        // Stop polling
-        if (this.pollingInterval) {
-            clearInterval(this.pollingInterval);
-            this.pollingInterval = null;
-        }
         // Close all active connections
         for (const [offerId, connection] of this.activeConnections.entries()) {
             if (connection.isRotating()) {
@@ -115,16 +108,30 @@ export class OfferPool extends EventEmitter {
         });
     }
     /**
-     * Create a new offer for rotation (reuses existing creation logic)
-     * Similar to createOffer() but only creates the offer, doesn't create connection
+     * 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
      */
-    async createNewOfferForRotation() {
+    async createOfferAndPublish() {
         const rtcConfig = {
-            iceServers: this.iceServers
+            iceServers: this.iceServers,
+            iceTransportPolicy: this.iceTransportPolicy,
+        };
+        // 1. Create RTCPeerConnection using adapter
+        const pc = this.webrtcAdapter.createPeerConnection(rtcConfig);
+        // Collect ICE candidates during offer creation
+        // We need to set this up BEFORE setLocalDescription is called
+        const collectedCandidates = [];
+        pc.onicecandidate = event => {
+            if (event.candidate) {
+                collectedCandidates.push({
+                    candidate: event.candidate.candidate,
+                    sdpMLineIndex: event.candidate.sdpMLineIndex,
+                    sdpMid: event.candidate.sdpMid,
+                });
+            }
         };
-        this.debug('Creating new offer for rotation...');
-        // 1. Create RTCPeerConnection
-        const pc = new RTCPeerConnection(rtcConfig);
         // 2. Call the factory to create offer
         let dc;
         let offer;
@@ -138,51 +145,45 @@ export class OfferPool extends EventEmitter {
             throw err;
         }
         // 3. Publish to server to get offerId
-        const result = await this.api.publishService({
-            serviceFqn: this.serviceFqn,
+        const result = await this.api.publish({
+            tags: this.tags,
             offers: [{ sdp: offer.sdp }],
             ttl: this.ttl,
         });
-        const newOfferId = result.offers[0].offerId;
-        this.debug(`New offer created for rotation: ${newOfferId}`);
-        return { newOfferId, pc, dc };
+        const offerId = result.offers[0].offerId;
+        // 4. Send any ICE candidates we've already collected
+        if (collectedCandidates.length > 0) {
+            this.debug(`Sending ${collectedCandidates.length} early ICE candidates for offer ${offerId}`);
+            this.api.addOfferIceCandidates(offerId, collectedCandidates).catch(err => {
+                this.debug('Failed to send early ICE candidates:', err);
+            });
+        }
+        return { offerId, pc, dc };
+    }
+    /**
+     * Create a new offer for rotation (reuses existing creation logic)
+     * Similar to createOffer() but only creates the offer, doesn't create connection
+     */
+    async createNewOfferForRotation() {
+        this.debug('Creating new offer for rotation...');
+        const { offerId, pc, dc } = await this.createOfferAndPublish();
+        this.debug(`New offer created for rotation: ${offerId}`);
+        return { newOfferId: offerId, pc, dc };
     }
     /**
      * Create a single offer and publish it to the server
      */
     async createOffer() {
-        const rtcConfig = {
-            iceServers: this.iceServers
-        };
         this.debug('Creating new offer...');
-        // 1. Create RTCPeerConnection
-        const pc = new RTCPeerConnection(rtcConfig);
-        // 2. Call the factory to create offer
-        let dc;
-        let offer;
-        try {
-            const factoryResult = await this.offerFactory(pc);
-            dc = factoryResult.dc;
-            offer = factoryResult.offer;
-        }
-        catch (err) {
-            pc.close();
-            throw err;
-        }
-        // 3. Publish to server to get offerId
-        const result = await this.api.publishService({
-            serviceFqn: this.serviceFqn,
-            offers: [{ sdp: offer.sdp }],
-            ttl: this.ttl,
-        });
-        const offerId = result.offers[0].offerId;
-        // 4. Create OffererConnection instance
+        const { offerId, pc, dc } = await this.createOfferAndPublish();
+        // Create OffererConnection instance
         const connection = new OffererConnection({
             api: this.api,
-            serviceFqn: this.serviceFqn,
+            ownerUsername: this.ownerUsername,
             offerId,
             pc,
             dc,
+            webrtcAdapter: this.webrtcAdapter,
             config: {
                 ...this.connectionConfig,
                 debug: this.debugEnabled,
@@ -195,7 +196,14 @@ export class OfferPool extends EventEmitter {
         });
         connection.on('failed', async (error) => {
             const currentOfferId = connection.getOfferId();
-            this.debug(`Connection failed for offer ${currentOfferId}, rotating...`);
+            this.debug(`Connection failed for offer ${currentOfferId}`);
+            // Double-check connection state before rotating
+            // (polling events may have already recovered the connection)
+            if (connection.getState() !== 'failed') {
+                this.debug(`Connection ${currentOfferId} recovered, skipping rotation`);
+                return;
+            }
+            this.debug(`Proceeding with rotation for offer ${currentOfferId}`);
             try {
                 // Create new offer and rebind existing connection
                 const { newOfferId, pc, dc } = await this.createNewOfferForRotation();
@@ -225,35 +233,42 @@ export class OfferPool extends EventEmitter {
         // Initialize the connection
         await connection.initialize();
         this.debug(`Offer created: ${offerId}`);
-        this.emit('offer:created', offerId, this.serviceFqn);
+        this.emit('offer:created', offerId, this.tags);
     }
     /**
-     * Poll for answers and delegate to OffererConnections
+     * Handle poll:answer event from PollingManager
+     * Called by Rondevu when a poll:answer event is received
      */
-    async pollInternal() {
+    async handlePollAnswer(data) {
         if (!this.running)
             return;
-        try {
-            const result = await this.api.poll(this.lastPollTimestamp);
-            // Process answers - delegate to OffererConnections
-            for (const answer of result.answers) {
-                const connection = this.activeConnections.get(answer.offerId);
-                if (connection) {
-                    try {
-                        await connection.processAnswer(answer.sdp, answer.answererId);
-                        this.lastPollTimestamp = Math.max(this.lastPollTimestamp, answer.answeredAt);
-                        // Create replacement offer
-                        this.fillOffers();
-                    }
-                    catch (err) {
-                        this.debug(`Failed to process answer for offer ${answer.offerId}:`, err);
-                    }
-                }
+        const connection = this.activeConnections.get(data.offerId);
+        if (connection) {
+            this.debug(`Processing answer for offer ${data.offerId}`);
+            try {
+                await connection.processAnswer(data.sdp, data.answererId);
+                // Create replacement offer
+                this.fillOffers();
+            }
+            catch (err) {
+                this.debug(`Failed to process answer for offer ${data.offerId}:`, err);
             }
         }
-        catch (err) {
-            console.error('[OfferPool] Polling error:', err);
+        // Silently ignore answers for offers we don't have - they may be for other connections
+    }
+    /**
+     * Handle poll:ice event from PollingManager
+     * Called by Rondevu when a poll:ice event is received
+     */
+    handlePollIce(data) {
+        if (!this.running)
+            return;
+        const connection = this.activeConnections.get(data.offerId);
+        if (connection) {
+            this.debug(`Processing ${data.candidates.length} ICE candidates for offer ${data.offerId}`);
+            connection.handleRemoteIceCandidates(data.candidates);
         }
+        // Silently ignore ICE candidates for offers we don't have
     }
     /**
      * Debug logging (only if debug enabled)
@@ -264,4 +279,3 @@ export class OfferPool extends EventEmitter {
         }
     }
 }
-OfferPool.POLLING_INTERVAL_MS = 1000;

package/dist/core/peer.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Peer - Clean DX wrapper for peer-to-peer connections
+ *
+ * Provides a simple interface for connecting to a peer by tags/username,
+ * with automatic reconnection and message buffering.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { RondevuAPI } from '../api/client.js';
+import { AnswererConnection } from '../connections/answerer.js';
+import { ConnectionConfig } from '../connections/config.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
+/**
+ * Simplified peer state (maps from ConnectionState)
+ */
+export type PeerState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'failed' | 'closed';
+/**
+ * Event map for Peer
+ */
+export interface PeerEventMap {
+    /** Emitted when connection state changes */
+    state: [state: PeerState, previousState: PeerState];
+    /** Emitted when connection is established */
+    open: [];
+    /** Emitted when connection is closed */
+    close: [reason?: string];
+    /** Emitted when a message is received */
+    message: [data: string | ArrayBuffer | Blob];
+    /** Emitted when an error occurs */
+    error: [error: Error];
+    /** Emitted when reconnection is attempted */
+    reconnecting: [attempt: number, maxAttempts: number];
+}
+export type PeerEventName = keyof PeerEventMap;
+/**
+ * Options for creating a Peer connection
+ */
+export interface PeerOptions {
+    /** Tags to match for peer discovery */
+    tags: string[];
+    /** Optional: connect to specific username */
+    username?: string;
+    /** Optional: custom RTC configuration */
+    rtcConfig?: RTCConfiguration;
+    /** Optional: connection behavior configuration */
+    config?: Partial<ConnectionConfig>;
+}
+/**
+ * Internal options passed from Rondevu
+ */
+export interface PeerInternalOptions extends PeerOptions {
+    api: RondevuAPI;
+    iceServers: RTCIceServer[];
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    webrtcAdapter?: WebRTCAdapter;
+    debug?: boolean;
+}
+/**
+ * Peer - A clean interface for peer-to-peer connections
+ *
+ * @example
+ * ```typescript
+ * const peer = await rondevu.peer({
+ *   username: 'alice',
+ *   tags: ['chat']
+ * })
+ *
+ * peer.on('open', () => {
+ *   console.log('Connected to', peer.peerUsername)
+ *   peer.send('Hello!')
+ * })
+ *
+ * peer.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * peer.on('state', (state) => {
+ *   console.log('Connection state:', state)
+ * })
+ *
+ * // Access underlying WebRTC objects
+ * const pc = peer.peerConnection  // RTCPeerConnection
+ * const dc = peer.dataChannel     // RTCDataChannel
+ * ```
+ */
+export declare class Peer extends EventEmitter<PeerEventMap> {
+    private connection;
+    private api;
+    private tags;
+    private targetUsername?;
+    private iceServers;
+    private iceTransportPolicy?;
+    private webrtcAdapter?;
+    private connectionConfig?;
+    private debugEnabled;
+    private _state;
+    private _peerUsername;
+    private _offerId;
+    constructor(options: PeerInternalOptions);
+    /**
+     * Initialize the peer connection (called internally by Rondevu.peer())
+     */
+    initialize(): Promise<void>;
+    /**
+     * Setup event handlers to forward from AnswererConnection
+     */
+    private setupEventHandlers;
+    /**
+     * Map internal ConnectionState to simplified PeerState
+     */
+    private mapState;
+    /**
+     * Current connection state
+     */
+    get state(): PeerState;
+    /**
+     * Username of the connected peer
+     */
+    get peerUsername(): string;
+    /**
+     * The offer ID being used for this connection
+     */
+    get offerId(): string;
+    /**
+     * Tags used for discovery
+     */
+    get peerTags(): string[];
+    /**
+     * The underlying RTCPeerConnection (null if not connected)
+     */
+    get peerConnection(): RTCPeerConnection | null;
+    /**
+     * The underlying RTCDataChannel (null if not connected)
+     */
+    get dataChannel(): RTCDataChannel | null;
+    /**
+     * Whether the peer is currently connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Send a message to the peer
+     * Messages are buffered if not connected (when buffering is enabled)
+     *
+     * @param data - String, ArrayBuffer, or Blob to send
+     */
+    send(data: string | ArrayBuffer | Blob): void;
+    /**
+     * Close the peer connection
+     */
+    close(): void;
+    /**
+     * Get the underlying AnswererConnection for advanced use cases
+     */
+    getConnection(): AnswererConnection | null;
+    /**
+     * Debug logging
+     */
+    private debug;
+}

package/dist/core/peer.js

@@ -0,0 +1,254 @@
+/**
+ * Peer - Clean DX wrapper for peer-to-peer connections
+ *
+ * Provides a simple interface for connecting to a peer by tags/username,
+ * with automatic reconnection and message buffering.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { AnswererConnection } from '../connections/answerer.js';
+import { ConnectionState } from '../connections/events.js';
+/**
+ * Peer - A clean interface for peer-to-peer connections
+ *
+ * @example
+ * ```typescript
+ * const peer = await rondevu.peer({
+ *   username: 'alice',
+ *   tags: ['chat']
+ * })
+ *
+ * peer.on('open', () => {
+ *   console.log('Connected to', peer.peerUsername)
+ *   peer.send('Hello!')
+ * })
+ *
+ * peer.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * peer.on('state', (state) => {
+ *   console.log('Connection state:', state)
+ * })
+ *
+ * // Access underlying WebRTC objects
+ * const pc = peer.peerConnection  // RTCPeerConnection
+ * const dc = peer.dataChannel     // RTCDataChannel
+ * ```
+ */
+export class Peer extends EventEmitter {
+    constructor(options) {
+        super();
+        this.connection = null;
+        this._state = 'connecting';
+        this._peerUsername = '';
+        this._offerId = '';
+        this.api = options.api;
+        this.tags = options.tags;
+        this.targetUsername = options.username;
+        this.iceServers = options.iceServers;
+        this.iceTransportPolicy = options.iceTransportPolicy;
+        this.webrtcAdapter = options.webrtcAdapter;
+        this.connectionConfig = options.config;
+        this.debugEnabled = options.debug || false;
+    }
+    /**
+     * Initialize the peer connection (called internally by Rondevu.peer())
+     */
+    async initialize() {
+        this.debug('Initializing peer connection');
+        this.debug(`Tags: ${this.tags.join(', ')}${this.targetUsername ? `, username: ${this.targetUsername}` : ''}`);
+        // Discover offers
+        const result = (await this.api.discover({
+            tags: this.tags,
+            limit: 100,
+        }));
+        if (!result.offers || result.offers.length === 0) {
+            throw new Error(`No peers found for tags: ${this.tags.join(', ')}`);
+        }
+        // Filter by username if specified
+        let availableOffers = result.offers;
+        if (this.targetUsername) {
+            availableOffers = result.offers.filter((o) => o.username === this.targetUsername);
+            if (availableOffers.length === 0) {
+                throw new Error(`No peers found for tags: ${this.tags.join(', ')} from @${this.targetUsername}`);
+            }
+        }
+        // Pick a random offer
+        const offer = availableOffers[Math.floor(Math.random() * availableOffers.length)];
+        this._peerUsername = offer.username;
+        this._offerId = offer.offerId;
+        this.debug(`Selected offer ${offer.offerId} from @${offer.username}`);
+        // Create the underlying AnswererConnection
+        this.connection = new AnswererConnection({
+            api: this.api,
+            ownerUsername: offer.username,
+            tags: offer.tags,
+            offerId: offer.offerId,
+            offerSdp: offer.sdp,
+            rtcConfig: {
+                iceServers: this.iceServers,
+                iceTransportPolicy: this.iceTransportPolicy,
+            },
+            webrtcAdapter: this.webrtcAdapter,
+            config: {
+                ...this.connectionConfig,
+                debug: this.debugEnabled,
+            },
+        });
+        // Wire up events
+        this.setupEventHandlers();
+        // Start connection
+        await this.connection.initialize();
+    }
+    /**
+     * Setup event handlers to forward from AnswererConnection
+     */
+    setupEventHandlers() {
+        if (!this.connection)
+            return;
+        // Map ConnectionState to PeerState
+        this.connection.on('state:changed', ({ oldState, newState, reason }) => {
+            const mappedOld = this.mapState(oldState);
+            const mappedNew = this.mapState(newState);
+            if (mappedOld !== mappedNew) {
+                this._state = mappedNew;
+                this.emit('state', mappedNew, mappedOld);
+            }
+        });
+        // Forward connection events
+        this.connection.on('connected', () => {
+            this._state = 'connected';
+            this.emit('open');
+        });
+        this.connection.on('closed', reason => {
+            this._state = 'closed';
+            this.emit('close', reason);
+        });
+        this.connection.on('failed', error => {
+            this._state = 'failed';
+            this.emit('error', error);
+        });
+        // Forward message events
+        this.connection.on('message', data => {
+            this.emit('message', data);
+        });
+        // Forward reconnection events
+        this.connection.on('reconnect:scheduled', info => {
+            this._state = 'reconnecting';
+            this.emit('reconnecting', info.attempt, info.maxAttempts);
+        });
+        this.connection.on('reconnect:success', () => {
+            // State will be updated by 'connected' event
+        });
+        this.connection.on('reconnect:failed', error => {
+            this.emit('error', error);
+        });
+    }
+    /**
+     * Map internal ConnectionState to simplified PeerState
+     */
+    mapState(state) {
+        switch (state) {
+            case ConnectionState.INITIALIZING:
+            case ConnectionState.GATHERING:
+            case ConnectionState.SIGNALING:
+            case ConnectionState.CHECKING:
+            case ConnectionState.CONNECTING:
+                return 'connecting';
+            case ConnectionState.CONNECTED:
+                return 'connected';
+            case ConnectionState.DISCONNECTED:
+                return 'disconnected';
+            case ConnectionState.RECONNECTING:
+                return 'reconnecting';
+            case ConnectionState.FAILED:
+                return 'failed';
+            case ConnectionState.CLOSED:
+                return 'closed';
+            default:
+                return 'connecting';
+        }
+    }
+    // ========================================
+    // Public Properties
+    // ========================================
+    /**
+     * Current connection state
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Username of the connected peer
+     */
+    get peerUsername() {
+        return this._peerUsername;
+    }
+    /**
+     * The offer ID being used for this connection
+     */
+    get offerId() {
+        return this._offerId;
+    }
+    /**
+     * Tags used for discovery
+     */
+    get peerTags() {
+        return this.tags;
+    }
+    /**
+     * The underlying RTCPeerConnection (null if not connected)
+     */
+    get peerConnection() {
+        return this.connection?.getPeerConnection() ?? null;
+    }
+    /**
+     * The underlying RTCDataChannel (null if not connected)
+     */
+    get dataChannel() {
+        return this.connection?.getDataChannel() ?? null;
+    }
+    /**
+     * Whether the peer is currently connected
+     */
+    get isConnected() {
+        return this._state === 'connected';
+    }
+    // ========================================
+    // Public Methods
+    // ========================================
+    /**
+     * Send a message to the peer
+     * Messages are buffered if not connected (when buffering is enabled)
+     *
+     * @param data - String, ArrayBuffer, or Blob to send
+     */
+    send(data) {
+        if (!this.connection) {
+            throw new Error('Peer not initialized');
+        }
+        this.connection.send(data);
+    }
+    /**
+     * Close the peer connection
+     */
+    close() {
+        this.debug('Closing peer connection');
+        this.connection?.close();
+        this._state = 'closed';
+    }
+    /**
+     * Get the underlying AnswererConnection for advanced use cases
+     */
+    getConnection() {
+        return this.connection;
+    }
+    /**
+     * Debug logging
+     */
+    debug(...args) {
+        if (this.debugEnabled) {
+            console.log('[Peer]', ...args);
+        }
+    }
+}