@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/dist/core/rondevu.js

@@ -0,0 +1,472 @@
+import { RondevuAPI } from '../api/client.js';
+import { BrowserWebRTCAdapter } from '../webrtc/browser.js';
+import { EventEmitter } from 'eventemitter3';
+import { OfferPool } from './offer-pool.js';
+import { Peer } from './peer.js';
+import { getIceConfiguration } from './ice-config.js';
+import { PollingManager } from './polling-manager.js';
+// Re-export ICE config for backward compatibility
+export { ICE_SERVER_PRESETS } from './ice-config.js';
+/**
+ * Rondevu - Complete WebRTC signaling client with durable connections
+ *
+ * Uses a tags-based discovery system where offers have 1+ tags for matching.
+ *
+ * @example
+ * ```typescript
+ * // Create and initialize Rondevu instance with preset ICE servers
+ * const rondevu = await Rondevu.connect({
+ *   apiUrl: 'https://signal.example.com',
+ *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
+ * })
+ *
+ * // Create offers with tags for discovery
+ * await rondevu.offer({
+ *   tags: ['chat', 'video'],
+ *   maxOffers: 5  // Maintain up to 5 concurrent offers
+ * })
+ *
+ * // Start accepting connections (auto-fills offers and polls)
+ * await rondevu.startFilling()
+ *
+ * // Listen for connections
+ * rondevu.on('connection:opened', (offerId, connection) => {
+ *   connection.on('connected', () => console.log('Connected!'))
+ *   connection.on('message', (data) => console.log('Received:', data))
+ *   connection.send('Hello!')
+ * })
+ *
+ * // Connect by discovering offers with matching tags
+ * const connection = await rondevu.connect({
+ *   tags: ['chat']
+ * })
+ *
+ * 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, credential, api, iceServers, iceTransportPolicy, webrtcAdapter, cryptoAdapter, debugEnabled = false) {
+        super();
+        // Publishing state
+        this.currentTags = null;
+        this.offerPool = null;
+        this.apiUrl = apiUrl;
+        this.credential = credential;
+        this.api = api;
+        this.iceServers = iceServers;
+        this.iceTransportPolicy = iceTransportPolicy;
+        this.webrtcAdapter = webrtcAdapter;
+        this.cryptoAdapter = cryptoAdapter;
+        this.debugEnabled = debugEnabled;
+        // Initialize centralized polling manager
+        this.pollingManager = new PollingManager({
+            api: this.api,
+            debugEnabled: this.debugEnabled,
+        });
+        // Forward polling events to Rondevu instance
+        this.pollingManager.on('poll:answer', data => {
+            this.emit('poll:answer', data);
+        });
+        this.pollingManager.on('poll:ice', data => {
+            this.emit('poll:ice', data);
+        });
+        this.debug('Instance created:', {
+            name: this.credential.name,
+            hasIceServers: iceServers.length > 0,
+            iceTransportPolicy: iceTransportPolicy || 'all',
+        });
+    }
+    /**
+     * 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({})  // Uses default API URL
+     * // or
+     * const rondevu = await Rondevu.connect({
+     *   apiUrl: 'https://custom.api.com'
+     * })
+     * ```
+     */
+    static async connect(options = {}) {
+        const apiUrl = options.apiUrl || Rondevu.DEFAULT_API_URL;
+        // Use provided WebRTC adapter or default to browser adapter
+        const webrtcAdapter = options.webrtcAdapter || new BrowserWebRTCAdapter();
+        // Handle preset string or custom array, extracting iceTransportPolicy if present
+        const iceConfig = getIceConfiguration(options.iceServers);
+        if (options.debug) {
+            console.log('[Rondevu] Connecting:', {
+                apiUrl,
+                hasCredential: !!options.credential,
+                iceServers: iceConfig.iceServers?.length ?? 0,
+                iceTransportPolicy: iceConfig.iceTransportPolicy || 'all',
+            });
+        }
+        // Generate credential if not provided
+        let credential = options.credential;
+        if (!credential) {
+            if (options.debug)
+                console.log('[Rondevu] Generating new credentials...');
+            credential = await RondevuAPI.generateCredentials(apiUrl, {
+                name: options.username, // Will claim this username if provided
+            });
+            if (options.debug)
+                console.log('[Rondevu] Generated credentials, name:', credential.name);
+        }
+        else {
+            if (options.debug)
+                console.log('[Rondevu] Using existing credential, name:', credential.name);
+        }
+        // Create API instance
+        const api = new RondevuAPI(apiUrl, credential, options.cryptoAdapter);
+        if (options.debug)
+            console.log('[Rondevu] Created API instance');
+        return new Rondevu(apiUrl, credential, api, iceConfig.iceServers || [], iceConfig.iceTransportPolicy, webrtcAdapter, options.cryptoAdapter, options.debug || false);
+    }
+    // ============================================
+    // Credential Access
+    // ============================================
+    /**
+     * Get the current credential name
+     */
+    getName() {
+        return this.credential.name;
+    }
+    /**
+     * Get the full credential (name + secret)
+     * Use this to persist credentials for future sessions
+     *
+     * ⚠️ SECURITY WARNING:
+     * - The secret grants full access to this identity
+     * - Store credentials securely (encrypted storage, never in logs)
+     * - Never expose credentials in URLs, console output, or error messages
+     * - Treat the secret like a password or API key
+     */
+    getCredential() {
+        return { ...this.credential };
+    }
+    /**
+     * Get the WebRTC adapter for creating peer connections
+     * Used internally by offer pool and connections
+     */
+    getWebRTCAdapter() {
+        return this.webrtcAdapter;
+    }
+    // ============================================
+    // 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 };
+    }
+    /**
+     * Create offers with tags for discovery (offerer/host side)
+     * Auto-starts filling by default. Use the returned object to cancel.
+     *
+     * @example
+     * ```typescript
+     * // Auto-start (default)
+     * const offer = await rondevu.offer({
+     *   tags: ['chat', 'video'],
+     *   maxOffers: 5
+     * })
+     * // Later: offer.cancel() to stop
+     *
+     * // Manual start
+     * await rondevu.offer({ tags: ['chat'], maxOffers: 5, autoStart: false })
+     * await rondevu.startFilling()
+     * ```
+     */
+    async offer(options) {
+        const { tags, maxOffers, offerFactory, ttl, connectionConfig, autoStart = true } = options;
+        this.currentTags = tags;
+        this.connectionConfig = connectionConfig;
+        this.debug(`Creating offers with tags: ${tags.join(', ')} with maxOffers: ${maxOffers}`);
+        // Create OfferPool
+        this.offerPool = new OfferPool({
+            api: this.api,
+            tags,
+            ownerUsername: this.credential.name,
+            maxOffers,
+            offerFactory: offerFactory || this.defaultOfferFactory.bind(this),
+            ttl: ttl || Rondevu.DEFAULT_TTL_MS,
+            iceServers: this.iceServers,
+            iceTransportPolicy: this.iceTransportPolicy,
+            webrtcAdapter: this.webrtcAdapter,
+            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, tags) => {
+            this.emit('offer:created', offerId, tags);
+        });
+        this.offerPool.on('connection:rotated', (oldOfferId, newOfferId, connection) => {
+            this.emit('connection:rotated', oldOfferId, newOfferId, connection);
+        });
+        // Subscribe to polling events and forward to OfferPool
+        this.on('poll:answer', data => {
+            this.offerPool?.handlePollAnswer(data);
+        });
+        this.on('poll:ice', data => {
+            this.offerPool?.handlePollIce(data);
+        });
+        // Auto-start if enabled (default)
+        if (autoStart) {
+            await this.startFilling();
+        }
+        // Return handle for cancellation
+        return {
+            cancel: () => this.stopFilling(),
+        };
+    }
+    /**
+     * Start filling offers and polling for answers/ICE
+     * Call this after offer() to begin accepting connections
+     */
+    async startFilling() {
+        if (!this.offerPool) {
+            throw new Error('No offers created. Call offer() first.');
+        }
+        this.debug('Starting offer filling and polling');
+        // Start the centralized polling manager
+        this.pollingManager.start();
+        await this.offerPool.start();
+    }
+    /**
+     * Stop filling offers and polling
+     * Closes all active peer connections
+     */
+    stopFilling() {
+        this.debug('Stopping offer filling and polling');
+        // Stop the centralized polling manager
+        this.pollingManager.stop();
+        this.offerPool?.stop();
+    }
+    /**
+     * Start the centralized polling manager
+     * Use this when you need polling without offers (e.g., answerer connections)
+     */
+    startPolling() {
+        this.debug('Starting polling manager');
+        this.pollingManager.start();
+    }
+    /**
+     * Stop the centralized polling manager
+     */
+    stopPolling() {
+        this.debug('Stopping polling manager');
+        this.pollingManager.stop();
+    }
+    /**
+     * Check if polling is active
+     */
+    isPolling() {
+        return this.pollingManager.isRunning();
+    }
+    /**
+     * 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 publishing status
+     * @returns Object with publishing state information
+     */
+    getPublishStatus() {
+        return {
+            active: this.currentTags !== null,
+            offerCount: this.offerPool?.getOfferCount() ?? 0,
+            tags: this.currentTags,
+        };
+    }
+    /**
+     * Create a peer connection with simplified DX
+     * Returns a Peer object with clean state management and events
+     *
+     * @example
+     * ```typescript
+     * // Connect to any peer matching tags
+     * const peer = await rondevu.peer({ tags: ['chat'] })
+     *
+     * // Connect to specific user
+     * 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, prevState) => {
+     *   console.log(`State: ${prevState} → ${state}`)
+     * })
+     *
+     * // Access underlying RTCPeerConnection
+     * if (peer.peerConnection) {
+     *   console.log('ICE state:', peer.peerConnection.iceConnectionState)
+     * }
+     * ```
+     */
+    async peer(options) {
+        const peer = new Peer({
+            ...options,
+            api: this.api,
+            iceServers: this.iceServers,
+            iceTransportPolicy: this.iceTransportPolicy,
+            debug: this.debugEnabled,
+        });
+        await peer.initialize();
+        // Subscribe to poll:ice events for this peer's connection
+        const peerOfferId = peer.offerId;
+        const peerConnection = peer.getConnection();
+        if (peerConnection) {
+            const pollIceHandler = (data) => {
+                if (data.offerId === peerOfferId) {
+                    peerConnection.handleRemoteIceCandidates(data.candidates);
+                }
+            };
+            this.on('poll:ice', pollIceHandler);
+            // Clean up handler when connection closes
+            peerConnection.on('closed', () => {
+                this.off('poll:ice', pollIceHandler);
+            });
+        }
+        // Start polling if not already running
+        if (!this.pollingManager.isRunning()) {
+            this.debug('Starting polling for peer connection');
+            this.pollingManager.start();
+        }
+        return peer;
+    }
+    // ============================================
+    // Discovery
+    // ============================================
+    /**
+     * Discover offers by tags
+     *
+     * @param tags - Tags to search for (OR logic - matches any tag)
+     * @param options - Discovery options (pagination)
+     *
+     * @example
+     * ```typescript
+     * // Discover offers matching any of the tags
+     * const result = await rondevu.discover(['chat', 'video'])
+     *
+     * // Paginated discovery
+     * const result = await rondevu.discover(['chat'], {
+     *   limit: 20,
+     *   offset: 0
+     * })
+     *
+     * // Access offers
+     * for (const offer of result.offers) {
+     *   console.log(offer.username, offer.tags)
+     * }
+     * ```
+     */
+    async discover(tags, options) {
+        const { limit = 10, offset = 0 } = options || {};
+        // Always pass limit to ensure we get DiscoverResponse (paginated mode)
+        return (await this.api.discover({ tags, limit, offset }));
+    }
+    // ============================================
+    // WebRTC Signaling
+    // ============================================
+    /**
+     * Post answer SDP to specific offer
+     */
+    async postOfferAnswer(offerId, sdp) {
+        await this.api.answerOffer(offerId, sdp);
+        return { success: true, offerId };
+    }
+    /**
+     * Get answer SDP (offerer polls this)
+     */
+    async getOfferAnswer(offerId) {
+        return await this.api.getOfferAnswer(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(offerId, candidates) {
+        return await this.api.addOfferIceCandidates(offerId, candidates);
+    }
+    /**
+     * Get ICE candidates for specific offer (with polling support)
+     */
+    async getOfferIceCandidates(offerId, since = 0) {
+        return await this.api.getOfferIceCandidates(offerId, since);
+    }
+    // ============================================
+    // Utility Methods
+    // ============================================
+    /**
+     * Get active connections (for offerer side)
+     */
+    getActiveConnections() {
+        return this.offerPool?.getActiveConnections() ?? new Map();
+    }
+}
+// Constants
+Rondevu.DEFAULT_API_URL = 'https://api.ronde.vu';
+Rondevu.DEFAULT_TTL_MS = 300000; // 5 minutes
+Rondevu.POLLING_INTERVAL_MS = 1000; // 1 second

package/dist/crypto/adapter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Crypto adapter interface for platform-independent cryptographic operations
+ */
+export interface Credential {
+    name: string;
+    secret: string;
+}
+/**
+ * Platform-independent crypto adapter interface
+ * Implementations provide platform-specific crypto operations
+ */
+export interface CryptoAdapter {
+    /**
+     * Generate HMAC-SHA256 signature for message authentication
+     * @param secret - The credential secret (hex string)
+     * @param message - The message to sign
+     * @returns Base64-encoded signature
+     */
+    generateSignature(secret: string, message: string): Promise<string>;
+    /**
+     * Verify HMAC-SHA256 signature
+     * @param secret - The credential secret (hex string)
+     * @param message - The message that was signed
+     * @param signature - The signature to verify (base64)
+     * @returns True if signature is valid
+     */
+    verifySignature(secret: string, message: string, signature: string): Promise<boolean>;
+    /**
+     * Generate a random secret (256-bit hex string)
+     * @returns 64-character hex string
+     */
+    generateSecret(): string;
+    /**
+     * Convert hex string to bytes
+     */
+    hexToBytes(hex: string): Uint8Array;
+    /**
+     * Convert bytes to hex string
+     */
+    bytesToHex(bytes: Uint8Array): string;
+    /**
+     * Convert Uint8Array to base64 string
+     */
+    bytesToBase64(bytes: Uint8Array): string;
+    /**
+     * Convert base64 string to Uint8Array
+     */
+    base64ToBytes(base64: string): Uint8Array;
+    /**
+     * Generate random bytes
+     */
+    randomBytes(length: number): Uint8Array;
+}

package/dist/crypto/node.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Node.js Crypto adapter for Node.js environments
+ * Requires Node.js 19+ or Node.js 18 with --experimental-global-webcrypto flag
+ */
+import { CryptoAdapter } from './adapter.js';
+/**
+ * Node.js Crypto implementation using Node.js built-in APIs
+ * Uses Buffer for base64 encoding and crypto.randomBytes for random generation
+ *
+ * Requirements:
+ * - Node.js 19+ (crypto.subtle available globally)
+ * - OR Node.js 18 with --experimental-global-webcrypto flag
+ *
+ * @example
+ * ```typescript
+ * import { RondevuAPI } from '@xtr-dev/rondevu-client'
+ * import { NodeCryptoAdapter } from '@xtr-dev/rondevu-client/node'
+ *
+ * const api = new RondevuAPI(
+ *   'https://signal.example.com',
+ *   'alice',
+ *   { name: 'alice', secret: '...' },
+ *   new NodeCryptoAdapter()
+ * )
+ * ```
+ */
+export declare class NodeCryptoAdapter implements CryptoAdapter {
+    constructor();
+    /**
+     * Generate HMAC-SHA256 signature
+     */
+    generateSignature(secret: string, message: string): Promise<string>;
+    /**
+     * Verify HMAC-SHA256 signature
+     * Uses constant-time comparison via Web Crypto API to prevent timing attacks
+     *
+     * @returns false for invalid signatures, throws for malformed input
+     * @throws Error if secret/signature format is invalid (not a verification failure)
+     */
+    verifySignature(secret: string, message: string, signature: string): Promise<boolean>;
+    /**
+     * Generate a random secret (256-bit hex string)
+     */
+    generateSecret(): string;
+    /**
+     * Convert hex string to bytes
+     * @throws Error if hex string is invalid
+     */
+    hexToBytes(hex: string): Uint8Array;
+    /**
+     * Convert bytes to hex string
+     */
+    bytesToHex(bytes: Uint8Array): string;
+    bytesToBase64(bytes: Uint8Array): string;
+    base64ToBytes(base64: string): Uint8Array;
+    randomBytes(length: number): Uint8Array;
+}