@xtr-dev/rondevu-client 0.17.1 → 0.18.2

package/README.md

@@ -49,8 +49,8 @@ const rondevu = await Rondevu.connect({
 await rondevu.publishService({
   service: 'chat:1.0.0',
   maxOffers: 5,  // Maintain up to 5 concurrent offers
-  offerFactory: async (rtcConfig) => {
-    const pc = new RTCPeerConnection(rtcConfig)
+  offerFactory: async (pc) => {
+    // pc is created by Rondevu with ICE handlers already attached
     const dc = pc.createDataChannel('chat')
 
     dc.addEventListener('open', () => {
@@ -64,7 +64,7 @@ await rondevu.publishService({
 
     const offer = await pc.createOffer()
     await pc.setLocalDescription(offer)
-    return { pc, dc, offer }
+    return { dc, offer }
   }
 })
 

package/dist/api.d.ts

@@ -31,6 +31,7 @@ export interface Service {
 }
 export interface IceCandidate {
     candidate: RTCIceCandidateInit | null;
+    role: 'offerer' | 'answerer';
     createdAt: number;
 }
 /**

package/dist/index.d.ts

@@ -2,12 +2,12 @@
  * @xtr-dev/rondevu-client
  * WebRTC peer signaling client
  */
-export { Rondevu } from './rondevu.js';
+export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
 export { RondevuAPI } from './api.js';
 export { RpcBatcher } from './rpc-batcher.js';
 export { WebCryptoAdapter } from './web-crypto-adapter.js';
 export { NodeCryptoAdapter } from './node-crypto-adapter.js';
 export type { Signaler, Binnable, } from './types.js';
 export type { Keypair, OfferRequest, ServiceRequest, Service, ServiceOffer, IceCandidate, } from './api.js';
-export type { RondevuOptions, PublishServiceOptions, ConnectToServiceOptions, ConnectionContext, OfferContext, OfferFactory } from './rondevu.js';
+export type { RondevuOptions, PublishServiceOptions, ConnectToServiceOptions, ConnectionContext, OfferContext, OfferFactory, ActiveOffer, FindServiceOptions, ServiceResult, PaginatedServiceResult } from './rondevu.js';
 export type { CryptoAdapter } from './crypto-adapter.js';

package/dist/index.js

@@ -2,7 +2,7 @@
  * @xtr-dev/rondevu-client
  * WebRTC peer signaling client
  */
-export { Rondevu } from './rondevu.js';
+export { Rondevu, RondevuError, NetworkError, ValidationError, ConnectionError } from './rondevu.js';
 export { RondevuAPI } from './api.js';
 export { RpcBatcher } from './rpc-batcher.js';
 // Export crypto adapters

package/dist/node-crypto-adapter.js

@@ -65,12 +65,10 @@ export class NodeCryptoAdapter {
     }
     bytesToBase64(bytes) {
         // Node.js Buffer provides native base64 encoding
-        // @ts-expect-error - Buffer is available in Node.js but not in browser TypeScript definitions
         return Buffer.from(bytes).toString('base64');
     }
     base64ToBytes(base64) {
         // Node.js Buffer provides native base64 decoding
-        // @ts-expect-error - Buffer is available in Node.js but not in browser TypeScript definitions
         return new Uint8Array(Buffer.from(base64, 'base64'));
     }
     randomBytes(length) {

package/dist/rondevu.d.ts

@@ -1,5 +1,6 @@
 import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from './api.js';
 import { CryptoAdapter } from './crypto-adapter.js';
+import { EventEmitter } from 'events';
 export type IceServerPreset = 'ipv4-turn' | 'hostname-turns' | 'google-stun' | 'relay-only';
 export declare const ICE_SERVER_PRESETS: Record<IceServerPreset, RTCIceServer[]>;
 export interface RondevuOptions {
@@ -10,13 +11,22 @@ export interface RondevuOptions {
     batching?: BatcherOptions | false;
     iceServers?: IceServerPreset | RTCIceServer[];
     debug?: boolean;
+    rtcPeerConnection?: typeof RTCPeerConnection;
+    rtcIceCandidate?: typeof RTCIceCandidate;
 }
 export interface OfferContext {
-    pc: RTCPeerConnection;
     dc?: RTCDataChannel;
     offer: RTCSessionDescriptionInit;
 }
-export type OfferFactory = (rtcConfig: RTCConfiguration) => Promise<OfferContext>;
+/**
+ * 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>;
 export interface PublishServiceOptions {
     service: string;
     maxOffers: number;
@@ -37,6 +47,59 @@ export interface ConnectToServiceOptions {
     onConnection?: (context: ConnectionContext) => void | Promise<void>;
     rtcConfig?: RTCConfiguration;
 }
+export interface ActiveOffer {
+    offerId: string;
+    serviceFqn: string;
+    pc: RTCPeerConnection;
+    dc?: RTCDataChannel;
+    answered: boolean;
+    createdAt: number;
+}
+export interface FindServiceOptions {
+    mode?: 'direct' | 'random' | 'paginated';
+    limit?: number;
+    offset?: number;
+}
+export interface ServiceResult {
+    serviceId: string;
+    username: string;
+    serviceFqn: string;
+    offerId: string;
+    sdp: string;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface PaginatedServiceResult {
+    services: ServiceResult[];
+    count: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Base error class for Rondevu errors
+ */
+export declare class RondevuError extends Error {
+    context?: Record<string, any> | undefined;
+    constructor(message: string, context?: Record<string, any> | undefined);
+}
+/**
+ * Network-related errors (API calls, connectivity)
+ */
+export declare class NetworkError extends RondevuError {
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * Validation errors (invalid input, malformed data)
+ */
+export declare class ValidationError extends RondevuError {
+    constructor(message: string, context?: Record<string, any>);
+}
+/**
+ * WebRTC connection errors (peer connection failures, ICE issues)
+ */
+export declare class ConnectionError extends RondevuError {
+    constructor(message: string, context?: Record<string, any>);
+}
 /**
  * Rondevu - Complete WebRTC signaling client
  *
@@ -70,12 +133,12 @@ export interface ConnectToServiceOptions {
  * await rondevu.publishService({
  *   service: 'chat:2.0.0',
  *   maxOffers: 5,  // Maintain up to 5 concurrent offers
- *   offerFactory: async (rtcConfig) => {
- *     const pc = new RTCPeerConnection(rtcConfig)
+ *   offerFactory: async (pc) => {
+ *     // pc is created by Rondevu with ICE handlers already attached
  *     const dc = pc.createDataChannel('chat')
  *     const offer = await pc.createOffer()
  *     await pc.setLocalDescription(offer)
- *     return { pc, dc, offer }
+ *     return { dc, offer }
  *   }
  * })
  *
@@ -91,7 +154,7 @@ export interface ConnectToServiceOptions {
  * rondevu.stopFilling()
  * ```
  */
-export declare class Rondevu {
+export declare class Rondevu extends EventEmitter {
     private static readonly DEFAULT_TTL_MS;
     private static readonly POLLING_INTERVAL_MS;
     private api;
@@ -103,6 +166,8 @@ export declare class Rondevu {
     private batchingOptions?;
     private iceServers;
     private debugEnabled;
+    private rtcPeerConnection?;
+    private rtcIceCandidate?;
     private currentService;
     private maxOffers;
     private offerFactory;
@@ -138,6 +203,7 @@ export declare class Rondevu {
     isUsernameClaimed(): Promise<boolean>;
     /**
      * Default offer factory - creates a simple data channel connection
+     * The RTCPeerConnection is created by Rondevu and passed in
      */
     private defaultOfferFactory;
     /**
@@ -156,6 +222,10 @@ export declare class Rondevu {
     publishService(options: PublishServiceOptions): Promise<void>;
     /**
      * Set up ICE candidate handler to send candidates to the server
+     *
+     * Note: This is used by connectToService() where the offerId is already known.
+     * For createOffer(), we use inline ICE handling with early candidate queuing
+     * since the offerId isn't available until after the factory completes.
      */
     private setupIceCandidateHandler;
     /**
@@ -180,6 +250,32 @@ export declare class Rondevu {
      * Closes all active peer connections
      */
     stopFilling(): void;
+    /**
+     * Get the count of active offers
+     * @returns Number of active offers
+     */
+    getOfferCount(): number;
+    /**
+     * Check if an offer is currently connected
+     * @param offerId - The offer ID to check
+     * @returns True if the offer exists and has been answered
+     */
+    isConnected(offerId: string): boolean;
+    /**
+     * Disconnect all active offers
+     * Similar to stopFilling() but doesn't stop the polling/filling process
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * Get the current service status
+     * @returns Object with service state information
+     */
+    getServiceStatus(): {
+        active: boolean;
+        offerCount: number;
+        maxOffers: number;
+        filling: boolean;
+    };
     /**
      * Resolve the full service FQN from various input options
      * Supports direct FQN, service+username, or service discovery
@@ -217,49 +313,30 @@ export declare class Rondevu {
      */
     connectToService(options: ConnectToServiceOptions): Promise<ConnectionContext>;
     /**
-     * Get service by FQN (with username) - Direct lookup
-     * Example: chat:1.0.0@alice
-     */
-    getService(serviceFqn: string): Promise<{
-        serviceId: string;
-        username: string;
-        serviceFqn: string;
-        offerId: string;
-        sdp: string;
-        createdAt: number;
-        expiresAt: number;
-    }>;
-    /**
-     * Discover a random available service without knowing the username
-     * Example: chat:1.0.0 (without @username)
-     */
-    discoverService(serviceVersion: string): Promise<{
-        serviceId: string;
-        username: string;
-        serviceFqn: string;
-        offerId: string;
-        sdp: string;
-        createdAt: number;
-        expiresAt: number;
-    }>;
-    /**
-     * Discover multiple available services with pagination
-     * Example: chat:1.0.0 (without @username)
+     * Find a service - unified discovery method
+     *
+     * Replaces getService(), discoverService(), and discoverServices() with a single 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
+     * })
+     * ```
      */
-    discoverServices(serviceVersion: string, limit?: number, offset?: number): Promise<{
-        services: Array<{
-            serviceId: string;
-            username: string;
-            serviceFqn: string;
-            offerId: string;
-            sdp: string;
-            createdAt: number;
-            expiresAt: number;
-        }>;
-        count: number;
-        limit: number;
-        offset: number;
-    }>;
+    findService(serviceFqn: string, options?: FindServiceOptions): Promise<ServiceResult | PaginatedServiceResult>;
     /**
      * Post answer SDP to specific offer
      */

package/dist/rondevu.js

@@ -1,4 +1,5 @@
 import { RondevuAPI } from './api.js';
+import { EventEmitter } from 'events';
 // ICE server presets
 export const ICE_SERVER_PRESETS = {
     'ipv4-turn': [
@@ -43,6 +44,47 @@ export const ICE_SERVER_PRESETS = {
         }
     ]
 };
+/**
+ * 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
  *
@@ -76,12 +118,12 @@ export const ICE_SERVER_PRESETS = {
  * await rondevu.publishService({
  *   service: 'chat:2.0.0',
  *   maxOffers: 5,  // Maintain up to 5 concurrent offers
- *   offerFactory: async (rtcConfig) => {
- *     const pc = new RTCPeerConnection(rtcConfig)
+ *   offerFactory: async (pc) => {
+ *     // pc is created by Rondevu with ICE handlers already attached
  *     const dc = pc.createDataChannel('chat')
  *     const offer = await pc.createOffer()
  *     await pc.setLocalDescription(offer)
- *     return { pc, dc, offer }
+ *     return { dc, offer }
  *   }
  * })
  *
@@ -97,8 +139,9 @@ export const ICE_SERVER_PRESETS = {
  * rondevu.stopFilling()
  * ```
  */
-export class Rondevu {
-    constructor(apiUrl, username, keypair, api, iceServers, cryptoAdapter, batchingOptions, debugEnabled = false) {
+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;
@@ -118,6 +161,8 @@ export class Rondevu {
         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,
@@ -146,6 +191,13 @@ export class Rondevu {
      */
     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') {
@@ -181,7 +233,7 @@ export class Rondevu {
         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);
+        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
@@ -215,13 +267,13 @@ export class Rondevu {
     // ============================================
     /**
      * Default offer factory - creates a simple data channel connection
+     * The RTCPeerConnection is created by Rondevu and passed in
      */
-    async defaultOfferFactory(rtcConfig) {
-        const pc = new RTCPeerConnection(rtcConfig);
+    async defaultOfferFactory(pc) {
         const dc = pc.createDataChannel('default');
         const offer = await pc.createOffer();
         await pc.setLocalDescription(offer);
-        return { pc, dc, offer };
+        return { dc, offer };
     }
     /**
      * Publish a service with automatic offer management
@@ -247,6 +299,10 @@ export class Rondevu {
     }
     /**
      * Set up ICE candidate handler to send candidates to the server
+     *
+     * Note: This is used by connectToService() where the offerId is already known.
+     * For createOffer(), we use inline ICE handling with early candidate queuing
+     * since the offerId isn't available until after the factory completes.
      */
     setupIceCandidateHandler(pc, serviceFqn, offerId) {
         pc.onicecandidate = async (event) => {
@@ -258,6 +314,8 @@ export class Rondevu {
                     const candidateData = typeof event.candidate.toJSON === 'function'
                         ? event.candidate.toJSON()
                         : event.candidate;
+                    // Emit local ICE candidate event
+                    this.emit('ice:candidate:local', offerId, candidateData);
                     await this.api.addOfferIceCandidates(serviceFqn, offerId, [candidateData]);
                 }
                 catch (err) {
@@ -276,12 +334,58 @@ export class Rondevu {
         const rtcConfig = {
             iceServers: this.iceServers
         };
-        this.debug('Creating new offer...');
-        // Create the offer using the factory
-        const { pc, dc, offer } = await this.offerFactory(rtcConfig);
         // Auto-append username to service
         const serviceFqn = `${this.currentService}@${this.username}`;
-        // Publish to server
+        this.debug('Creating new offer...');
+        // 1. Create the RTCPeerConnection - Rondevu controls this to set up handlers early
+        const pc = new RTCPeerConnection(rtcConfig);
+        // 2. Set up ICE candidate handler with queuing BEFORE the factory runs
+        // This ensures we capture all candidates, even those generated immediately
+        // when setLocalDescription() is called in the factory
+        const earlyIceCandidates = [];
+        let offerId;
+        pc.onicecandidate = async (event) => {
+            if (event.candidate) {
+                // Handle both browser and Node.js (wrtc) environments
+                const candidateData = typeof event.candidate.toJSON === 'function'
+                    ? event.candidate.toJSON()
+                    : event.candidate;
+                // Emit local ICE candidate event
+                if (offerId) {
+                    this.emit('ice:candidate:local', offerId, candidateData);
+                }
+                if (offerId) {
+                    // We have the offerId, send directly
+                    try {
+                        await this.api.addOfferIceCandidates(serviceFqn, offerId, [candidateData]);
+                    }
+                    catch (err) {
+                        console.error('[Rondevu] Failed to send ICE candidate:', err);
+                    }
+                }
+                else {
+                    // Queue for later - we don't have the offerId yet
+                    this.debug('Queuing early ICE candidate');
+                    earlyIceCandidates.push(candidateData);
+                }
+            }
+        };
+        // 3. Call the factory with the pc - factory creates data channel and offer
+        // When factory calls setLocalDescription(), ICE gathering starts and
+        // candidates are captured by the handler we set up above
+        let dc;
+        let offer;
+        try {
+            const factoryResult = await this.offerFactory(pc);
+            dc = factoryResult.dc;
+            offer = factoryResult.offer;
+        }
+        catch (err) {
+            // Clean up the connection if factory fails
+            pc.close();
+            throw err;
+        }
+        // 4. Publish to server to get offerId
         const result = await this.api.publishService({
             serviceFqn,
             offers: [{ sdp: offer.sdp }],
@@ -289,8 +393,8 @@ export class Rondevu {
             signature: '',
             message: '',
         });
-        const offerId = result.offers[0].offerId;
-        // Store active offer
+        offerId = result.offers[0].offerId;
+        // 5. Store active offer
         this.activeOffers.set(offerId, {
             offerId,
             serviceFqn,
@@ -300,12 +404,29 @@ export class Rondevu {
             createdAt: Date.now()
         });
         this.debug(`Offer created: ${offerId}`);
-        // Set up ICE candidate handler
-        this.setupIceCandidateHandler(pc, serviceFqn, offerId);
-        // Monitor connection state
+        this.emit('offer:created', offerId, serviceFqn);
+        // Set up data channel open handler (offerer side)
+        if (dc) {
+            dc.onopen = () => {
+                this.debug(`Data channel opened for offer ${offerId}`);
+                this.emit('connection:opened', offerId, dc);
+            };
+        }
+        // 6. Send any queued early ICE candidates
+        if (earlyIceCandidates.length > 0) {
+            this.debug(`Sending ${earlyIceCandidates.length} early ICE candidates`);
+            try {
+                await this.api.addOfferIceCandidates(serviceFqn, offerId, earlyIceCandidates);
+            }
+            catch (err) {
+                console.error('[Rondevu] Failed to send early ICE candidates:', err);
+            }
+        }
+        // 7. Monitor connection state
         pc.onconnectionstatechange = () => {
             this.debug(`Offer ${offerId} connection state: ${pc.connectionState}`);
             if (pc.connectionState === 'failed' || pc.connectionState === 'closed') {
+                this.emit('connection:closed', offerId);
                 this.activeOffers.delete(offerId);
                 this.fillOffers(); // Try to replace failed offer
             }
@@ -348,6 +469,7 @@ export class Rondevu {
                     });
                     activeOffer.answered = true;
                     this.lastPollTimestamp = answer.answeredAt;
+                    this.emit('offer:answered', answer.offerId, answer.answererId);
                     // Create replacement offer
                     this.fillOffers();
                 }
@@ -359,6 +481,7 @@ export class Rondevu {
                     const answererCandidates = candidates.filter(c => c.role === 'answerer');
                     for (const item of answererCandidates) {
                         if (item.candidate) {
+                            this.emit('ice:candidate:remote', offerId, item.candidate, item.role);
                             await activeOffer.pc.addIceCandidate(new RTCIceCandidate(item.candidate));
                             this.lastPollTimestamp = Math.max(this.lastPollTimestamp, item.createdAt);
                         }
@@ -411,6 +534,47 @@ export class Rondevu {
         }
         this.activeOffers.clear();
     }
+    /**
+     * Get the count of active offers
+     * @returns Number of active offers
+     */
+    getOfferCount() {
+        return this.activeOffers.size;
+    }
+    /**
+     * Check if an offer is currently connected
+     * @param offerId - The offer ID to check
+     * @returns True if the offer exists and has been answered
+     */
+    isConnected(offerId) {
+        const offer = this.activeOffers.get(offerId);
+        return offer ? offer.answered : false;
+    }
+    /**
+     * Disconnect all active offers
+     * Similar to stopFilling() but doesn't stop the polling/filling process
+     */
+    async disconnectAll() {
+        this.debug('Disconnecting all offers');
+        for (const [offerId, offer] of this.activeOffers.entries()) {
+            this.debug(`Closing offer ${offerId}`);
+            offer.dc?.close();
+            offer.pc.close();
+        }
+        this.activeOffers.clear();
+    }
+    /**
+     * Get the current service status
+     * @returns Object with service state information
+     */
+    getServiceStatus() {
+        return {
+            active: this.currentService !== null,
+            offerCount: this.activeOffers.size,
+            maxOffers: this.maxOffers,
+            filling: this.filling
+        };
+    }
     /**
      * Resolve the full service FQN from various input options
      * Supports direct FQN, service+username, or service discovery
@@ -426,7 +590,7 @@ export class Rondevu {
         else if (service) {
             // Discovery mode - get random service
             this.debug(`Discovering service: ${service}`);
-            const discovered = await this.discoverService(service);
+            const discovered = await this.findService(service);
             return discovered.serviceFqn;
         }
         else {
@@ -444,6 +608,7 @@ export class Rondevu {
                 const result = await this.api.getOfferIceCandidates(serviceFqn, offerId, lastIceTimestamp);
                 for (const item of result.candidates) {
                     if (item.candidate) {
+                        this.emit('ice:candidate:remote', offerId, item.candidate, item.role);
                         await pc.addIceCandidate(new RTCIceCandidate(item.candidate));
                         lastIceTimestamp = item.createdAt;
                     }
@@ -508,6 +673,7 @@ export class Rondevu {
             pc.ondatachannel = (event) => {
                 this.debug('Data channel received from offerer');
                 dc = event.channel;
+                this.emit('connection:opened', serviceData.offerId, dc);
                 resolve(dc);
             };
         });
@@ -565,25 +731,41 @@ export class Rondevu {
     // Service Discovery
     // ============================================
     /**
-     * Get service by FQN (with username) - Direct lookup
-     * Example: chat:1.0.0@alice
-     */
-    async getService(serviceFqn) {
-        return await this.api.getService(serviceFqn);
-    }
-    /**
-     * Discover a random available service without knowing the username
-     * Example: chat:1.0.0 (without @username)
-     */
-    async discoverService(serviceVersion) {
-        return await this.api.getService(serviceVersion);
-    }
-    /**
-     * Discover multiple available services with pagination
-     * Example: chat:1.0.0 (without @username)
+     * Find a service - unified discovery method
+     *
+     * Replaces getService(), discoverService(), and discoverServices() with a single 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 discoverServices(serviceVersion, limit = 10, offset = 0) {
-        return await this.api.getService(serviceVersion, { limit, offset });
+    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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/rondevu-client",
-  "version": "0.17.1",
+  "version": "0.18.2",
   "description": "TypeScript client for Rondevu with durable WebRTC connections, automatic reconnection, and message queuing",
   "type": "module",
   "main": "dist/index.js",
@@ -25,6 +25,7 @@
   "license": "MIT",
   "devDependencies": {
     "@eslint/js": "^9.39.1",
+    "@types/node": "^25.0.2",
     "@typescript-eslint/eslint-plugin": "^8.48.1",
     "@typescript-eslint/parser": "^8.48.1",
     "eslint": "^9.39.1",