@xtr-dev/rondevu-client 0.7.3 → 0.7.5

package/README.md

@@ -4,10 +4,10 @@
 
 🌐 **Topic-based peer discovery and WebRTC signaling client**
 
-TypeScript/JavaScript client for Rondevu, providing topic-based peer discovery, stateless authentication, and complete WebRTC signaling.
+TypeScript/JavaScript client for Rondevu, providing topic-based peer discovery, stateless authentication, and complete WebRTC signaling with trickle ICE support.
 
 **Related repositories:**
-- [rondevu-server](https://github.com/xtr-dev/rondevu) - HTTP signaling server
+- [rondevu-server](https://github.com/xtr-dev/rondevu-server) - HTTP signaling server
 - [rondevu-demo](https://rondevu-demo.pages.dev) - Interactive demo
 
 ---
@@ -19,6 +19,8 @@ TypeScript/JavaScript client for Rondevu, providing topic-based peer discovery,
 - **Bloom Filters**: Efficient peer exclusion for repeated discoveries
 - **Multi-Offer Management**: Create and manage multiple offers per peer
 - **Complete WebRTC Signaling**: Full offer/answer and ICE candidate exchange
+- **Trickle ICE**: Send ICE candidates as they're discovered (faster connections)
+- **State Machine**: Clean state-based connection lifecycle
 - **TypeScript**: Full type safety and autocomplete
 
 ## Install
@@ -29,36 +31,42 @@ npm install @xtr-dev/rondevu-client
 
 ## Quick Start
 
-The easiest way to use Rondevu is with the high-level `RondevuConnection` class, which handles all WebRTC connection complexity including offer/answer exchange, ICE candidates, and connection lifecycle.
-
 ### Creating an Offer (Peer A)
 
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client';
 
+// Initialize client and register
 const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
 await client.register();
 
-// Create a connection
-const conn = client.createConnection();
+// Create peer connection
+const peer = client.createPeer();
 
 // Set up event listeners
-conn.on('connected', () => {
-  console.log('Connected to peer!');
+peer.on('state', (state) => {
+  console.log('Peer state:', state);
+  // States: idle → creating-offer → waiting-for-answer → exchanging-ice → connected
+});
+
+peer.on('connected', () => {
+  console.log('✅ Connected to peer!');
 });
 
-conn.on('datachannel', (channel) => {
-  console.log('Data channel ready');
+peer.on('datachannel', (channel) => {
+  console.log('📡 Data channel ready');
 
-  channel.onmessage = (event) => {
-    console.log('Received:', event.data);
-  };
+  channel.addEventListener('message', (event) => {
+    console.log('📥 Received:', event.data);
+  });
 
-  channel.send('Hello from peer A!');
+  channel.addEventListener('open', () => {
+    channel.send('Hello from peer A!');
+  });
 });
 
 // Create offer and advertise on topics
-const offerId = await conn.createOffer({
+const offerId = await peer.createOffer({
   topics: ['my-app', 'room-123'],
   ttl: 300000  // 5 minutes
 });
@@ -72,6 +80,7 @@ console.log('Share these topics with peers:', ['my-app', 'room-123']);
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client';
 
+// Initialize client and register
 const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
 await client.register();
 
@@ -81,65 +90,104 @@ const offers = await client.offers.findByTopic('my-app', { limit: 10 });
 if (offers.length > 0) {
   const offer = offers[0];
 
-  // Create connection
-  const conn = client.createConnection();
+  // Create peer connection
+  const peer = client.createPeer();
 
   // Set up event listeners
-  conn.on('connecting', () => {
-    console.log('Connecting...');
+  peer.on('state', (state) => {
+    console.log('Peer state:', state);
+    // States: idle → answering → exchanging-ice → connected
   });
 
-  conn.on('connected', () => {
-    console.log('Connected!');
+  peer.on('connected', () => {
+    console.log('✅ Connected!');
   });
 
-  conn.on('datachannel', (channel) => {
-    console.log('Data channel ready');
+  peer.on('datachannel', (channel) => {
+    console.log('📡 Data channel ready');
 
-    channel.onmessage = (event) => {
-      console.log('Received:', event.data);
-    };
+    channel.addEventListener('message', (event) => {
+      console.log('📥 Received:', event.data);
+    });
 
-    channel.send('Hello from peer B!');
+    channel.addEventListener('open', () => {
+      channel.send('Hello from peer B!');
+    });
+  });
+
+  peer.on('failed', (error) => {
+    console.error('❌ Connection failed:', error);
   });
 
   // Answer the offer
-  await conn.answer(offer.id, offer.sdp);
+  await peer.answer(offer.id, offer.sdp, {
+    topics: offer.topics
+  });
 }
 ```
 
-### Connection Events
+## Connection Lifecycle
+
+The `RondevuPeer` uses a state machine for connection management:
+
+### Offerer States
+1. **idle** - Initial state
+2. **creating-offer** - Creating WebRTC offer
+3. **waiting-for-answer** - Polling for answer from peer
+4. **exchanging-ice** - Exchanging ICE candidates
+5. **connected** - Successfully connected
+6. **failed** - Connection failed
+7. **closed** - Connection closed
+
+### Answerer States
+1. **idle** - Initial state
+2. **answering** - Creating WebRTC answer
+3. **exchanging-ice** - Exchanging ICE candidates
+4. **connected** - Successfully connected
+5. **failed** - Connection failed
+6. **closed** - Connection closed
+
+### State Events
 
 ```typescript
-conn.on('connecting', () => {
-  // Connection is being established
+peer.on('state', (stateName) => {
+  console.log('Current state:', stateName);
 });
 
-conn.on('connected', () => {
+peer.on('connected', () => {
   // Connection established successfully
 });
 
-conn.on('disconnected', () => {
+peer.on('disconnected', () => {
   // Connection lost or closed
 });
 
-conn.on('error', (error) => {
-  // An error occurred
+peer.on('failed', (error) => {
+  // Connection failed
   console.error('Connection error:', error);
 });
 
-conn.on('datachannel', (channel) => {
-  // Data channel is ready to use
+peer.on('datachannel', (channel) => {
+  // Data channel is ready (use channel.addEventListener)
 });
 
-conn.on('track', (event) => {
+peer.on('track', (event) => {
   // Media track received (for audio/video streaming)
   const stream = event.streams[0];
   videoElement.srcObject = stream;
 });
 ```
 
-### Adding Media Tracks
+## Trickle ICE
+
+This library implements **trickle ICE** for faster connection establishment:
+
+- ICE candidates are sent to the server as they're discovered
+- No waiting for all candidates before sending offer/answer
+- Connections establish much faster (milliseconds vs seconds)
+- Proper event listener cleanup to prevent memory leaks
+
+## Adding Media Tracks
 
 ```typescript
 // Get user's camera/microphone
@@ -148,29 +196,64 @@ const stream = await navigator.mediaDevices.getUserMedia({
   audio: true
 });
 
-// Add tracks to connection
+// Add tracks to peer connection
 stream.getTracks().forEach(track => {
-  conn.addTrack(track, stream);
+  peer.addTrack(track, stream);
 });
 ```
 
-### Connection Properties
+## Peer Properties
 
 ```typescript
+// Get current state name
+console.log(peer.stateName); // 'idle', 'creating-offer', 'connected', etc.
+
 // Get connection state
-console.log(conn.connectionState); // 'connecting', 'connected', 'disconnected', etc.
+console.log(peer.connectionState); // RTCPeerConnectionState
+
+// Get offer ID (after creating offer or answering)
+console.log(peer.offerId);
 
-// Get offer ID
-console.log(conn.id);
+// Get role
+console.log(peer.role); // 'offerer' or 'answerer'
+```
+
+## Closing a Connection
 
-// Get data channel
-console.log(conn.channel);
+```typescript
+await peer.close();
 ```
 
-### Closing a Connection
+## Custom RTCConfiguration
 
 ```typescript
-conn.close();
+const peer = client.createPeer({
+  iceServers: [
+    { urls: 'stun:stun.l.google.com:19302' },
+    {
+      urls: 'turn:turn.example.com:3478',
+      username: 'user',
+      credential: 'pass'
+    }
+  ],
+  iceTransportPolicy: 'relay' // Force TURN relay (useful for testing)
+});
+```
+
+## Timeouts
+
+Configure connection timeouts:
+
+```typescript
+await peer.createOffer({
+  topics: ['my-topic'],
+  timeouts: {
+    iceGathering: 10000,        // ICE gathering timeout (10s)
+    waitingForAnswer: 30000,    // Waiting for answer timeout (30s)
+    creatingAnswer: 10000,      // Creating answer timeout (10s)
+    iceConnection: 30000        // ICE connection timeout (30s)
+  }
+});
 ```
 
 ## Platform-Specific Setup
@@ -197,6 +280,43 @@ const client = new Rondevu({
 });
 ```
 
+### Node.js with WebRTC (wrtc)
+
+For WebRTC functionality in Node.js, you need to provide WebRTC polyfills since Node.js doesn't have native WebRTC support:
+
+```bash
+npm install wrtc node-fetch
+```
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+import fetch from 'node-fetch';
+import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
+
+const client = new Rondevu({
+  baseUrl: 'https://api.ronde.vu',
+  fetch: fetch as any,
+  RTCPeerConnection,
+  RTCSessionDescription,
+  RTCIceCandidate
+});
+
+// Now you can use WebRTC features
+await client.register();
+const peer = client.createPeer({
+  iceServers: [
+    { urls: 'stun:stun.l.google.com:19302' }
+  ]
+});
+
+// Create offers, answer, etc.
+const offerId = await peer.createOffer({
+  topics: ['my-topic']
+});
+```
+
+**Note:** The `wrtc` package provides WebRTC bindings for Node.js. Alternative packages like `node-webrtc` can also be used - just pass their implementations to the Rondevu constructor.
+
 ### Deno
 
 ```typescript
@@ -230,7 +350,7 @@ export default {
 
 ## Low-Level API Usage
 
-For advanced use cases where you need direct control over the signaling process, you can use the low-level API:
+For direct control over the signaling process without WebRTC:
 
 ```typescript
 import { Rondevu, BloomFilter } from '@xtr-dev/rondevu-client';
@@ -335,13 +455,6 @@ Get all offers owned by the authenticated peer.
 const myOffers = await client.offers.getMine();
 ```
 
-#### `client.offers.heartbeat(offerId)`
-Update last_seen timestamp for an offer.
-
-```typescript
-await client.offers.heartbeat(offerId);
-```
-
 #### `client.offers.delete(offerId)`
 Delete a specific offer.
 
@@ -370,7 +483,7 @@ Post ICE candidates for an offer.
 
 ```typescript
 await client.offers.addIceCandidates(offerId, [
-  'candidate:1 1 UDP...'
+  { candidate: 'candidate:1 1 UDP...', sdpMid: '0', sdpMLineIndex: 0 }
 ]);
 ```
 
@@ -378,7 +491,7 @@ await client.offers.addIceCandidates(offerId, [
 Get ICE candidates from the other peer.
 
 ```typescript
-const candidates = await client.offers.getIceCandidates(offerId);
+const candidates = await client.offers.getIceCandidates(offerId, since);
 ```
 
 ### Bloom Filter
@@ -414,8 +527,9 @@ import type {
   IceCandidate,
   FetchFunction,
   RondevuOptions,
-  ConnectionOptions,
-  RondevuConnectionEvents
+  PeerOptions,
+  PeerEvents,
+  PeerTimeouts
 } from '@xtr-dev/rondevu-client';
 ```
 
@@ -423,28 +537,36 @@ import type {
 
 The client library is designed to work across different JavaScript runtimes:
 
-| Environment | Native Fetch | Custom Fetch Needed |
-|-------------|--------------|---------------------|
-| Modern Browsers | ✅ Yes | ❌ No |
-| Node.js 18+ | ✅ Yes | ❌ No |
-| Node.js < 18 | ❌ No | ✅ Yes (node-fetch) |
-| Deno | ✅ Yes | ❌ No |
-| Bun | ✅ Yes | ❌ No |
-| Cloudflare Workers | ✅ Yes | ❌ No |
+| Environment | Native Fetch | Native WebRTC | Polyfills Needed |
+|-------------|--------------|---------------|------------------|
+| Modern Browsers | ✅ Yes | ✅ Yes | ❌ None |
+| Node.js 18+ | ✅ Yes | ❌ No | ✅ WebRTC (wrtc) |
+| Node.js < 18 | ❌ No | ❌ No | ✅ Fetch + WebRTC |
+| Deno | ✅ Yes | ⚠️ Partial | ❌ None (signaling only) |
+| Bun | ✅ Yes | ❌ No | ✅ WebRTC (wrtc) |
+| Cloudflare Workers | ✅ Yes | ❌ No | ❌ None (signaling only) |
+
+**For signaling-only (no WebRTC peer connections):**
+
+Use the low-level API with `client.offers` - no WebRTC polyfills needed.
 
-**If your environment doesn't have native fetch:**
+**For full WebRTC support in Node.js:**
 
 ```bash
-npm install node-fetch
+npm install wrtc node-fetch
 ```
 
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client';
 import fetch from 'node-fetch';
+import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
 
 const client = new Rondevu({
-  baseUrl: 'https://rondevu.xtrdev.workers.dev',
-  fetch: fetch as any
+  baseUrl: 'https://api.ronde.vu',
+  fetch: fetch as any,
+  RTCPeerConnection,
+  RTCSessionDescription,
+  RTCIceCandidate
 });
 ```
 

package/dist/offers.d.ts

@@ -55,20 +55,18 @@ export declare class RondevuOffers {
     getTopics(options?: {
         limit?: number;
         offset?: number;
+        startsWith?: string;
     }): Promise<{
         topics: TopicInfo[];
         total: number;
         limit: number;
         offset: number;
+        startsWith?: string;
     }>;
     /**
      * Get own offers
      */
     getMine(): Promise<Offer[]>;
-    /**
-     * Update offer heartbeat
-     */
-    heartbeat(offerId: string): Promise<void>;
     /**
      * Delete an offer
      */

package/dist/offers.js

@@ -81,6 +81,9 @@ export class RondevuOffers {
         if (options?.offset) {
             params.set('offset', options.offset.toString());
         }
+        if (options?.startsWith) {
+            params.set('startsWith', options.startsWith);
+        }
         const url = `${this.baseUrl}/topics${params.toString() ? '?' + params.toString() : ''}`;
         const response = await this.fetchFn(url, {
             method: 'GET',
@@ -108,21 +111,6 @@ export class RondevuOffers {
         const data = await response.json();
         return data.offers;
     }
-    /**
-     * Update offer heartbeat
-     */
-    async heartbeat(offerId) {
-        const response = await this.fetchFn(`${this.baseUrl}/offers/${encodeURIComponent(offerId)}/heartbeat`, {
-            method: 'PUT',
-            headers: {
-                Authorization: RondevuAuth.createAuthHeader(this.credentials),
-            },
-        });
-        if (!response.ok) {
-            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
-            throw new Error(`Failed to update heartbeat: ${error.error || response.statusText}`);
-        }
-    }
     /**
      * Delete an offer
      */

package/dist/peer/exchanging-ice-state.js

@@ -24,7 +24,7 @@ export class ExchangingIceState extends PeerState {
                 for (const cand of candidates) {
                     if (cand.candidate && cand.candidate.candidate && cand.candidate.candidate !== '') {
                         try {
-                            await this.peer.pc.addIceCandidate(new RTCIceCandidate(cand.candidate));
+                            await this.peer.pc.addIceCandidate(new this.peer.RTCIceCandidate(cand.candidate));
                             this.lastIceTimestamp = cand.createdAt;
                         }
                         catch (err) {

package/dist/peer/index.d.ts

@@ -12,6 +12,9 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
     offersApi: RondevuOffers;
     offerId?: string;
     role?: 'offerer' | 'answerer';
+    RTCPeerConnection: typeof RTCPeerConnection;
+    RTCSessionDescription: typeof RTCSessionDescription;
+    RTCIceCandidate: typeof RTCIceCandidate;
     private _state;
     private connectionStateChangeHandler?;
     private dataChannelHandler?;
@@ -29,7 +32,7 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
      * RTCPeerConnection state
      */
     get connectionState(): RTCPeerConnectionState;
-    constructor(offersApi: RondevuOffers, rtcConfig?: RTCConfiguration);
+    constructor(offersApi: RondevuOffers, rtcConfig?: RTCConfiguration, rtcPeerConnection?: typeof RTCPeerConnection, rtcSessionDescription?: typeof RTCSessionDescription, rtcIceCandidate?: typeof RTCIceCandidate);
     /**
      * Set up peer connection event handlers
      */

package/dist/peer/index.js

@@ -31,10 +31,26 @@ export default class RondevuPeer extends EventEmitter {
             { urls: 'stun:stun.l.google.com:19302' },
             { urls: 'stun:stun1.l.google.com:19302' }
         ]
-    }) {
+    }, rtcPeerConnection, rtcSessionDescription, rtcIceCandidate) {
         super();
         this.offersApi = offersApi;
-        this.pc = new RTCPeerConnection(rtcConfig);
+        // Use provided polyfills or fall back to globals
+        this.RTCPeerConnection = rtcPeerConnection || (typeof globalThis.RTCPeerConnection !== 'undefined'
+            ? globalThis.RTCPeerConnection
+            : (() => {
+                throw new Error('RTCPeerConnection is not available. Please provide it in the Rondevu constructor options for Node.js environments.');
+            }));
+        this.RTCSessionDescription = rtcSessionDescription || (typeof globalThis.RTCSessionDescription !== 'undefined'
+            ? globalThis.RTCSessionDescription
+            : (() => {
+                throw new Error('RTCSessionDescription is not available. Please provide it in the Rondevu constructor options for Node.js environments.');
+            }));
+        this.RTCIceCandidate = rtcIceCandidate || (typeof globalThis.RTCIceCandidate !== 'undefined'
+            ? globalThis.RTCIceCandidate
+            : (() => {
+                throw new Error('RTCIceCandidate is not available. Please provide it in the Rondevu constructor options for Node.js environments.');
+            }));
+        this.pc = new this.RTCPeerConnection(rtcConfig);
         this._state = new IdleState(this);
         this.setupPeerConnection();
     }

package/dist/peer/state.js

@@ -18,7 +18,7 @@ export class PeerState {
     async handleIceCandidate(candidate) {
         // ICE candidates can arrive in multiple states, so default is to add them
         if (this.peer.pc.remoteDescription) {
-            await this.peer.pc.addIceCandidate(new RTCIceCandidate(candidate));
+            await this.peer.pc.addIceCandidate(new this.peer.RTCIceCandidate(candidate));
         }
     }
     /**

package/dist/rondevu.d.ts

@@ -22,6 +22,39 @@ export interface RondevuOptions {
      * ```
      */
     fetch?: FetchFunction;
+    /**
+     * Custom RTCPeerConnection implementation for Node.js environments
+     * Required when using in Node.js with wrtc or similar polyfills
+     *
+     * @example Node.js with wrtc
+     * ```typescript
+     * import { RTCPeerConnection } from 'wrtc';
+     * const client = new Rondevu({ RTCPeerConnection });
+     * ```
+     */
+    RTCPeerConnection?: typeof RTCPeerConnection;
+    /**
+     * Custom RTCSessionDescription implementation for Node.js environments
+     * Required when using in Node.js with wrtc or similar polyfills
+     *
+     * @example Node.js with wrtc
+     * ```typescript
+     * import { RTCSessionDescription } from 'wrtc';
+     * const client = new Rondevu({ RTCSessionDescription });
+     * ```
+     */
+    RTCSessionDescription?: typeof RTCSessionDescription;
+    /**
+     * Custom RTCIceCandidate implementation for Node.js environments
+     * Required when using in Node.js with wrtc or similar polyfills
+     *
+     * @example Node.js with wrtc
+     * ```typescript
+     * import { RTCIceCandidate } from 'wrtc';
+     * const client = new Rondevu({ RTCIceCandidate });
+     * ```
+     */
+    RTCIceCandidate?: typeof RTCIceCandidate;
 }
 export declare class Rondevu {
     readonly auth: RondevuAuth;
@@ -29,6 +62,9 @@ export declare class Rondevu {
     private credentials?;
     private baseUrl;
     private fetchFn?;
+    private rtcPeerConnection?;
+    private rtcSessionDescription?;
+    private rtcIceCandidate?;
     constructor(options?: RondevuOptions);
     /**
      * Get offers API (requires authentication)

package/dist/rondevu.js

@@ -5,6 +5,9 @@ export class Rondevu {
     constructor(options = {}) {
         this.baseUrl = options.baseUrl || 'https://api.ronde.vu';
         this.fetchFn = options.fetch;
+        this.rtcPeerConnection = options.RTCPeerConnection;
+        this.rtcSessionDescription = options.RTCSessionDescription;
+        this.rtcIceCandidate = options.RTCIceCandidate;
         this.auth = new RondevuAuth(this.baseUrl, this.fetchFn);
         if (options.credentials) {
             this.credentials = options.credentials;
@@ -52,6 +55,6 @@ export class Rondevu {
         if (!this._offers) {
             throw new Error('Not authenticated. Call register() first or provide credentials.');
         }
-        return new RondevuPeer(this._offers, rtcConfig);
+        return new RondevuPeer(this._offers, rtcConfig, this.rtcPeerConnection, this.rtcSessionDescription, this.rtcIceCandidate);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/rondevu-client",
-  "version": "0.7.3",
+  "version": "0.7.5",
   "description": "TypeScript client for Rondevu topic-based peer discovery and signaling server",
   "type": "module",
   "main": "dist/index.js",