0.7.8

- Add secret field to PeerOptions interface
- Pass secret when creating offers in CreatingOfferState
- Pass secret when answering offers in AnsweringState
- Bump version to 0.7.7

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -1,14 +1,15 @@
-# @xtr-dev/rondevu-client
+# Rondevu Client
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
 🌐 **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-demo](https://rondevu-demo.pages.dev) - Interactive demo
+- [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
+- [@xtr-dev/rondevu-server](https://github.com/xtr-dev/rondevu-server) - HTTP signaling server ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-server), [live](https://api.ronde.vu))
+- [@xtr-dev/rondevu-demo](https://github.com/xtr-dev/rondevu-demo) - Interactive demo ([live](https://ronde.vu))
 
 ---
 
@@ -16,9 +17,12 @@ TypeScript/JavaScript client for Rondevu, providing topic-based peer discovery,
 
 - **Topic-Based Discovery**: Find peers by topics (e.g., torrent infohashes)
 - **Stateless Authentication**: No server-side sessions, portable credentials
+- **Protected Connections**: Optional secret-protected offers for access control
 - **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,38 +33,45 @@ 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
 });
 
-conn.on('datachannel', (channel) => {
-  console.log('Data channel ready');
+peer.on('connected', () => {
+  console.log('✅ Connected to peer!');
+});
 
-  channel.onmessage = (event) => {
-    console.log('Received:', event.data);
-  };
+peer.on('datachannel', (channel) => {
+  console.log('📡 Data channel ready');
 
-  channel.send('Hello from peer A!');
+  channel.addEventListener('message', (event) => {
+    console.log('📥 Received:', event.data);
+  });
+
+  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
+  ttl: 300000,  // 5 minutes
+  secret: 'my-secret-password'  // Optional: protect offer (max 128 chars)
 });
 
 console.log('Offer created:', offerId);
@@ -72,6 +83,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 +93,143 @@ 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,
+    secret: 'my-secret-password'  // Required if offer.hasSecret is true
+  });
 }
 ```
 
-### Connection Events
+## Protected Offers
+
+You can protect offers with a secret to control who can answer them. This is useful for private rooms or invite-only connections.
+
+### Creating a Protected Offer
 
 ```typescript
-conn.on('connecting', () => {
-  // Connection is being established
+const offerId = await peer.createOffer({
+  topics: ['private-room'],
+  secret: 'my-secret-password'  // Max 128 characters
 });
 
-conn.on('connected', () => {
+// Share the secret with authorized peers through a secure channel
+```
+
+### Answering a Protected Offer
+
+```typescript
+const offers = await client.offers.findByTopic('private-room');
+
+// Check if offer requires a secret
+if (offers[0].hasSecret) {
+  console.log('This offer requires a secret');
+}
+
+// Provide the secret when answering
+await peer.answer(offers[0].id, offers[0].sdp, {
+  topics: offers[0].topics,
+  secret: 'my-secret-password'  // Must match the offer's secret
+});
+```
+
+**Notes:**
+- The actual secret is never exposed in public API responses - only a `hasSecret` boolean flag
+- Answerers must provide the correct secret, or the answer will be rejected
+- Secrets are limited to 128 characters
+- Use this for access control, not for cryptographic security (use end-to-end encryption for that)
+
+## 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
+peer.on('state', (stateName) => {
+  console.log('Current state:', stateName);
+});
+
+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 +238,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
-console.log(conn.id);
+// Get offer ID (after creating offer or answering)
+console.log(peer.offerId);
 
-// Get data channel
-console.log(conn.channel);
+// Get role
+console.log(peer.role); // 'offerer' or 'answerer'
 ```
 
-### Closing a Connection
+## Closing a Connection
 
 ```typescript
-conn.close();
+await peer.close();
+```
+
+## Custom RTCConfiguration
+
+```typescript
+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 +322,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 +392,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';
@@ -248,7 +410,8 @@ localStorage.setItem('rondevu-creds', JSON.stringify(creds));
 const offers = await client.offers.create([{
   sdp: 'v=0...',  // Your WebRTC offer SDP
   topics: ['movie-xyz', 'hd-content'],
-  ttl: 300000  // 5 minutes
+  ttl: 300000,  // 5 minutes
+  secret: 'my-secret-password'  // Optional: protect offer (max 128 chars)
 }]);
 
 // Discover peers by topic
@@ -313,7 +476,8 @@ const offers = await client.offers.create([
   {
     sdp: 'v=0...',
     topics: ['topic-1', 'topic-2'],
-    ttl: 300000  // optional, default 5 minutes
+    ttl: 300000,  // optional, default 5 minutes
+    secret: 'my-secret-password'  // optional, max 128 chars
   }
 ]);
 ```
@@ -335,13 +499,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.
 
@@ -349,13 +506,18 @@ Delete a specific offer.
 await client.offers.delete(offerId);
 ```
 
-#### `client.offers.answer(offerId, sdp)`
+#### `client.offers.answer(offerId, sdp, secret?)`
 Answer an offer (locks it to answerer).
 
 ```typescript
-await client.offers.answer(offerId, answerSdp);
+await client.offers.answer(offerId, answerSdp, 'my-secret-password');
 ```
 
+**Parameters:**
+- `offerId`: The offer ID to answer
+- `sdp`: The WebRTC answer SDP
+- `secret` (optional): Required if the offer has `hasSecret: true`
+
 #### `client.offers.getAnswers()`
 Poll for answers to your offers.
 
@@ -370,7 +532,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 +540,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 +576,9 @@ import type {
   IceCandidate,
   FetchFunction,
   RondevuOptions,
-  ConnectionOptions,
-  RondevuConnectionEvents
+  PeerOptions,
+  PeerEvents,
+  PeerTimeouts
 } from '@xtr-dev/rondevu-client';
 ```
 
@@ -423,28 +586,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) |
 
-**If your environment doesn't have native fetch:**
+**For signaling-only (no WebRTC peer connections):**
+
+Use the low-level API with `client.offers` - no WebRTC polyfills needed.
+
+**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-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@xtr-dev/rondevu-client",
-  "version": "0.7.0",
+  "version": "0.7.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@xtr-dev/rondevu-client",
-      "version": "0.7.0",
+      "version": "0.7.8",
       "license": "MIT",
       "dependencies": {
         "@xtr-dev/rondevu-client": "^0.5.1"

package.json

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

src/client.ts

@@ -1,208 +0,0 @@
-import {
-  RondevuClientOptions,
-  CreateOfferRequest,
-  CreateOfferResponse,
-  AnswerRequest,
-  AnswerResponse,
-  PollRequest,
-  PollOffererResponse,
-  PollAnswererResponse,
-  VersionResponse,
-  HealthResponse,
-  ErrorResponse,
-  Side,
-} from './types.js';
-
-/**
- * HTTP API client for Rondevu peer signaling server
- */
-export class RondevuAPI {
-  private readonly baseUrl: string;
-  private readonly fetchImpl: typeof fetch;
-
-  /**
-   * Creates a new Rondevu API client instance
-   * @param options - Client configuration options
-   */
-  constructor(options: RondevuClientOptions) {
-    this.baseUrl = options.baseUrl.replace(/\/$/, ''); // Remove trailing slash
-    this.fetchImpl = options.fetch || globalThis.fetch.bind(globalThis);
-  }
-
-  /**
-   * Makes an HTTP request to the Rondevu server
-   */
-  private async request<T>(
-    endpoint: string,
-    options: RequestInit = {}
-  ): Promise<T> {
-    const url = `${this.baseUrl}${endpoint}`;
-
-    const headers: Record<string, string> = {
-      ...(options.headers as Record<string, string>),
-    };
-
-    if (options.body) {
-      headers['Content-Type'] = 'application/json';
-    }
-
-    const response = await this.fetchImpl(url, {
-      ...options,
-      headers,
-    });
-
-    const data = await response.json();
-
-    if (!response.ok) {
-      const error = data as ErrorResponse;
-      throw new Error(error.error || `HTTP ${response.status}: ${response.statusText}`);
-    }
-
-    return data as T;
-  }
-
-  /**
-   * Gets server version information
-   *
-   * @returns Server version
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   * const { version } = await api.getVersion();
-   * console.log('Server version:', version);
-   * ```
-   */
-  async getVersion(): Promise<VersionResponse> {
-    return this.request<VersionResponse>('/', {
-      method: 'GET',
-    });
-  }
-
-  /**
-   * Creates a new offer
-   *
-   * @param request - Offer details including peer ID, signaling data, and optional custom code
-   * @returns Unique offer code (UUID or custom code)
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   * const { code } = await api.createOffer({
-   *   peerId: 'peer-123',
-   *   offer: signalingData,
-   *   code: 'my-custom-code' // optional
-   * });
-   * console.log('Offer code:', code);
-   * ```
-   */
-  async createOffer(request: CreateOfferRequest): Promise<CreateOfferResponse> {
-    return this.request<CreateOfferResponse>('/offer', {
-      method: 'POST',
-      body: JSON.stringify(request),
-    });
-  }
-
-  /**
-   * Sends an answer or candidate to an existing offer
-   *
-   * @param request - Answer details including offer code and signaling data
-   * @returns Success confirmation
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   *
-   * // Send answer
-   * await api.sendAnswer({
-   *   code: offerCode,
-   *   answer: answerData,
-   *   side: 'answerer'
-   * });
-   *
-   * // Send candidate
-   * await api.sendAnswer({
-   *   code: offerCode,
-   *   candidate: candidateData,
-   *   side: 'offerer'
-   * });
-   * ```
-   */
-  async sendAnswer(request: AnswerRequest): Promise<AnswerResponse> {
-    return this.request<AnswerResponse>('/answer', {
-      method: 'POST',
-      body: JSON.stringify(request),
-    });
-  }
-
-  /**
-   * Polls for offer data from the other peer
-   *
-   * @param code - Offer code
-   * @param side - Which side is polling ('offerer' or 'answerer')
-   * @returns Offer data including offers, answers, and candidates
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   *
-   * // Offerer polls for answer
-   * const offererData = await api.poll(offerCode, 'offerer');
-   * if (offererData.answer) {
-   *   console.log('Received answer:', offererData.answer);
-   * }
-   *
-   * // Answerer polls for offer
-   * const answererData = await api.poll(offerCode, 'answerer');
-   * console.log('Received offer:', answererData.offer);
-   * ```
-   */
-  async poll(
-    code: string,
-    side: Side
-  ): Promise<PollOffererResponse | PollAnswererResponse> {
-    const request: PollRequest = { code, side };
-    return this.request<PollOffererResponse | PollAnswererResponse>('/poll', {
-      method: 'POST',
-      body: JSON.stringify(request),
-    });
-  }
-
-  /**
-   * Checks server health and version
-   *
-   * @returns Health status, timestamp, and version
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   * const health = await api.health();
-   * console.log('Server status:', health.status);
-   * console.log('Server version:', health.version);
-   * ```
-   */
-  async health(): Promise<HealthResponse> {
-    return this.request<HealthResponse>('/health', {
-      method: 'GET',
-    });
-  }
-
-  /**
-   * Ends a session by deleting the offer from the server
-   *
-   * @param code - The offer code
-   * @returns Success confirmation
-   *
-   * @example
-   * ```typescript
-   * const api = new RondevuAPI({ baseUrl: 'https://example.com' });
-   * await api.leave('my-offer-code');
-   * ```
-   */
-  async leave(code: string): Promise<{ success: boolean }> {
-    return this.request<{ success: boolean }>('/leave', {
-      method: 'POST',
-      body: JSON.stringify({ code }),
-    });
-  }
-}

src/offers.ts

@@ -8,6 +8,7 @@ export interface CreateOfferRequest {
   sdp: string;
   topics: string[];
   ttl?: number;
+  secret?: string;
 }
 
 export interface Offer {
@@ -18,6 +19,8 @@ export interface Offer {
   createdAt?: number;
   expiresAt: number;
   lastSeen: number;
+  secret?: string;
+  hasSecret?: boolean;
   answererPeerId?: string;
   answerSdp?: string;
   answeredAt?: number;
@@ -143,11 +146,13 @@ export class RondevuOffers {
   async getTopics(options?: {
     limit?: number;
     offset?: number;
+    startsWith?: string;
   }): Promise<{
     topics: TopicInfo[];
     total: number;
     limit: number;
     offset: number;
+    startsWith?: string;
   }> {
     const params = new URLSearchParams();
 
@@ -159,6 +164,10 @@ export class RondevuOffers {
       params.set('offset', options.offset.toString());
     }
 
+    if (options?.startsWith) {
+      params.set('startsWith', options.startsWith);
+    }
+
     const url = `${this.baseUrl}/topics${
       params.toString() ? '?' + params.toString() : ''
     }`;
@@ -195,23 +204,6 @@ export class RondevuOffers {
     return data.offers;
   }
 
-  /**
-   * Update offer heartbeat
-   */
-  async heartbeat(offerId: string): Promise<void> {
-    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
    */
@@ -232,14 +224,14 @@ export class RondevuOffers {
   /**
    * Answer an offer
    */
-  async answer(offerId: string, sdp: string): Promise<void> {
+  async answer(offerId: string, sdp: string, secret?: string): Promise<void> {
     const response = await this.fetchFn(`${this.baseUrl}/offers/${encodeURIComponent(offerId)}/answer`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
         Authorization: RondevuAuth.createAuthHeader(this.credentials),
       },
-      body: JSON.stringify({ sdp }),
+      body: JSON.stringify({ sdp, secret }),
     });
 
     if (!response.ok) {

src/peer/answering-state.ts

@@ -25,25 +25,18 @@ export class AnsweringState extends PeerState {
 
       // Create answer
       const answer = await this.peer.pc.createAnswer();
+
+      // Send answer to server BEFORE setLocalDescription
+      // This registers us as the answerer so ICE candidates will be accepted
+      await this.peer.offersApi.answer(offerId, answer.sdp!, options.secret);
+
+      // Enable trickle ICE - set up handler before ICE gathering starts
+      this.setupIceCandidateHandler();
+
+      // Set local description - ICE gathering starts here
+      // Server already knows we're the answerer, so candidates will be accepted
       await this.peer.pc.setLocalDescription(answer);
 
-      // Send answer to server immediately (don't wait for ICE)
-      await this.peer.offersApi.answer(offerId, answer.sdp!);
-
-      // Enable trickle ICE - send candidates as they arrive
-      this.peer.pc.onicecandidate = async (event: RTCPeerConnectionIceEvent) => {
-        if (event.candidate && offerId) {
-          const candidateData = event.candidate.toJSON();
-          if (candidateData.candidate && candidateData.candidate !== '') {
-            try {
-              await this.peer.offersApi.addIceCandidates(offerId, [candidateData]);
-            } catch (err) {
-              console.error('Error sending ICE candidate:', err);
-            }
-          }
-        }
-      };
-
       // Transition to exchanging ICE
       const { ExchangingIceState } = await import('./exchanging-ice-state.js');
       this.peer.setState(new ExchangingIceState(this.peer, offerId, options));

src/peer/creating-offer-state.ts

@@ -24,33 +24,24 @@ export class CreatingOfferState extends PeerState {
         this.peer.emitEvent('datachannel', channel);
       }
 
+      // Enable trickle ICE - set up handler before ICE gathering starts
+      // Handler will check this.peer.offerId before sending
+      this.setupIceCandidateHandler();
+
       // Create WebRTC offer
       const offer = await this.peer.pc.createOffer();
-      await this.peer.pc.setLocalDescription(offer);
+      await this.peer.pc.setLocalDescription(offer); // ICE gathering starts here
 
       // Send offer to server immediately (don't wait for ICE)
       const offers = await this.peer.offersApi.create([{
         sdp: offer.sdp!,
         topics: options.topics,
-        ttl: options.ttl || 300000
+        ttl: options.ttl || 300000,
+        secret: options.secret
       }]);
 
       const offerId = offers[0].id;
-      this.peer.offerId = offerId;
-
-      // Enable trickle ICE - send candidates as they arrive
-      this.peer.pc.onicecandidate = async (event: RTCPeerConnectionIceEvent) => {
-        if (event.candidate && offerId) {
-          const candidateData = event.candidate.toJSON();
-          if (candidateData.candidate && candidateData.candidate !== '') {
-            try {
-              await this.peer.offersApi.addIceCandidates(offerId, [candidateData]);
-            } catch (err) {
-              console.error('Error sending ICE candidate:', err);
-            }
-          }
-        }
-      };
+      this.peer.offerId = offerId; // Now handler can send candidates
 
       // Transition to waiting for answer
       const { WaitingForAnswerState } = await import('./waiting-for-answer-state.js');

src/peer/exchanging-ice-state.ts

@@ -43,7 +43,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) {
               console.warn('Failed to add ICE candidate:', err);

src/peer/index.ts

@@ -24,8 +24,19 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
   offerId?: string;
   role?: 'offerer' | 'answerer';
 
+  // WebRTC polyfills for Node.js compatibility
+  RTCPeerConnection: typeof RTCPeerConnection;
+  RTCSessionDescription: typeof RTCSessionDescription;
+  RTCIceCandidate: typeof RTCIceCandidate;
+
   private _state: PeerState;
 
+  // Event handler references for cleanup
+  private connectionStateChangeHandler?: () => void;
+  private dataChannelHandler?: (event: RTCDataChannelEvent) => void;
+  private trackHandler?: (event: RTCTrackEvent) => void;
+  private iceCandidateErrorHandler?: (event: Event) => void;
+
   /**
    * Current connection state name
    */
@@ -54,11 +65,34 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
         { urls: 'stun:stun.l.google.com:19302' },
         { urls: 'stun:stun1.l.google.com:19302' }
       ]
-    }
+    },
+    rtcPeerConnection?: typeof RTCPeerConnection,
+    rtcSessionDescription?: typeof RTCSessionDescription,
+    rtcIceCandidate?: typeof 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.');
+        }) as any);
+
+    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.');
+        }) as any);
+
+    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.');
+        }) as any);
+
+    this.pc = new this.RTCPeerConnection(rtcConfig);
     this._state = new IdleState(this);
 
     this.setupPeerConnection();
@@ -68,7 +102,7 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
    * Set up peer connection event handlers
    */
   private setupPeerConnection(): void {
-    this.pc.onconnectionstatechange = () => {
+    this.connectionStateChangeHandler = () => {
       switch (this.pc.connectionState) {
         case 'connected':
           this.setState(new ConnectedState(this));
@@ -86,18 +120,22 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
           break;
       }
     };
+    this.pc.addEventListener('connectionstatechange', this.connectionStateChangeHandler);
 
-    this.pc.ondatachannel = (event) => {
+    this.dataChannelHandler = (event: RTCDataChannelEvent) => {
       this.emitEvent('datachannel', event.channel);
     };
+    this.pc.addEventListener('datachannel', this.dataChannelHandler);
 
-    this.pc.ontrack = (event) => {
+    this.trackHandler = (event: RTCTrackEvent) => {
       this.emitEvent('track', event);
     };
+    this.pc.addEventListener('track', this.trackHandler);
 
-    this.pc.onicecandidateerror = (event) => {
+    this.iceCandidateErrorHandler = (event: Event) => {
       console.error('ICE candidate error:', event);
     };
+    this.pc.addEventListener('icecandidateerror', this.iceCandidateErrorHandler);
   }
 
   /**
@@ -145,6 +183,20 @@ export default class RondevuPeer extends EventEmitter<PeerEvents> {
    * Close the connection and clean up
    */
   async close(): Promise<void> {
+    // Remove RTCPeerConnection event listeners
+    if (this.connectionStateChangeHandler) {
+      this.pc.removeEventListener('connectionstatechange', this.connectionStateChangeHandler);
+    }
+    if (this.dataChannelHandler) {
+      this.pc.removeEventListener('datachannel', this.dataChannelHandler);
+    }
+    if (this.trackHandler) {
+      this.pc.removeEventListener('track', this.trackHandler);
+    }
+    if (this.iceCandidateErrorHandler) {
+      this.pc.removeEventListener('icecandidateerror', this.iceCandidateErrorHandler);
+    }
+
     await this._state.close();
     this.removeAllListeners();
   }

src/peer/state.ts

@@ -6,6 +6,8 @@ import type RondevuPeer from './index.js';
  * Implements the State pattern for managing WebRTC connection lifecycle
  */
 export abstract class PeerState {
+  protected iceCandidateHandler?: (event: RTCPeerConnectionIceEvent) => void;
+
   constructor(protected peer: RondevuPeer) {}
 
   abstract get name(): string;
@@ -25,12 +27,35 @@ export abstract class PeerState {
   async handleIceCandidate(candidate: any): Promise<void> {
     // 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));
     }
   }
 
+  /**
+   * Setup trickle ICE candidate handler
+   * Sends local ICE candidates to server as they are discovered
+   */
+  protected setupIceCandidateHandler(): void {
+    this.iceCandidateHandler = async (event: RTCPeerConnectionIceEvent) => {
+      if (event.candidate && this.peer.offerId) {
+        const candidateData = event.candidate.toJSON();
+        if (candidateData.candidate && candidateData.candidate !== '') {
+          try {
+            await this.peer.offersApi.addIceCandidates(this.peer.offerId, [candidateData]);
+          } catch (err) {
+            console.error('Error sending ICE candidate:', err);
+          }
+        }
+      }
+    };
+    this.peer.pc.addEventListener('icecandidate', this.iceCandidateHandler);
+  }
+
   cleanup(): void {
-    // Override in states that need cleanup
+    // Clean up ICE candidate handler if it exists
+    if (this.iceCandidateHandler) {
+      this.peer.pc.removeEventListener('icecandidate', this.iceCandidateHandler);
+    }
   }
 
   async close(): Promise<void> {

src/peer/types.ts

@@ -22,6 +22,8 @@ export interface PeerOptions {
   topics: string[];
   /** How long the offer should live (milliseconds) */
   ttl?: number;
+  /** Optional secret to protect the offer (max 128 characters) */
+  secret?: string;
   /** Whether to create a data channel automatically (for offerer) */
   createDataChannel?: boolean;
   /** Label for the automatically created data channel */

src/rondevu.ts

@@ -25,6 +25,42 @@ 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 class Rondevu {
@@ -33,10 +69,16 @@ export class Rondevu {
   private credentials?: Credentials;
   private baseUrl: string;
   private fetchFn?: FetchFunction;
+  private rtcPeerConnection?: typeof RTCPeerConnection;
+  private rtcSessionDescription?: typeof RTCSessionDescription;
+  private rtcIceCandidate?: typeof RTCIceCandidate;
 
   constructor(options: RondevuOptions = {}) {
     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);
 
@@ -98,6 +140,12 @@ export class Rondevu {
       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
+    );
   }
 }

src/types.ts

@@ -1,182 +0,0 @@
-// ============================================================================
-// Signaling Types
-// ============================================================================
-
-/**
- * Session side - identifies which peer in a connection
- */
-export type Side = 'offerer' | 'answerer';
-
-/**
- * Request body for POST /offer
- */
-export interface CreateOfferRequest {
-  /** Peer identifier/metadata (max 1024 characters) */
-  peerId: string;
-  /** Signaling data for peer connection */
-  offer: string;
-  /** Optional custom connection code (if not provided, server generates UUID) */
-  code?: string;
-}
-
-/**
- * Response from POST /offer
- */
-export interface CreateOfferResponse {
-  /** Unique session identifier (UUID) */
-  code: string;
-}
-
-/**
- * Request body for POST /answer
- */
-export interface AnswerRequest {
-  /** Session UUID from the offer */
-  code: string;
-  /** Response signaling data (required if candidate not provided) */
-  answer?: string;
-  /** Additional signaling data (required if answer not provided) */
-  candidate?: string;
-  /** Which peer is sending the data */
-  side: Side;
-}
-
-/**
- * Response from POST /answer
- */
-export interface AnswerResponse {
-  success: boolean;
-}
-
-/**
- * Request body for POST /poll
- */
-export interface PollRequest {
-  /** Session UUID */
-  code: string;
-  /** Which side is polling */
-  side: Side;
-}
-
-/**
- * Response from POST /poll when side=offerer
- */
-export interface PollOffererResponse {
-  /** Answer from answerer (null if not yet received) */
-  answer: string | null;
-  /** Additional signaling data from answerer */
-  answerCandidates: string[];
-}
-
-/**
- * Response from POST /poll when side=answerer
- */
-export interface PollAnswererResponse {
-  /** Offer from offerer */
-  offer: string;
-  /** Additional signaling data from offerer */
-  offerCandidates: string[];
-}
-
-/**
- * Response from POST /poll (union type)
- */
-export type PollResponse = PollOffererResponse | PollAnswererResponse;
-
-/**
- * Response from GET / - server version information
- */
-export interface VersionResponse {
-  /** Git commit hash or version identifier */
-  version: string;
-}
-
-/**
- * Response from GET /health
- */
-export interface HealthResponse {
-  status: 'ok';
-  timestamp: number;
-  version: string;
-}
-
-/**
- * Error response structure
- */
-export interface ErrorResponse {
-  error: string;
-}
-
-/**
- * Client configuration options
- */
-export interface RondevuClientOptions {
-  /** Base URL of the Rondevu server (e.g., 'https://example.com') */
-  baseUrl: string;
-  /** Optional fetch implementation (for Node.js environments) */
-  fetch?: typeof fetch;
-}
-
-// ============================================================================
-// WebRTC Types
-// ============================================================================
-
-/**
- * WebRTC polyfill for Node.js and other non-browser platforms
- */
-export interface WebRTCPolyfill {
-  RTCPeerConnection: typeof RTCPeerConnection;
-  RTCSessionDescription: typeof RTCSessionDescription;
-  RTCIceCandidate: typeof RTCIceCandidate;
-}
-
-/**
- * Configuration options for Rondevu WebRTC client
- */
-export interface RondevuOptions {
-  /** Base URL of the Rondevu server (defaults to 'https://api.ronde.vu') */
-  baseUrl?: string;
-  /** Peer identifier (optional, auto-generated if not provided) */
-  peerId?: string;
-  /** Optional fetch implementation (for Node.js environments) */
-  fetch?: typeof fetch;
-  /** WebRTC configuration (ICE servers, etc.) */
-  rtcConfig?: RTCConfiguration;
-  /** Polling interval in milliseconds (default: 1000) */
-  pollingInterval?: number;
-  /** Connection timeout in milliseconds (default: 30000) */
-  connectionTimeout?: number;
-  /** WebRTC polyfill for Node.js (e.g., wrtc or @roamhq/wrtc) */
-  wrtc?: WebRTCPolyfill;
-}
-
-/**
- * Connection role - whether this peer is creating or answering
- */
-export type ConnectionRole = 'offerer' | 'answerer';
-
-/**
- * Parameters for creating a RondevuConnection
- */
-export interface RondevuConnectionParams {
-  id: string;
-  topic?: string;
-  role: ConnectionRole;
-  pc: RTCPeerConnection;
-  localPeerId: string;
-  remotePeerId: string;
-  pollingInterval: number;
-  connectionTimeout: number;
-  wrtc?: WebRTCPolyfill;
-}
-
-/**
- * Event map for RondevuConnection events
- */
-export interface RondevuConnectionEvents {
-  connect: () => void;
-  disconnect: () => void;
-  error: (error: Error) => void;
-  datachannel: (channel: RTCDataChannel) => void;
-  stream: (stream: MediaStream) => void;
-}