@xtr-dev/rondevu-client 0.20.1 → 0.21.1

package/dist/core/polling-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * PollingManager - Centralized polling for WebRTC signaling
+ *
+ * Provides a single shared polling timer that emits events for:
+ * - poll:answer - When an offer receives an answer
+ * - poll:ice - When new ICE candidates are available
+ *
+ * Connections subscribe to these events and filter by offerId in their callbacks.
+ */
+import { EventEmitter } from 'eventemitter3';
+import { RondevuAPI, IceCandidate } from '../api/client.js';
+export interface PollAnswerEvent {
+    offerId: string;
+    answererId: string;
+    sdp: string;
+    answeredAt: number;
+}
+export interface PollIceEvent {
+    offerId: string;
+    candidates: IceCandidate[];
+}
+export interface PollingManagerEvents {
+    'poll:answer': (data: PollAnswerEvent) => void;
+    'poll:ice': (data: PollIceEvent) => void;
+    'poll:error': (error: Error) => void;
+    'poll:started': () => void;
+    'poll:stopped': () => void;
+}
+export interface PollingManagerOptions {
+    api: RondevuAPI;
+    intervalMs?: number;
+    debugEnabled?: boolean;
+}
+/**
+ * Centralized polling manager that emits global events
+ * Connections subscribe to events and filter by offerId
+ */
+export declare class PollingManager extends EventEmitter<PollingManagerEvents> {
+    private static readonly DEFAULT_INTERVAL_MS;
+    private readonly api;
+    private readonly intervalMs;
+    private readonly debugEnabled;
+    private pollingInterval;
+    private lastPollTimestamp;
+    private running;
+    constructor(options: PollingManagerOptions);
+    /**
+     * Start polling
+     */
+    start(): void;
+    /**
+     * Stop polling
+     */
+    stop(): void;
+    /**
+     * Check if polling is active
+     */
+    isRunning(): boolean;
+    /**
+     * Get the last poll timestamp
+     */
+    getLastPollTimestamp(): number;
+    /**
+     * Perform a single poll
+     */
+    private poll;
+    /**
+     * Debug logging
+     */
+    private debug;
+}

package/dist/core/polling-manager.js

@@ -0,0 +1,122 @@
+/**
+ * PollingManager - Centralized polling for WebRTC signaling
+ *
+ * Provides a single shared polling timer that emits events for:
+ * - poll:answer - When an offer receives an answer
+ * - poll:ice - When new ICE candidates are available
+ *
+ * Connections subscribe to these events and filter by offerId in their callbacks.
+ */
+import { EventEmitter } from 'eventemitter3';
+/**
+ * Centralized polling manager that emits global events
+ * Connections subscribe to events and filter by offerId
+ */
+export class PollingManager extends EventEmitter {
+    constructor(options) {
+        super();
+        this.pollingInterval = null;
+        this.lastPollTimestamp = 0;
+        this.running = false;
+        this.api = options.api;
+        this.intervalMs = options.intervalMs ?? PollingManager.DEFAULT_INTERVAL_MS;
+        this.debugEnabled = options.debugEnabled ?? false;
+    }
+    /**
+     * Start polling
+     */
+    start() {
+        if (this.running) {
+            this.debug('Already running');
+            return;
+        }
+        this.debug('Starting polling manager');
+        this.running = true;
+        // Poll immediately
+        this.poll();
+        // Start interval
+        this.pollingInterval = setInterval(() => {
+            this.poll();
+        }, this.intervalMs);
+        this.emit('poll:started');
+    }
+    /**
+     * Stop polling
+     */
+    stop() {
+        if (!this.running)
+            return;
+        this.debug('Stopping polling manager');
+        this.running = false;
+        if (this.pollingInterval) {
+            clearInterval(this.pollingInterval);
+            this.pollingInterval = null;
+        }
+        this.emit('poll:stopped');
+    }
+    /**
+     * Check if polling is active
+     */
+    isRunning() {
+        return this.running;
+    }
+    /**
+     * Get the last poll timestamp
+     */
+    getLastPollTimestamp() {
+        return this.lastPollTimestamp;
+    }
+    /**
+     * Perform a single poll
+     */
+    async poll() {
+        if (!this.running)
+            return;
+        try {
+            const result = await this.api.poll(this.lastPollTimestamp);
+            // Emit answer events
+            for (const answer of result.answers) {
+                this.debug(`Poll: answer for ${answer.offerId}`);
+                this.emit('poll:answer', {
+                    offerId: answer.offerId,
+                    answererId: answer.answererId,
+                    sdp: answer.sdp,
+                    answeredAt: answer.answeredAt,
+                });
+                // Update last poll timestamp
+                if (answer.answeredAt > this.lastPollTimestamp) {
+                    this.lastPollTimestamp = answer.answeredAt;
+                }
+            }
+            // Emit ICE candidate events (grouped by offerId)
+            for (const [offerId, candidates] of Object.entries(result.iceCandidates)) {
+                if (candidates.length > 0) {
+                    this.debug(`Poll: ${candidates.length} ICE candidates for ${offerId}`);
+                    this.emit('poll:ice', {
+                        offerId,
+                        candidates: candidates,
+                    });
+                    // Update last poll timestamp from candidates
+                    for (const candidate of candidates) {
+                        if (candidate.createdAt > this.lastPollTimestamp) {
+                            this.lastPollTimestamp = candidate.createdAt;
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            this.debug('Poll error:', error);
+            this.emit('poll:error', error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    /**
+     * Debug logging
+     */
+    debug(...args) {
+        if (this.debugEnabled) {
+            console.log('[PollingManager]', ...args);
+        }
+    }
+}
+PollingManager.DEFAULT_INTERVAL_MS = 1000;

package/dist/core/rondevu-errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Rondevu Error Classes
+ *
+ * Error hierarchy for the Rondevu client:
+ * - RondevuError (base)
+ *   - NetworkError (API/connectivity issues)
+ *   - ValidationError (invalid input/data)
+ *   - ConnectionError (WebRTC/ICE issues)
+ */
+/**
+ * Base error class for all Rondevu errors.
+ * Provides optional context object for debugging.
+ */
+export declare class RondevuError extends Error {
+    context?: Record<string, unknown> | undefined;
+    constructor(message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Network-related errors (API calls, connectivity)
+ *
+ * @example
+ * ```typescript
+ * throw new NetworkError('Failed to reach signaling server', {
+ *   url: 'https://api.ronde.vu',
+ *   status: 503
+ * })
+ * ```
+ */
+export declare class NetworkError extends RondevuError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Validation errors (invalid input, malformed data)
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid username format', {
+ *   username: 'invalid@user',
+ *   pattern: '^[a-z0-9-]{4,32}$'
+ * })
+ * ```
+ */
+export declare class ValidationError extends RondevuError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * WebRTC connection errors (peer connection failures, ICE issues)
+ *
+ * @example
+ * ```typescript
+ * throw new ConnectionError('ICE connection failed', {
+ *   iceState: 'failed',
+ *   offerId: 'abc123'
+ * })
+ * ```
+ */
+export declare class ConnectionError extends RondevuError {
+    constructor(message: string, context?: Record<string, unknown>);
+}

package/dist/core/rondevu-errors.js

@@ -0,0 +1,75 @@
+/**
+ * Rondevu Error Classes
+ *
+ * Error hierarchy for the Rondevu client:
+ * - RondevuError (base)
+ *   - NetworkError (API/connectivity issues)
+ *   - ValidationError (invalid input/data)
+ *   - ConnectionError (WebRTC/ICE issues)
+ */
+/**
+ * Base error class for all Rondevu errors.
+ * Provides optional context object for debugging.
+ */
+export class RondevuError extends Error {
+    constructor(message, context) {
+        super(message);
+        this.context = context;
+        this.name = 'RondevuError';
+        Object.setPrototypeOf(this, RondevuError.prototype);
+    }
+}
+/**
+ * Network-related errors (API calls, connectivity)
+ *
+ * @example
+ * ```typescript
+ * throw new NetworkError('Failed to reach signaling server', {
+ *   url: 'https://api.ronde.vu',
+ *   status: 503
+ * })
+ * ```
+ */
+export class NetworkError extends RondevuError {
+    constructor(message, context) {
+        super(message, context);
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+/**
+ * Validation errors (invalid input, malformed data)
+ *
+ * @example
+ * ```typescript
+ * throw new ValidationError('Invalid username format', {
+ *   username: 'invalid@user',
+ *   pattern: '^[a-z0-9-]{4,32}$'
+ * })
+ * ```
+ */
+export class ValidationError extends RondevuError {
+    constructor(message, context) {
+        super(message, context);
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+/**
+ * WebRTC connection errors (peer connection failures, ICE issues)
+ *
+ * @example
+ * ```typescript
+ * throw new ConnectionError('ICE connection failed', {
+ *   iceState: 'failed',
+ *   offerId: 'abc123'
+ * })
+ * ```
+ */
+export class ConnectionError extends RondevuError {
+    constructor(message, context) {
+        super(message, context);
+        this.name = 'ConnectionError';
+        Object.setPrototypeOf(this, ConnectionError.prototype);
+    }
+}

package/dist/core/rondevu-types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Rondevu Type Definitions
+ *
+ * Contains all public interfaces and types for the Rondevu client.
+ */
+import { Credential } from '../api/client.js';
+import { CryptoAdapter } from '../crypto/adapter.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
+import { ConnectionConfig } from '../connections/config.js';
+import { IceServerPreset } from './ice-config.js';
+/**
+ * Options for creating a Rondevu instance via Rondevu.connect()
+ */
+export interface RondevuOptions {
+    /** API URL (defaults to 'https://api.ronde.vu') */
+    apiUrl?: string;
+    /** Pre-existing credential (will generate if not provided) */
+    credential?: Credential;
+    /** Claim specific username (4-32 chars, alphanumeric + dashes + periods) */
+    username?: string;
+    /** Crypto adapter (defaults to WebCryptoAdapter) */
+    cryptoAdapter?: CryptoAdapter;
+    /** WebRTC adapter (defaults to BrowserWebRTCAdapter, use NodeWebRTCAdapter for Node.js) */
+    webrtcAdapter?: WebRTCAdapter;
+    /** ICE server preset name or custom RTCIceServer array */
+    iceServers?: IceServerPreset | RTCIceServer[];
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+/**
+ * Context returned by offer factory functions
+ */
+export interface OfferContext {
+    /** Optional data channel created for the offer */
+    dc?: RTCDataChannel;
+    /** The WebRTC offer SDP */
+    offer: RTCSessionDescriptionInit;
+}
+/**
+ * Factory function for creating WebRTC offers.
+ * Rondevu creates the RTCPeerConnection and passes it to the factory,
+ * allowing ICE candidate handlers to be set up before setLocalDescription() is called.
+ *
+ * @param pc - The RTCPeerConnection created by Rondevu (already configured with ICE servers)
+ * @returns Promise containing the data channel (optional) and offer SDP
+ */
+export type OfferFactory = (pc: RTCPeerConnection) => Promise<OfferContext>;
+/**
+ * Options for rondevu.offer() - publishing WebRTC offers
+ */
+export interface OfferOptions {
+    /** Tags for discovery (e.g., ["chat", "video"]) */
+    tags: string[];
+    /** Maximum number of concurrent offers to maintain */
+    maxOffers: number;
+    /** Custom offer creation (defaults to simple data channel) */
+    offerFactory?: OfferFactory;
+    /** Time-to-live for offers in milliseconds (default: 300000 = 5 minutes) */
+    ttl?: number;
+    /** Connection durability configuration */
+    connectionConfig?: Partial<ConnectionConfig>;
+    /** Auto-start filling offers (default: true). Set to false to manually call startFilling() */
+    autoStart?: boolean;
+}
+/**
+ * Handle returned by rondevu.offer() for controlling the offer lifecycle
+ */
+export interface OfferHandle {
+    /** Stop filling offers and close all connections */
+    cancel: () => void;
+}
+/**
+ * Context provided when a connection is established
+ */
+export interface ConnectionContext {
+    /** The underlying RTCPeerConnection */
+    pc: RTCPeerConnection;
+    /** The data channel for communication */
+    dc: RTCDataChannel;
+    /** Tags associated with this connection */
+    tags: string[];
+    /** The offer ID for this connection */
+    offerId: string;
+    /** Username of the connected peer */
+    peerUsername: string;
+}
+/**
+ * Options for rondevu.discover() - discovering available offers
+ */
+export interface DiscoverOptions {
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Offset for pagination (default: 0) */
+    offset?: number;
+}
+/**
+ * A discovered offer from the signaling server
+ */
+export interface DiscoveredOffer {
+    /** Unique offer identifier */
+    offerId: string;
+    /** Username of the offer publisher */
+    username: string;
+    /** Tags associated with this offer */
+    tags: string[];
+    /** The WebRTC offer SDP */
+    sdp: string;
+    /** Timestamp when the offer was created */
+    createdAt: number;
+    /** Timestamp when the offer expires */
+    expiresAt: number;
+}
+/**
+ * Result of a discover() call
+ */
+export interface DiscoverResult {
+    /** Array of discovered offers */
+    offers: DiscoveredOffer[];
+    /** Total count of matching offers */
+    count: number;
+    /** Limit used in the query */
+    limit: number;
+    /** Offset used in the query */
+    offset: number;
+}

package/dist/core/rondevu-types.js

@@ -0,0 +1,6 @@
+/**
+ * Rondevu Type Definitions
+ *
+ * Contains all public interfaces and types for the Rondevu client.
+ */
+export {};