@xtr-dev/rondevu-client 0.18.10 → 0.20.1

package/dist/core/rondevu.js

@@ -0,0 +1,600 @@
+import { RondevuAPI } from '../api/client.js';
+import { EventEmitter } from 'eventemitter3';
+import { AnswererConnection } from '../connections/answerer.js';
+import { OfferPool } from './offer-pool.js';
+// ICE server presets
+export const ICE_SERVER_PRESETS = {
+    'ipv4-turn': [
+        { 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: 'webrtcuser',
+            credential: 'supersecretpassword'
+        }
+    ],
+    'hostname-turns': [
+        { urls: 'stun:turn.share.fish:3478' },
+        {
+            urls: [
+                'turns:turn.share.fish:5349?transport=tcp',
+                'turns:turn.share.fish:5349?transport=udp',
+                'turn:turn.share.fish:3478?transport=tcp',
+                'turn:turn.share.fish:3478?transport=udp',
+            ],
+            username: 'webrtcuser',
+            credential: 'supersecretpassword'
+        }
+    ],
+    'google-stun': [
+        { urls: 'stun:stun.l.google.com:19302' },
+        { urls: 'stun:stun1.l.google.com:19302' }
+    ],
+    'relay-only': [
+        { 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: 'webrtcuser',
+            credential: 'supersecretpassword',
+            // @ts-expect-error - iceTransportPolicy is valid but not in RTCIceServer type
+            iceTransportPolicy: 'relay'
+        }
+    ]
+};
+/**
+ * Base error class for Rondevu errors
+ */
+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)
+ */
+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)
+ */
+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)
+ */
+export class ConnectionError extends RondevuError {
+    constructor(message, context) {
+        super(message, context);
+        this.name = 'ConnectionError';
+        Object.setPrototypeOf(this, ConnectionError.prototype);
+    }
+}
+/**
+ * Rondevu - Complete WebRTC signaling client with durable connections
+ *
+ * v1.0.0 introduces breaking changes:
+ * - connectToService() now returns AnswererConnection instead of ConnectionContext
+ * - Automatic reconnection and message buffering built-in
+ * - Connection objects expose .send() method instead of raw DataChannel
+ * - Rich event system for connection lifecycle (connected, disconnected, reconnecting, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Create and initialize Rondevu instance with preset ICE servers
+ * const rondevu = await Rondevu.connect({
+ *   apiUrl: 'https://signal.example.com',
+ *   username: 'alice',
+ *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
+ * })
+ *
+ * // Publish a service with automatic offer management
+ * await rondevu.publishService({
+ *   service: 'chat:2.0.0',
+ *   maxOffers: 5  // Maintain up to 5 concurrent offers
+ * })
+ *
+ * // Start accepting connections (auto-fills offers and polls)
+ * await rondevu.startFilling()
+ *
+ * // Listen for connections (v1.0.0 API)
+ * rondevu.on('connection:opened', (offerId, connection) => {
+ *   connection.on('connected', () => console.log('Connected!'))
+ *   connection.on('message', (data) => console.log('Received:', data))
+ *   connection.send('Hello!')
+ * })
+ *
+ * // Connect to a service (v1.0.0 - returns AnswererConnection)
+ * const connection = await rondevu.connectToService({
+ *   serviceFqn: 'chat:2.0.0@bob'
+ * })
+ *
+ * connection.on('connected', () => {
+ *   console.log('Connected!')
+ *   connection.send('Hello!')
+ * })
+ *
+ * connection.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * connection.on('reconnecting', (attempt) => {
+ *   console.log(`Reconnecting, attempt ${attempt}`)
+ * })
+ * ```
+ */
+export class Rondevu extends EventEmitter {
+    constructor(apiUrl, username, keypair, api, iceServers, cryptoAdapter, batchingOptions, debugEnabled = false, rtcPeerConnection, rtcIceCandidate) {
+        super();
+        this.usernameClaimed = false;
+        // Service management
+        this.currentService = null;
+        this.offerPool = null;
+        this.apiUrl = apiUrl;
+        this.username = username;
+        this.keypair = keypair;
+        this.api = api;
+        this.iceServers = iceServers;
+        this.cryptoAdapter = cryptoAdapter;
+        this.batchingOptions = batchingOptions;
+        this.debugEnabled = debugEnabled;
+        this.rtcPeerConnection = rtcPeerConnection;
+        this.rtcIceCandidate = rtcIceCandidate;
+        this.debug('Instance created:', {
+            username: this.username,
+            publicKey: this.keypair.publicKey,
+            hasIceServers: iceServers.length > 0,
+            batchingEnabled: batchingOptions !== false
+        });
+    }
+    /**
+     * Internal debug logging - only logs if debug mode is enabled
+     */
+    debug(message, ...args) {
+        if (this.debugEnabled) {
+            console.log(`[Rondevu] ${message}`, ...args);
+        }
+    }
+    /**
+     * Create and initialize a Rondevu client
+     *
+     * @example
+     * ```typescript
+     * const rondevu = await Rondevu.connect({
+     *   apiUrl: 'https://api.ronde.vu',
+     *   username: 'alice'
+     * })
+     * ```
+     */
+    static async connect(options) {
+        const username = options.username || Rondevu.generateAnonymousUsername();
+        // Apply WebRTC polyfills to global scope if provided (Node.js environments)
+        if (options.rtcPeerConnection) {
+            globalThis.RTCPeerConnection = options.rtcPeerConnection;
+        }
+        if (options.rtcIceCandidate) {
+            globalThis.RTCIceCandidate = options.rtcIceCandidate;
+        }
+        // Handle preset string or custom array
+        let iceServers;
+        if (typeof options.iceServers === 'string') {
+            iceServers = ICE_SERVER_PRESETS[options.iceServers];
+        }
+        else {
+            iceServers = options.iceServers || [
+                { urls: 'stun:stun.l.google.com:19302' }
+            ];
+        }
+        if (options.debug) {
+            console.log('[Rondevu] Connecting:', {
+                username,
+                hasKeypair: !!options.keypair,
+                iceServers: iceServers.length,
+                batchingEnabled: options.batching !== false
+            });
+        }
+        // Generate keypair if not provided
+        let keypair = options.keypair;
+        if (!keypair) {
+            if (options.debug)
+                console.log('[Rondevu] Generating new keypair...');
+            keypair = await RondevuAPI.generateKeypair(options.cryptoAdapter);
+            if (options.debug)
+                console.log('[Rondevu] Generated keypair, publicKey:', keypair.publicKey);
+        }
+        else {
+            if (options.debug)
+                console.log('[Rondevu] Using existing keypair, publicKey:', keypair.publicKey);
+        }
+        // Create API instance
+        const api = new RondevuAPI(options.apiUrl, username, keypair, options.cryptoAdapter, options.batching);
+        if (options.debug)
+            console.log('[Rondevu] Created API instance');
+        return new Rondevu(options.apiUrl, username, keypair, api, iceServers, options.cryptoAdapter, options.batching, options.debug || false, options.rtcPeerConnection, options.rtcIceCandidate);
+    }
+    /**
+     * Generate an anonymous username with timestamp and random component
+     */
+    static generateAnonymousUsername() {
+        const timestamp = Date.now().toString(36);
+        const random = Array.from(crypto.getRandomValues(new Uint8Array(3)))
+            .map(b => b.toString(16).padStart(2, '0')).join('');
+        return `anon-${timestamp}-${random}`;
+    }
+    // ============================================
+    // Username Management
+    // ============================================
+    /**
+     * Check if username has been claimed (checks with server)
+     */
+    async isUsernameClaimed() {
+        try {
+            const claimed = await this.api.isUsernameClaimed();
+            // Update internal flag to match server state
+            this.usernameClaimed = claimed;
+            return claimed;
+        }
+        catch (err) {
+            console.error('Failed to check username claim status:', err);
+            return false;
+        }
+    }
+    // ============================================
+    // Service Publishing
+    // ============================================
+    /**
+     * Default offer factory - creates a simple data channel connection
+     * The RTCPeerConnection is created by Rondevu and passed in
+     */
+    async defaultOfferFactory(pc) {
+        const dc = pc.createDataChannel('default');
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        return { dc, offer };
+    }
+    /**
+     * Publish a service with automatic offer management
+     * Call startFilling() to begin accepting connections
+     *
+     * @example
+     * ```typescript
+     * await rondevu.publishService({
+     *   service: 'chat:2.0.0',
+     *   maxOffers: 5,
+     *   connectionConfig: {
+     *     reconnectEnabled: true,
+     *     bufferEnabled: true
+     *   }
+     * })
+     * await rondevu.startFilling()
+     * ```
+     */
+    async publishService(options) {
+        const { service, maxOffers, offerFactory, ttl, connectionConfig } = options;
+        this.currentService = service;
+        this.connectionConfig = connectionConfig;
+        // Auto-append username to service
+        const serviceFqn = `${service}@${this.username}`;
+        this.debug(`Publishing service: ${service} with maxOffers: ${maxOffers}`);
+        // Create OfferPool (but don't start it yet - call startFilling() to begin)
+        this.offerPool = new OfferPool({
+            api: this.api,
+            serviceFqn,
+            maxOffers,
+            offerFactory: offerFactory || this.defaultOfferFactory.bind(this),
+            ttl: ttl || Rondevu.DEFAULT_TTL_MS,
+            iceServers: this.iceServers,
+            connectionConfig,
+            debugEnabled: this.debugEnabled,
+        });
+        // Forward events from OfferPool
+        this.offerPool.on('connection:opened', (offerId, connection) => {
+            this.emit('connection:opened', offerId, connection);
+        });
+        this.offerPool.on('offer:created', (offerId, serviceFqn) => {
+            this.emit('offer:created', offerId, serviceFqn);
+        });
+        this.offerPool.on('connection:rotated', (oldOfferId, newOfferId, connection) => {
+            this.emit('connection:rotated', oldOfferId, newOfferId, connection);
+        });
+        this.usernameClaimed = true;
+    }
+    /**
+     * Start filling offers and polling for answers/ICE
+     * Call this after publishService() to begin accepting connections
+     */
+    async startFilling() {
+        if (!this.offerPool) {
+            throw new Error('No service published. Call publishService() first.');
+        }
+        this.debug('Starting offer filling and polling');
+        await this.offerPool.start();
+    }
+    /**
+     * Stop filling offers and polling
+     * Closes all active peer connections
+     */
+    stopFilling() {
+        this.debug('Stopping offer filling and polling');
+        this.offerPool?.stop();
+    }
+    /**
+     * Get the count of active offers
+     * @returns Number of active offers
+     */
+    getOfferCount() {
+        return this.offerPool?.getOfferCount() ?? 0;
+    }
+    /**
+     * Check if an offer is currently connected
+     * @param offerId - The offer ID to check
+     * @returns True if the offer exists and is connected
+     */
+    isConnected(offerId) {
+        return this.offerPool?.isConnected(offerId) ?? false;
+    }
+    /**
+     * Disconnect all active offers
+     * Similar to stopFilling() but doesn't stop the polling/filling process
+     */
+    disconnectAll() {
+        this.debug('Disconnecting all offers');
+        this.offerPool?.disconnectAll();
+    }
+    /**
+     * Get the current service status
+     * @returns Object with service state information
+     */
+    getServiceStatus() {
+        return {
+            active: this.currentService !== null,
+            offerCount: this.offerPool?.getOfferCount() ?? 0
+        };
+    }
+    /**
+     * Resolve the full service FQN from various input options
+     * Supports direct FQN, service+username, or service discovery
+     */
+    async resolveServiceFqn(options) {
+        const { serviceFqn, service, username } = options;
+        if (serviceFqn) {
+            return serviceFqn;
+        }
+        else if (service && username) {
+            return `${service}@${username}`;
+        }
+        else if (service) {
+            // Discovery mode - get random service
+            this.debug(`Discovering service: ${service}`);
+            const discovered = await this.findService(service);
+            return discovered.serviceFqn;
+        }
+        else {
+            throw new Error('Either serviceFqn or service must be provided');
+        }
+    }
+    /**
+     * Connect to a service (answerer side) - v1.0.0 API
+     * Returns an AnswererConnection with automatic reconnection and buffering
+     *
+     * BREAKING CHANGE: This now returns AnswererConnection instead of ConnectionContext
+     *
+     * @example
+     * ```typescript
+     * // Connect to specific user
+     * const connection = await rondevu.connectToService({
+     *   serviceFqn: 'chat:2.0.0@alice',
+     *   connectionConfig: {
+     *     reconnectEnabled: true,
+     *     bufferEnabled: true
+     *   }
+     * })
+     *
+     * connection.on('connected', () => {
+     *   console.log('Connected!')
+     *   connection.send('Hello!')
+     * })
+     *
+     * connection.on('message', (data) => {
+     *   console.log('Received:', data)
+     * })
+     *
+     * connection.on('reconnecting', (attempt) => {
+     *   console.log(`Reconnecting, attempt ${attempt}`)
+     * })
+     *
+     * // Discover random service
+     * const connection = await rondevu.connectToService({
+     *   service: 'chat:2.0.0'
+     * })
+     * ```
+     */
+    async connectToService(options) {
+        const { rtcConfig, connectionConfig } = options;
+        // Validate inputs
+        if (options.serviceFqn !== undefined && typeof options.serviceFqn === 'string' && !options.serviceFqn.trim()) {
+            throw new Error('serviceFqn cannot be empty');
+        }
+        if (options.service !== undefined && typeof options.service === 'string' && !options.service.trim()) {
+            throw new Error('service cannot be empty');
+        }
+        if (options.username !== undefined && typeof options.username === 'string' && !options.username.trim()) {
+            throw new Error('username cannot be empty');
+        }
+        // Determine the full service FQN
+        const fqn = await this.resolveServiceFqn(options);
+        this.debug(`Connecting to service: ${fqn}`);
+        // Get service offer
+        const serviceData = await this.api.getService(fqn);
+        this.debug(`Found service from @${serviceData.username}`);
+        // Create RTCConfiguration
+        const rtcConfiguration = rtcConfig || {
+            iceServers: this.iceServers
+        };
+        // Create AnswererConnection
+        const connection = new AnswererConnection({
+            api: this.api,
+            serviceFqn: serviceData.serviceFqn,
+            offerId: serviceData.offerId,
+            offerSdp: serviceData.sdp,
+            rtcConfig: rtcConfiguration,
+            config: {
+                ...connectionConfig,
+                debug: this.debugEnabled,
+            },
+        });
+        // Initialize the connection
+        await connection.initialize();
+        return connection;
+    }
+    // ============================================
+    // Service Discovery
+    // ============================================
+    /**
+     * Find a service - unified discovery method
+     *
+     * @param serviceFqn - Service identifier (e.g., 'chat:1.0.0' or 'chat:1.0.0@alice')
+     * @param options - Discovery options
+     *
+     * @example
+     * ```typescript
+     * // Direct lookup (has username)
+     * const service = await rondevu.findService('chat:1.0.0@alice')
+     *
+     * // Random discovery (no username)
+     * const service = await rondevu.findService('chat:1.0.0')
+     *
+     * // Paginated discovery
+     * const result = await rondevu.findService('chat:1.0.0', {
+     *   mode: 'paginated',
+     *   limit: 20,
+     *   offset: 0
+     * })
+     * ```
+     */
+    async findService(serviceFqn, options) {
+        const { mode, limit = 10, offset = 0 } = options || {};
+        // Auto-detect mode if not specified
+        const hasUsername = serviceFqn.includes('@');
+        const effectiveMode = mode || (hasUsername ? 'direct' : 'random');
+        if (effectiveMode === 'paginated') {
+            return await this.api.getService(serviceFqn, { limit, offset });
+        }
+        else {
+            // Both 'direct' and 'random' use the same API call
+            return await this.api.getService(serviceFqn);
+        }
+    }
+    // ============================================
+    // WebRTC Signaling
+    // ============================================
+    /**
+     * Post answer SDP to specific offer
+     */
+    async postOfferAnswer(serviceFqn, offerId, sdp) {
+        await this.api.answerOffer(serviceFqn, offerId, sdp);
+        return { success: true, offerId };
+    }
+    /**
+     * Get answer SDP (offerer polls this)
+     */
+    async getOfferAnswer(serviceFqn, offerId) {
+        return await this.api.getOfferAnswer(serviceFqn, offerId);
+    }
+    /**
+     * Combined polling for answers and ICE candidates
+     * Returns all answered offers and ICE candidates for all peer's offers since timestamp
+     */
+    async poll(since) {
+        return await this.api.poll(since);
+    }
+    /**
+     * Add ICE candidates to specific offer
+     */
+    async addOfferIceCandidates(serviceFqn, offerId, candidates) {
+        return await this.api.addOfferIceCandidates(serviceFqn, offerId, candidates);
+    }
+    /**
+     * Get ICE candidates for specific offer (with polling support)
+     */
+    async getOfferIceCandidates(serviceFqn, offerId, since = 0) {
+        return await this.api.getOfferIceCandidates(serviceFqn, offerId, since);
+    }
+    // ============================================
+    // Utility Methods
+    // ============================================
+    /**
+     * Get the current keypair (for backup/storage)
+     */
+    getKeypair() {
+        return this.keypair;
+    }
+    /**
+     * Get the username
+     */
+    getUsername() {
+        return this.username;
+    }
+    /**
+     * Get the public key
+     */
+    getPublicKey() {
+        return this.keypair.publicKey;
+    }
+    /**
+     * Get active connections (for offerer side)
+     */
+    getActiveConnections() {
+        return this.offerPool?.getActiveConnections() ?? new Map();
+    }
+    /**
+     * Get all active offers (legacy compatibility)
+     * @deprecated Use getActiveConnections() instead
+     */
+    getActiveOffers() {
+        const offers = [];
+        const connections = this.offerPool?.getActiveConnections() ?? new Map();
+        for (const [offerId, connection] of connections.entries()) {
+            const pc = connection.getPeerConnection();
+            const dc = connection.getDataChannel();
+            if (pc) {
+                offers.push({
+                    offerId,
+                    serviceFqn: this.currentService ? `${this.currentService}@${this.username}` : '',
+                    pc,
+                    dc: dc || undefined,
+                    answered: connection.getState() === 'connected',
+                    createdAt: Date.now(),
+                });
+            }
+        }
+        return offers;
+    }
+    /**
+     * Access to underlying API for advanced operations
+     * @deprecated Use direct methods on Rondevu instance instead
+     */
+    getAPIPublic() {
+        return this.api;
+    }
+}
+// Constants
+Rondevu.DEFAULT_TTL_MS = 300000; // 5 minutes
+Rondevu.POLLING_INTERVAL_MS = 1000; // 1 second

package/dist/{node-crypto-adapter.d.ts → crypto/node.d.ts}

@@ -2,7 +2,7 @@
  * Node.js Crypto adapter for Node.js environments
  * Requires Node.js 19+ or Node.js 18 with --experimental-global-webcrypto flag
  */
-import { CryptoAdapter, Keypair } from './crypto-adapter.js';
+import { CryptoAdapter, Keypair } from './adapter.js';
 /**
  * Node.js Crypto implementation using Node.js built-in APIs
  * Uses Buffer for base64 encoding and crypto.randomBytes for random generation

package/dist/{web-crypto-adapter.d.ts → crypto/web.d.ts}

@@ -1,7 +1,7 @@
 /**
  * Web Crypto adapter for browser environments
  */
-import { CryptoAdapter, Keypair } from './crypto-adapter.js';
+import { CryptoAdapter, Keypair } from './adapter.js';
 /**
  * Web Crypto implementation using browser APIs
  * Uses btoa/atob for base64 encoding and crypto.getRandomValues for random bytes

package/dist/utils/async-lock.d.ts

@@ -0,0 +1,42 @@
+/**
+ * AsyncLock provides a mutual exclusion primitive for asynchronous operations.
+ * Ensures only one async operation can proceed at a time while queuing others.
+ */
+export declare class AsyncLock {
+    private locked;
+    private queue;
+    /**
+     * Acquire the lock. If already locked, waits until released.
+     * @returns Promise that resolves when lock is acquired
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release the lock. If others are waiting, grants lock to next in queue.
+     */
+    release(): void;
+    /**
+     * Run a function with the lock acquired, automatically releasing after.
+     * This is the recommended way to use AsyncLock to prevent forgetting to release.
+     *
+     * @param fn - Async function to run with lock held
+     * @returns Promise resolving to the function's return value
+     *
+     * @example
+     * ```typescript
+     * const lock = new AsyncLock()
+     * const result = await lock.run(async () => {
+     *     // Critical section - only one caller at a time
+     *     return await doSomething()
+     * })
+     * ```
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if lock is currently held
+     */
+    isLocked(): boolean;
+    /**
+     * Get number of operations waiting for the lock
+     */
+    getQueueLength(): number;
+}