@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/README.md

@@ -2,28 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-🌐 **Simple WebRTC signaling client with username-based discovery**
+**WebRTC signaling client with durable connections**
 
-TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with username claiming, service publishing/discovery, and efficient batch polling.
-
-**Related repositories:**
-- [@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))
-
----
+TypeScript client for [Rondevu](https://github.com/xtr-dev/rondevu-server), providing WebRTC signaling with automatic reconnection, message buffering, and tags-based discovery.
 
 ## Features
 
-- **Username Claiming**: Secure ownership with Ed25519 signatures
-- **Anonymous Users**: Auto-generated anonymous usernames for quick testing
-- **Service Publishing**: Publish services with multiple offers for connection pooling
-- **Service Discovery**: Direct lookup, random discovery, or paginated search
-- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates (50% fewer requests)
-- **Semantic Version Matching**: Compatible version resolution (chat:1.0.0 matches any 1.x.x)
-- **TypeScript**: Full type safety and autocomplete
-- **Keypair Management**: Generate or reuse Ed25519 keypairs
-- **Automatic Signatures**: All authenticated requests signed automatically
+- **Simple Peer API**: Connect with `rondevu.peer({ tags, username })`
+- **Tags-Based Discovery**: Find peers using tags (e.g., `["chat", "video"]`)
+- **Automatic Reconnection**: Built-in exponential backoff
+- **Message Buffering**: Queues messages during disconnections
 
 ## Installation
 
@@ -33,144 +21,131 @@ npm install @xtr-dev/rondevu-client
 
 ## Quick Start
 
-### Publishing a Service (Offerer)
-
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client'
 
-// 1. Connect to Rondevu
-const rondevu = await Rondevu.connect({
-  apiUrl: 'https://api.ronde.vu',
-  username: 'alice',  // Or omit for anonymous username
-  iceServers: 'ipv4-turn'  // Preset: 'ipv4-turn', 'hostname-turns', 'google-stun', 'relay-only'
-})
-
-// 2. Publish service with automatic offer management
-await rondevu.publishService({
-  service: 'chat:1.0.0',
-  maxOffers: 5,  // Maintain up to 5 concurrent offers
-  offerFactory: async (pc) => {
-    // pc is created by Rondevu with ICE handlers already attached
-    const dc = pc.createDataChannel('chat')
-
-    dc.addEventListener('open', () => {
-      console.log('Connection opened!')
-      dc.send('Hello from Alice!')
-    })
-
-    dc.addEventListener('message', (e) => {
-      console.log('Received:', e.data)
-    })
-
-    const offer = await pc.createOffer()
-    await pc.setLocalDescription(offer)
-    return { dc, offer }
-  }
-})
-
-// 3. Start accepting connections
-await rondevu.startFilling()
-```
-
-### Connecting to a Service (Answerer)
+// ============================================
+// ALICE: Host and wait for connections
+// ============================================
+const alice = await Rondevu.connect({ username: 'alice' })
 
-```typescript
-import { Rondevu } from '@xtr-dev/rondevu-client'
-
-// 1. Connect to Rondevu
-const rondevu = await Rondevu.connect({
-  apiUrl: 'https://api.ronde.vu',
-  username: 'bob',
-  iceServers: 'ipv4-turn'
+alice.on('connection:opened', (offerId, connection) => {
+  console.log('Connected to', connection.peerUsername)
+  connection.on('message', (data) => console.log('Received:', data))
+  connection.send('Hello!')
 })
 
-// 2. Connect to service (automatic WebRTC setup)
-const connection = await rondevu.connectToService({
-  serviceFqn: 'chat:1.0.0@alice',
-  onConnection: ({ dc, peerUsername }) => {
-    console.log('Connected to', peerUsername)
+const offer = await alice.offer({ tags: ['chat'], maxOffers: 5 })
+// Later: offer.cancel() to stop accepting connections
 
-    dc.addEventListener('message', (e) => {
-      console.log('Received:', e.data)
-    })
+// ============================================
+// BOB: Connect to Alice
+// ============================================
+const bob = await Rondevu.connect()
 
-    dc.addEventListener('open', () => {
-      dc.send('Hello from Bob!')
-    })
-  }
+const peer = await bob.peer({
+  username: 'alice',
+  tags: ['chat']
 })
 
-// Access connection
-connection.dc.send('Another message')
-connection.pc.close()  // Close when done
+peer.on('open', () => peer.send('Hello Alice!'))
+peer.on('message', (data) => console.log('Received:', data))
 ```
 
-## Core API
+## API Reference
 
 ### Rondevu.connect()
 
 ```typescript
 const rondevu = await Rondevu.connect({
-  apiUrl: string,          // Required: Signaling server URL
-  username?: string,       // Optional: your username (auto-generates anonymous if omitted)
-  keypair?: Keypair,       // Optional: reuse existing keypair
-  iceServers?: IceServerPreset | RTCIceServer[],  // Optional: preset or custom config
-  debug?: boolean          // Optional: enable debug logging (default: false)
+  apiUrl?: string,         // Default: 'https://api.ronde.vu'
+  credential?: Credential, // Reuse existing credential
+  username?: string,       // Claim username (4-32 chars)
+  iceServers?: IceServerPreset | RTCIceServer[],  // Default: 'rondevu'
+  debug?: boolean
 })
+
+rondevu.getName()       // Get username
+rondevu.getCredential() // Get credential for reuse
 ```
 
-### Service Publishing
+**ICE Presets**: `'rondevu'` (default), `'rondevu-relay'`, `'google-stun'`, `'public-stun'`
+
+### rondevu.peer()
 
 ```typescript
-await rondevu.publishService({
-  service: string,        // e.g., 'chat:1.0.0' (username auto-appended)
-  maxOffers: number,      // Maximum concurrent offers to maintain
-  offerFactory?: OfferFactory,  // Optional: custom offer creation
-  ttl?: number           // Optional: offer lifetime in ms (default: 300000)
+const peer = await rondevu.peer({
+  tags: string[],
+  username?: string,
+  rtcConfig?: RTCConfiguration
 })
 
-await rondevu.startFilling()  // Start accepting connections
-rondevu.stopFilling()         // Stop and close all connections
+// Events
+peer.on('open', () => {})
+peer.on('close', (reason) => {})
+peer.on('message', (data) => {})
+peer.on('error', (error) => {})
+peer.on('reconnecting', (attempt, max) => {})
+
+// Properties & Methods
+peer.state           // 'connecting' | 'connected' | 'reconnecting' | ...
+peer.peerUsername
+peer.send(data)
+peer.close()
 ```
 
-### Service Discovery
+### rondevu.offer()
 
 ```typescript
-// Direct lookup (with username)
-await rondevu.getService('chat:1.0.0@alice')
+const offer = await rondevu.offer({
+  tags: string[],
+  maxOffers: number,
+  ttl?: number,       // Offer lifetime in ms (default: 300000)
+  autoStart?: boolean // Auto-start filling (default: true)
+})
 
-// Random discovery (without username)
-await rondevu.discoverService('chat:1.0.0')
+offer.cancel()  // Stop accepting connections
 
-// Paginated discovery
-await rondevu.discoverServices('chat:1.0.0', limit, offset)
+rondevu.on('connection:opened', (offerId, connection) => {
+  connection.on('message', (data) => {})
+  connection.send('Hello!')
+})
 ```
 
-### Connecting to Services
+### rondevu.discover()
 
 ```typescript
-const connection = await rondevu.connectToService({
-  serviceFqn?: string,     // Full FQN like 'chat:1.0.0@alice'
-  service?: string,        // Service without username (for discovery)
-  username?: string,       // Target username (combined with service)
-  onConnection?: (context) => void,  // Called when data channel opens
-  rtcConfig?: RTCConfiguration  // Optional: override ICE servers
-})
+const result = await rondevu.discover(['chat'], { limit: 20 })
+result.offers.forEach(o => console.log(o.username, o.tags))
 ```
 
-## Documentation
+## Credentials
+
+```typescript
+// Auto-generated username
+const rondevu = await Rondevu.connect()
+// rondevu.getName() === 'friendly-panda-a1b2c3'
+
+// Claimed username
+const rondevu = await Rondevu.connect({ username: 'alice' })
+
+// Save and restore credentials
+const credential = rondevu.getCredential()
+localStorage.setItem('cred', JSON.stringify(credential))
+
+const saved = JSON.parse(localStorage.getItem('cred'))
+const rondevu = await Rondevu.connect({ credential: saved })
+```
+
+## Tag Validation
+
+Tags: 1-64 chars, lowercase alphanumeric with dots/dashes.
 
-📚 **[ADVANCED.md](./ADVANCED.md)** - Comprehensive guide including:
-- Detailed API reference for all methods
-- Type definitions and interfaces
-- Platform support (Browser & Node.js)
-- Advanced usage patterns
-- Username rules and service FQN format
-- Examples and migration guides
+Valid: `chat`, `video-call`, `com.example.service`
 
-## Examples
+## Links
 
-- [React Demo](https://github.com/xtr-dev/rondevu-demo) - Full browser UI ([live](https://ronde.vu))
+- [Live Demo](https://ronde.vu) | [Server](https://github.com/xtr-dev/rondevu-server) | [API](https://api.ronde.vu)
 
 ## License
 

package/dist/api/batcher.d.ts

@@ -0,0 +1,83 @@
+/**
+ * RPC Request Batcher with throttling
+ *
+ * Collects RPC requests over a short time window and sends them efficiently.
+ *
+ * Due to server authentication design (signature covers method+params),
+ * authenticated requests are sent individually while unauthenticated
+ * requests can be truly batched together.
+ */
+export interface RpcRequest {
+    method: string;
+    params?: any;
+}
+export interface RpcResponse {
+    success: boolean;
+    result?: any;
+    error?: string;
+    errorCode?: string;
+}
+export interface BatcherOptions {
+    /** Delay in ms before flushing queued requests (default: 10) */
+    delay?: number;
+    /** Maximum batch size for unauthenticated requests (default: 50) */
+    maxBatchSize?: number;
+}
+/**
+ * RpcBatcher - Batches RPC requests with throttling
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RpcBatcher('https://api.example.com', {
+ *   delay: 10,
+ *   maxBatchSize: 50
+ * })
+ *
+ * // Requests made within the delay window are batched
+ * const [result1, result2] = await Promise.all([
+ *   batcher.add({ method: 'getOffer', params: {...} }, null),
+ *   batcher.add({ method: 'getOffer', params: {...} }, null)
+ * ])
+ * ```
+ */
+export declare class RpcBatcher {
+    private readonly baseUrl;
+    private queue;
+    private flushTimer;
+    private readonly delay;
+    private readonly maxBatchSize;
+    constructor(baseUrl: string, options?: BatcherOptions);
+    /**
+     * Add a request to the batch queue
+     * @param request - The RPC request
+     * @param authHeaders - Auth headers for authenticated requests, null for unauthenticated
+     * @returns Promise that resolves with the request result
+     */
+    add(request: RpcRequest, authHeaders: Record<string, string> | null): Promise<any>;
+    /**
+     * Schedule a flush after the delay
+     */
+    private scheduleFlush;
+    /**
+     * Flush all queued requests
+     */
+    private flush;
+    /**
+     * Process unauthenticated requests in batches
+     */
+    private processUnauthenticatedBatches;
+    /**
+     * Process authenticated requests individually
+     * Each authenticated request needs its own HTTP call because
+     * the signature covers the specific method+params
+     */
+    private processAuthenticatedRequests;
+    /**
+     * Send a batch of requests
+     */
+    private sendBatch;
+    /**
+     * Flush immediately (useful for cleanup/testing)
+     */
+    flushNow(): Promise<void>;
+}

package/dist/api/batcher.js

@@ -0,0 +1,155 @@
+/**
+ * RPC Request Batcher with throttling
+ *
+ * Collects RPC requests over a short time window and sends them efficiently.
+ *
+ * Due to server authentication design (signature covers method+params),
+ * authenticated requests are sent individually while unauthenticated
+ * requests can be truly batched together.
+ */
+/**
+ * RpcBatcher - Batches RPC requests with throttling
+ *
+ * @example
+ * ```typescript
+ * const batcher = new RpcBatcher('https://api.example.com', {
+ *   delay: 10,
+ *   maxBatchSize: 50
+ * })
+ *
+ * // Requests made within the delay window are batched
+ * const [result1, result2] = await Promise.all([
+ *   batcher.add({ method: 'getOffer', params: {...} }, null),
+ *   batcher.add({ method: 'getOffer', params: {...} }, null)
+ * ])
+ * ```
+ */
+export class RpcBatcher {
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl;
+        this.queue = [];
+        this.flushTimer = null;
+        this.delay = options.delay ?? 10;
+        this.maxBatchSize = options.maxBatchSize ?? 50;
+    }
+    /**
+     * Add a request to the batch queue
+     * @param request - The RPC request
+     * @param authHeaders - Auth headers for authenticated requests, null for unauthenticated
+     * @returns Promise that resolves with the request result
+     */
+    add(request, authHeaders) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({ request, authHeaders, resolve, reject });
+            this.scheduleFlush();
+        });
+    }
+    /**
+     * Schedule a flush after the delay
+     */
+    scheduleFlush() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            this.flush();
+        }, this.delay);
+    }
+    /**
+     * Flush all queued requests
+     */
+    async flush() {
+        if (this.queue.length === 0)
+            return;
+        const items = this.queue;
+        this.queue = [];
+        // Separate authenticated vs unauthenticated requests
+        const unauthenticated = [];
+        const authenticated = [];
+        for (const item of items) {
+            if (item.authHeaders) {
+                authenticated.push(item);
+            }
+            else {
+                unauthenticated.push(item);
+            }
+        }
+        // Process unauthenticated requests in batches
+        await this.processUnauthenticatedBatches(unauthenticated);
+        // Process authenticated requests individually (each needs unique signature)
+        await this.processAuthenticatedRequests(authenticated);
+    }
+    /**
+     * Process unauthenticated requests in batches
+     */
+    async processUnauthenticatedBatches(items) {
+        if (items.length === 0)
+            return;
+        // Split into chunks of maxBatchSize
+        for (let i = 0; i < items.length; i += this.maxBatchSize) {
+            const chunk = items.slice(i, i + this.maxBatchSize);
+            await this.sendBatch(chunk, null);
+        }
+    }
+    /**
+     * Process authenticated requests individually
+     * Each authenticated request needs its own HTTP call because
+     * the signature covers the specific method+params
+     */
+    async processAuthenticatedRequests(items) {
+        // Send all authenticated requests in parallel, each as its own batch of 1
+        await Promise.all(items.map(item => this.sendBatch([item], item.authHeaders)));
+    }
+    /**
+     * Send a batch of requests
+     */
+    async sendBatch(items, authHeaders) {
+        try {
+            const requests = items.map(item => item.request);
+            const headers = {
+                'Content-Type': 'application/json',
+            };
+            if (authHeaders) {
+                Object.assign(headers, authHeaders);
+            }
+            const response = await fetch(`${this.baseUrl}/rpc`, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(requests), // Always send as array
+            });
+            if (!response.ok) {
+                const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+                items.forEach(item => item.reject(error));
+                return;
+            }
+            const results = await response.json();
+            // Match responses to requests (server returns array in same order)
+            items.forEach((item, index) => {
+                const result = results[index];
+                if (!result) {
+                    item.reject(new Error('Missing response from server'));
+                }
+                else if (!result.success) {
+                    item.reject(new Error(result.error || 'RPC call failed'));
+                }
+                else {
+                    item.resolve(result.result);
+                }
+            });
+        }
+        catch (error) {
+            // Network or parsing error - reject all
+            items.forEach(item => item.reject(error));
+        }
+    }
+    /**
+     * Flush immediately (useful for cleanup/testing)
+     */
+    async flushNow() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+}