@xtr-dev/rondevu-client 0.3.4 → 0.4.0

package/README.md

@@ -1,112 +1,453 @@
-# Rondevu
+# @xtr-dev/rondevu-client
 
-🎯 **Simple WebRTC peer signaling**
+[![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**
 
-Connect peers directly by ID with automatic WebRTC negotiation.
+TypeScript/JavaScript client for Rondevu, providing topic-based peer discovery, stateless authentication, and complete WebRTC signaling.
 
 **Related repositories:**
-- [rondevu-server](https://github.com/xtr-dev/rondevu-server) - HTTP signaling server
-- [rondevu-demo](https://github.com/xtr-dev/rondevu-demo) - Interactive demo
+- [rondevu-server](https://github.com/xtr-dev/rondevu) - HTTP signaling server
+- [rondevu-demo](https://rondevu-demo.pages.dev) - Interactive demo
 
 ---
 
-## @xtr-dev/rondevu-client
-
-[![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
+## Features
 
-TypeScript client library for Rondevu peer signaling and WebRTC connection management. Handles automatic signaling, ICE candidate exchange, and connection establishment.
+- **Topic-Based Discovery**: Find peers by topics (e.g., torrent infohashes)
+- **Stateless Authentication**: No server-side sessions, portable credentials
+- **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
+- **TypeScript**: Full type safety and autocomplete
 
-### Install
+## Install
 
 ```bash
 npm install @xtr-dev/rondevu-client
 ```
 
-### Usage
+## 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.
 
-#### Browser
+### Creating an Offer (Peer A)
 
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client';
 
-const rdv = new Rondevu({
-  baseUrl: 'https://api.ronde.vu',
-  rtcConfig: {
-    iceServers: [
-      { urls: 'stun:stun.l.google.com:19302' },
-      { urls: 'stun:stun1.l.google.com:19302' }
-    ]
-  }
+const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
+await client.register();
+
+// Create a connection
+const conn = client.createConnection();
+
+// Set up event listeners
+conn.on('connected', () => {
+  console.log('Connected to peer!');
 });
 
-// Create an offer with custom ID
-const connection = await rdv.offer('my-room-123');
+conn.on('datachannel', (channel) => {
+  console.log('Data channel ready');
 
-// Or answer an existing offer
-const connection = await rdv.answer('my-room-123');
+  channel.onmessage = (event) => {
+    console.log('Received:', event.data);
+  };
+
+  channel.send('Hello from peer A!');
+});
 
-// Use data channels
-connection.on('connect', () => {
-  const channel = connection.dataChannel('chat');
-  channel.send('Hello!');
+// Create offer and advertise on topics
+const offerId = await conn.createOffer({
+  topics: ['my-app', 'room-123'],
+  ttl: 300000  // 5 minutes
 });
 
-connection.on('datachannel', (channel) => {
-  if (channel.label === 'chat') {
+console.log('Offer created:', offerId);
+console.log('Share these topics with peers:', ['my-app', 'room-123']);
+```
+
+### Answering an Offer (Peer B)
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
+await client.register();
+
+// Discover offers by topic
+const offers = await client.offers.findByTopic('my-app', { limit: 10 });
+
+if (offers.length > 0) {
+  const offer = offers[0];
+
+  // Create connection
+  const conn = client.createConnection();
+
+  // Set up event listeners
+  conn.on('connecting', () => {
+    console.log('Connecting...');
+  });
+
+  conn.on('connected', () => {
+    console.log('Connected!');
+  });
+
+  conn.on('datachannel', (channel) => {
+    console.log('Data channel ready');
+
     channel.onmessage = (event) => {
       console.log('Received:', event.data);
     };
-  }
+
+    channel.send('Hello from peer B!');
+  });
+
+  // Answer the offer
+  await conn.answer(offer.id, offer.sdp);
+}
+```
+
+### Connection Events
+
+```typescript
+conn.on('connecting', () => {
+  // Connection is being established
+});
+
+conn.on('connected', () => {
+  // Connection established successfully
+});
+
+conn.on('disconnected', () => {
+  // Connection lost or closed
+});
+
+conn.on('error', (error) => {
+  // An error occurred
+  console.error('Connection error:', error);
+});
+
+conn.on('datachannel', (channel) => {
+  // Data channel is ready to use
+});
+
+conn.on('track', (event) => {
+  // Media track received (for audio/video streaming)
+  const stream = event.streams[0];
+  videoElement.srcObject = stream;
 });
 ```
 
-#### Node.js
+### Adding Media Tracks
+
+```typescript
+// Get user's camera/microphone
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: true,
+  audio: true
+});
+
+// Add tracks to connection
+stream.getTracks().forEach(track => {
+  conn.addTrack(track, stream);
+});
+```
+
+### Connection Properties
+
+```typescript
+// Get connection state
+console.log(conn.connectionState); // 'connecting', 'connected', 'disconnected', etc.
+
+// Get offer ID
+console.log(conn.id);
+
+// Get data channel
+console.log(conn.channel);
+```
+
+### Closing a Connection
+
+```typescript
+conn.close();
+```
+
+## Platform-Specific Setup
+
+### Node.js 18+ (with native fetch)
+
+Works out of the box - no additional setup needed.
+
+### Node.js < 18 (without native fetch)
+
+Install node-fetch and provide it to the client:
+
+```bash
+npm install node-fetch
+```
 
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client';
-import wrtc from '@roamhq/wrtc';
 import fetch from 'node-fetch';
 
-const rdv = new Rondevu({
+const client = new Rondevu({
   baseUrl: 'https://api.ronde.vu',
-  fetch: fetch as any,
-  wrtc: {
-    RTCPeerConnection: wrtc.RTCPeerConnection,
-    RTCSessionDescription: wrtc.RTCSessionDescription,
-    RTCIceCandidate: wrtc.RTCIceCandidate,
+  fetch: fetch as any
+});
+```
+
+### Deno
+
+```typescript
+import { Rondevu } from 'npm:@xtr-dev/rondevu-client';
+
+const client = new Rondevu({
+  baseUrl: 'https://api.ronde.vu'
+});
+```
+
+### Bun
+
+Works out of the box - no additional setup needed.
+
+### Cloudflare Workers
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const client = new Rondevu({
+      baseUrl: 'https://api.ronde.vu'
+    });
+
+    const creds = await client.register();
+    return new Response(JSON.stringify(creds));
   }
+};
+```
+
+## Low-Level API Usage
+
+For advanced use cases where you need direct control over the signaling process, you can use the low-level API:
+
+```typescript
+import { Rondevu, BloomFilter } from '@xtr-dev/rondevu-client';
+
+const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
+
+// Register and get credentials
+const creds = await client.register();
+console.log('Peer ID:', creds.peerId);
+
+// Save credentials for later use
+localStorage.setItem('rondevu-creds', JSON.stringify(creds));
+
+// Create offer with topics
+const offers = await client.offers.create([{
+  sdp: 'v=0...',  // Your WebRTC offer SDP
+  topics: ['movie-xyz', 'hd-content'],
+  ttl: 300000  // 5 minutes
+}]);
+
+// Discover peers by topic
+const discovered = await client.offers.findByTopic('movie-xyz', {
+  limit: 50
+});
+
+console.log(`Found ${discovered.length} peers`);
+
+// Use bloom filter to exclude known peers
+const knownPeers = new Set(['peer-id-1', 'peer-id-2']);
+const bloom = new BloomFilter(1024, 3);
+knownPeers.forEach(id => bloom.add(id));
+
+const newPeers = await client.offers.findByTopic('movie-xyz', {
+  bloomFilter: bloom.toBytes(),
+  limit: 50
+});
+```
+
+## API Reference
+
+### Authentication
+
+#### `client.register()`
+Register a new peer and receive credentials.
+
+```typescript
+const creds = await client.register();
+// { peerId: '...', secret: '...' }
+```
+
+### Topics
+
+#### `client.offers.getTopics(options?)`
+List all topics with active peer counts (paginated).
+
+```typescript
+const result = await client.offers.getTopics({
+  limit: 50,
+  offset: 0
 });
 
-const connection = await rdv.offer('my-room-123');
+// {
+//   topics: [
+//     { topic: 'movie-xyz', activePeers: 42 },
+//     { topic: 'torrent-abc', activePeers: 15 }
+//   ],
+//   total: 123,
+//   limit: 50,
+//   offset: 0
+// }
+```
+
+### Offers
+
+#### `client.offers.create(offers)`
+Create one or more offers with topics.
+
+```typescript
+const offers = await client.offers.create([
+  {
+    sdp: 'v=0...',
+    topics: ['topic-1', 'topic-2'],
+    ttl: 300000  // optional, default 5 minutes
+  }
+]);
+```
+
+#### `client.offers.findByTopic(topic, options?)`
+Find offers by topic with optional bloom filter.
 
-connection.on('connect', () => {
-  const channel = connection.dataChannel('chat');
-  channel.send('Hello from Node.js!');
+```typescript
+const offers = await client.offers.findByTopic('movie-xyz', {
+  limit: 50,
+  bloomFilter: bloomBytes  // optional
 });
 ```
 
-### API
+#### `client.offers.getMine()`
+Get all offers owned by the authenticated peer.
+
+```typescript
+const myOffers = await client.offers.getMine();
+```
+
+#### `client.offers.heartbeat(offerId)`
+Update last_seen timestamp for an offer.
 
-**Main Methods:**
-- `rdv.offer(id)` - Create an offer with custom ID
-- `rdv.answer(id)` - Answer an existing offer by ID
+```typescript
+await client.offers.heartbeat(offerId);
+```
 
-**Connection Events:**
-- `connect` - Connection established
-- `disconnect` - Connection closed
-- `error` - Connection error
-- `datachannel` - New data channel received
-- `stream` - Media stream received
+#### `client.offers.delete(offerId)`
+Delete a specific offer.
 
-**Connection Methods:**
-- `connection.dataChannel(label)` - Get or create data channel
-- `connection.addStream(stream)` - Add media stream
-- `connection.close()` - Close connection
+```typescript
+await client.offers.delete(offerId);
+```
 
-### Version Compatibility
+#### `client.offers.answer(offerId, sdp)`
+Answer an offer (locks it to answerer).
 
-The client automatically checks server compatibility via the `/health` endpoint. If the server version is incompatible, an error will be thrown during initialization.
+```typescript
+await client.offers.answer(offerId, answerSdp);
+```
+
+#### `client.offers.getAnswers()`
+Poll for answers to your offers.
+
+```typescript
+const answers = await client.offers.getAnswers();
+```
+
+### ICE Candidates
+
+#### `client.offers.addIceCandidates(offerId, candidates)`
+Post ICE candidates for an offer.
+
+```typescript
+await client.offers.addIceCandidates(offerId, [
+  'candidate:1 1 UDP...'
+]);
+```
+
+#### `client.offers.getIceCandidates(offerId, since?)`
+Get ICE candidates from the other peer.
+
+```typescript
+const candidates = await client.offers.getIceCandidates(offerId);
+```
+
+### Bloom Filter
+
+```typescript
+import { BloomFilter } from '@xtr-dev/rondevu-client';
+
+// Create filter: size=1024 bits, hash=3 functions
+const bloom = new BloomFilter(1024, 3);
+
+// Add items
+bloom.add('peer-id-1');
+bloom.add('peer-id-2');
+
+// Test membership
+bloom.test('peer-id-1');  // true (probably)
+bloom.test('unknown');    // false (definitely)
+
+// Export for API
+const bytes = bloom.toBytes();
+```
+
+## TypeScript
+
+All types are exported:
+
+```typescript
+import type {
+  Credentials,
+  Offer,
+  CreateOfferRequest,
+  TopicInfo,
+  IceCandidate,
+  FetchFunction,
+  RondevuOptions,
+  ConnectionOptions,
+  RondevuConnectionEvents
+} from '@xtr-dev/rondevu-client';
+```
+
+## Environment Compatibility
+
+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 |
+
+**If your environment doesn't have native fetch:**
+
+```bash
+npm install node-fetch
+```
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+import fetch from 'node-fetch';
+
+const client = new Rondevu({
+  baseUrl: 'https://rondevu.xtrdev.workers.dev',
+  fetch: fetch as any
+});
+```
 
-### License
+## License
 
 MIT

package/dist/auth.d.ts

@@ -0,0 +1,18 @@
+export interface Credentials {
+    peerId: string;
+    secret: string;
+}
+export type FetchFunction = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export declare class RondevuAuth {
+    private baseUrl;
+    private fetchFn;
+    constructor(baseUrl: string, fetchFn?: FetchFunction);
+    /**
+     * Register a new peer and receive credentials
+     */
+    register(): Promise<Credentials>;
+    /**
+     * Create Authorization header value
+     */
+    static createAuthHeader(credentials: Credentials): string;
+}

package/dist/auth.js

@@ -0,0 +1,39 @@
+export class RondevuAuth {
+    constructor(baseUrl, fetchFn) {
+        this.baseUrl = baseUrl;
+        // Use provided fetch or fall back to global fetch
+        this.fetchFn = fetchFn || ((...args) => {
+            if (typeof globalThis.fetch === 'function') {
+                return globalThis.fetch(...args);
+            }
+            throw new Error('fetch is not available. Please provide a fetch implementation in the constructor options.');
+        });
+    }
+    /**
+     * Register a new peer and receive credentials
+     */
+    async register() {
+        const response = await this.fetchFn(`${this.baseUrl}/register`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({}),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Registration failed: ${error.error || response.statusText}`);
+        }
+        const data = await response.json();
+        return {
+            peerId: data.peerId,
+            secret: data.secret,
+        };
+    }
+    /**
+     * Create Authorization header value
+     */
+    static createAuthHeader(credentials) {
+        return `Bearer ${credentials.peerId}:${credentials.secret}`;
+    }
+}

package/dist/bloom.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Simple bloom filter implementation for peer ID exclusion
+ * Uses multiple hash functions for better distribution
+ */
+export declare class BloomFilter {
+    private bits;
+    private size;
+    private numHashes;
+    constructor(size?: number, numHashes?: number);
+    /**
+     * Add a peer ID to the filter
+     */
+    add(peerId: string): void;
+    /**
+     * Test if peer ID might be in the filter
+     */
+    test(peerId: string): boolean;
+    /**
+     * Get raw bits for transmission
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Convert to base64 for URL parameters
+     */
+    toBase64(): string;
+    /**
+     * Simple hash function (FNV-1a variant)
+     */
+    private hash;
+}

package/dist/bloom.js

@@ -0,0 +1,73 @@
+/**
+ * Simple bloom filter implementation for peer ID exclusion
+ * Uses multiple hash functions for better distribution
+ */
+export class BloomFilter {
+    constructor(size = 1024, numHashes = 3) {
+        this.size = size;
+        this.numHashes = numHashes;
+        this.bits = new Uint8Array(Math.ceil(size / 8));
+    }
+    /**
+     * Add a peer ID to the filter
+     */
+    add(peerId) {
+        for (let i = 0; i < this.numHashes; i++) {
+            const hash = this.hash(peerId, i);
+            const index = hash % this.size;
+            const byteIndex = Math.floor(index / 8);
+            const bitIndex = index % 8;
+            this.bits[byteIndex] |= 1 << bitIndex;
+        }
+    }
+    /**
+     * Test if peer ID might be in the filter
+     */
+    test(peerId) {
+        for (let i = 0; i < this.numHashes; i++) {
+            const hash = this.hash(peerId, i);
+            const index = hash % this.size;
+            const byteIndex = Math.floor(index / 8);
+            const bitIndex = index % 8;
+            if (!(this.bits[byteIndex] & (1 << bitIndex))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Get raw bits for transmission
+     */
+    toBytes() {
+        return this.bits;
+    }
+    /**
+     * Convert to base64 for URL parameters
+     */
+    toBase64() {
+        // Convert Uint8Array to regular array then to string
+        const binaryString = String.fromCharCode(...Array.from(this.bits));
+        // Use btoa for browser, or Buffer for Node.js
+        if (typeof btoa !== 'undefined') {
+            return btoa(binaryString);
+        }
+        else if (typeof Buffer !== 'undefined') {
+            return Buffer.from(this.bits).toString('base64');
+        }
+        else {
+            // Fallback: manual base64 encoding
+            throw new Error('No base64 encoding available');
+        }
+    }
+    /**
+     * Simple hash function (FNV-1a variant)
+     */
+    hash(str, seed) {
+        let hash = 2166136261 ^ seed;
+        for (let i = 0; i < str.length; i++) {
+            hash ^= str.charCodeAt(i);
+            hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+        }
+        return hash >>> 0;
+    }
+}

package/dist/client.d.ts

@@ -108,4 +108,19 @@ export declare class RondevuAPI {
      * ```
      */
     health(): Promise<HealthResponse>;
+    /**
+     * 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');
+     * ```
+     */
+    leave(code: string): Promise<{
+        success: boolean;
+    }>;
 }