@xtr-dev/rondevu-client 0.20.1 → 0.21.3

package/README.md

@@ -2,37 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-🌐 **WebRTC signaling client with durable connections**
+**WebRTC signaling client with durable connections**
 
-TypeScript/JavaScript client for Rondevu, providing WebRTC signaling with **automatic reconnection**, **message buffering**, 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
 
-### ✨ New in v0.20.0
-- **🔄 Automatic Reconnection**: Built-in exponential backoff for failed connections
-- **📦 Message Buffering**: Queues messages during disconnections, replays on reconnect
-- **🔄 Connection Persistence**: OffererConnection objects persist across disconnections via offer rotation
-- **📊 Connection State Machine**: Explicit lifecycle tracking with native RTC events
-- **🎯 Rich Event System**: 20+ events for monitoring connection health including `connection:rotated`
-- **⚡ Improved Reliability**: ICE polling lifecycle management, proper cleanup, rotation fallback
-- **🏗️ Internal Refactoring**: Cleaner codebase with OfferPool extraction and consolidated ICE polling
-
-### Core 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
-- **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
+- **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
 
@@ -42,412 +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
-  connectionConfig: {
-    reconnectEnabled: true,    // Auto-reconnect on failures
-    bufferEnabled: true,       // Buffer messages during disconnections
-    connectionTimeout: 30000   // 30 second timeout
-  }
-})
-
-// 3. Start accepting connections
-await rondevu.startFilling()
-
-// 4. Handle incoming connections
-rondevu.on('connection:opened', (offerId, connection) => {
-  console.log('New connection:', offerId)
-
-  // Listen for messages
-  connection.on('message', (data) => {
-    console.log('Received:', data)
-  })
-
-  // Monitor connection state
-  connection.on('connected', () => {
-    console.log('Fully connected!')
-    connection.send('Hello from Alice!')
-  })
-
-  connection.on('disconnected', () => {
-    console.log('Connection lost, will auto-reconnect')
-  })
-})
-```
+// ============================================
+// ALICE: Host and wait for connections
+// ============================================
+const alice = await Rondevu.connect({ username: 'alice' })
 
-### Connecting to a Service (Answerer)
-
-```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'
-})
-
-// 2. Connect to service - returns AnswererConnection
-const connection = await rondevu.connectToService({
-  serviceFqn: 'chat:1.0.0@alice',
-  connectionConfig: {
-    reconnectEnabled: true,
-    bufferEnabled: true,
-    maxReconnectAttempts: 5
-  }
+alice.on('connection:opened', (offerId, connection) => {
+  console.log('Connected to', connection.peerUsername)
+  connection.on('message', (data) => console.log('Received:', data))
+  connection.send('Hello!')
 })
 
-// 3. Setup event handlers
-connection.on('connected', () => {
-  console.log('Connected to alice!')
-  connection.send('Hello from Bob!')
-})
+const offer = await alice.offer({ tags: ['chat'], maxOffers: 5 })
+// Later: offer.cancel() to stop accepting connections
 
-connection.on('message', (data) => {
-  console.log('Received:', data)
-})
+// ============================================
+// BOB: Connect to Alice
+// ============================================
+const bob = await Rondevu.connect()
 
-// 4. Monitor connection health
-connection.on('reconnecting', (attempt) => {
-  console.log(`Reconnecting... attempt ${attempt}`)
+const peer = await bob.peer({
+  username: 'alice',
+  tags: ['chat']
 })
 
-connection.on('reconnect:success', () => {
-  console.log('Back online!')
-})
-
-connection.on('failed', (error) => {
-  console.error('Connection failed:', error)
-})
+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
 })
-```
-
-### Service Publishing
 
-```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)
-  connectionConfig?: Partial<ConnectionConfig>  // Optional: durability settings
-})
-
-await rondevu.startFilling()  // Start accepting connections
-rondevu.stopFilling()         // Stop and close all connections
+rondevu.getName()       // Get username
+rondevu.getCredential() // Get credential for reuse
 ```
 
-### Connecting to Services
+**ICE Presets**: `'rondevu'` (default), `'rondevu-relay'`, `'google-stun'`, `'public-stun'`
 
-**⚠️ Breaking Change in v0.18.9+:** `connectToService()` now returns `AnswererConnection` instead of `ConnectionContext`.
+### rondevu.peer()
 
 ```typescript
-// New API (v0.18.9/v0.18.11+)
-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)
-  connectionConfig?: Partial<ConnectionConfig>,  // Durability settings
-  rtcConfig?: RTCConfiguration  // Optional: override ICE servers
-})
-
-// Setup event handlers
-connection.on('connected', () => {
-  connection.send('Hello!')
-})
-
-connection.on('message', (data) => {
-  console.log(data)
-})
-```
-
-### Connection Configuration
-
-```typescript
-interface ConnectionConfig {
-  // Timeouts
-  connectionTimeout: number      // Default: 30000ms (30s)
-  iceGatheringTimeout: number    // Default: 10000ms (10s)
-
-  // Reconnection
-  reconnectEnabled: boolean      // Default: true
-  maxReconnectAttempts: number   // Default: 5 (0 = infinite)
-  reconnectBackoffBase: number   // Default: 1000ms
-  reconnectBackoffMax: number    // Default: 30000ms (30s)
-
-  // Message buffering
-  bufferEnabled: boolean         // Default: true
-  maxBufferSize: number          // Default: 100 messages
-  maxBufferAge: number           // Default: 60000ms (1 min)
-
-  // Debug
-  debug: boolean                 // Default: false
-}
-```
-
-### Connection Events
-
-```typescript
-// Lifecycle events
-connection.on('connecting', () => {})
-connection.on('connected', () => {})
-connection.on('disconnected', (reason) => {})
-connection.on('failed', (error) => {})
-connection.on('closed', (reason) => {})
-
-// Reconnection events
-connection.on('reconnecting', (attempt) => {})
-connection.on('reconnect:success', () => {})
-connection.on('reconnect:failed', (error) => {})
-connection.on('reconnect:exhausted', (attempts) => {})
-
-// Message events
-connection.on('message', (data) => {})
-connection.on('message:buffered', (data) => {})
-connection.on('message:replayed', (message) => {})
-
-// ICE events
-connection.on('ice:connection:state', (state) => {})
-connection.on('ice:polling:started', () => {})
-connection.on('ice:polling:stopped', () => {})
+const peer = await rondevu.peer({
+  tags: string[],
+  username?: string,
+  rtcConfig?: RTCConfiguration
+})
+
+// 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
-
-```typescript
-// Unified discovery API
-const service = await rondevu.findService(
-  'chat:1.0.0@alice',  // Direct lookup (with username)
-  { mode: 'direct' }
-)
-
-const service = await rondevu.findService(
-  'chat:1.0.0',  // Random discovery (without username)
-  { mode: 'random' }
-)
-
-const result = await rondevu.findService(
-  'chat:1.0.0',
-  {
-    mode: 'paginated',
-    limit: 20,
-    offset: 0
-  }
-)
-```
-
-## Migration Guide
-
-**Upgrading from v0.18.10 or earlier?** See [MIGRATION.md](./MIGRATION.md) for detailed upgrade instructions.
-
-### Quick Migration Summary
-
-**Before (v0.18.7/v0.18.10):**
-```typescript
-const context = await rondevu.connectToService({
-  serviceFqn: 'chat:1.0.0@alice',
-  onConnection: ({ dc }) => {
-    dc.addEventListener('message', (e) => console.log(e.data))
-    dc.send('Hello')
-  }
-})
-```
+### rondevu.offer()
 
-**After (v0.18.9/v0.18.11):**
 ```typescript
-const connection = await rondevu.connectToService({
-  serviceFqn: '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)
 })
 
-connection.on('connected', () => {
-  connection.send('Hello')  // Use connection.send()
-})
+offer.cancel()  // Stop accepting connections
 
-connection.on('message', (data) => {
-  console.log(data)  // data is already extracted
+rondevu.on('connection:opened', (offerId, connection) => {
+  connection.on('message', (data) => {})
+  connection.send('Hello!')
 })
 ```
 
-## Advanced Usage
-
-### Custom Offer Factory
+### rondevu.discover()
 
 ```typescript
-await rondevu.publishService({
-  service: 'file-transfer:1.0.0',
-  maxOffers: 3,
-  offerFactory: async (pc) => {
-    // Customize data channel settings
-    const dc = pc.createDataChannel('files', {
-      ordered: true,
-      maxRetransmits: 10
-    })
-
-    // Add custom listeners
-    dc.addEventListener('open', () => {
-      console.log('Transfer channel ready')
-    })
-
-    const offer = await pc.createOffer()
-    await pc.setLocalDescription(offer)
-    return { dc, offer }
-  }
-})
+const result = await rondevu.discover(['chat'], { limit: 20 })
+result.offers.forEach(o => console.log(o.username, o.tags))
 ```
 
-### Accessing Raw RTCPeerConnection
+## Credentials
 
 ```typescript
-const connection = await rondevu.connectToService({ ... })
-
-// Get raw objects if needed
-const pc = connection.getPeerConnection()
-const dc = connection.getDataChannel()
-
-// Note: Using raw DataChannel bypasses buffering/reconnection features
-if (dc) {
-  dc.addEventListener('message', (e) => {
-    console.log('Raw message:', e.data)
-  })
-}
-```
+// Auto-generated username
+const rondevu = await Rondevu.connect()
+// rondevu.getName() === 'friendly-panda-a1b2c3'
 
-### Disabling Durability Features
+// Claimed username
+const rondevu = await Rondevu.connect({ username: 'alice' })
 
-```typescript
-const connection = await rondevu.connectToService({
-  serviceFqn: 'chat:1.0.0@alice',
-  connectionConfig: {
-    reconnectEnabled: false,  // Disable auto-reconnect
-    bufferEnabled: false,     // Disable message buffering
-  }
-})
-```
+// Save and restore credentials
+const credential = rondevu.getCredential()
+localStorage.setItem('cred', JSON.stringify(credential))
 
-## Documentation
-
-📚 **[MIGRATION.md](./MIGRATION.md)** - Upgrade guide from v0.18.7 to v0.18.9
+const saved = JSON.parse(localStorage.getItem('cred'))
+const rondevu = await Rondevu.connect({ credential: saved })
+```
 
-📚 **[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
+## Tag Validation
 
-## Connection Persistence (v0.20.0+)
+Tags: 1-64 chars, lowercase alphanumeric with dots/dashes.
 
-Connection objects now persist across disconnections via **"offer rotation"**. When a connection fails, the same connection object is rebound to a new offer instead of being destroyed:
+Valid: `chat`, `video-call`, `com.example.service`
 
-```typescript
-rondevu.on('connection:opened', (offerId, connection) => {
-    console.log(`Connection ${offerId} opened`)
-
-    // Listen for offer rotation
-    rondevu.on('connection:rotated', (oldOfferId, newOfferId, conn) => {
-        if (conn === connection) {
-            console.log(`Connection rotated: ${oldOfferId} → ${newOfferId}`)
-            // Same connection object! Event listeners still work
-            // Message buffer preserved
-        }
-    })
-
-    connection.on('message', (data) => {
-        console.log('Received:', data)
-        // This listener continues working even after rotation
-    })
-
-    connection.on('failed', () => {
-        console.log('Connection failed, will auto-rotate to new offer')
-    })
-})
-```
+## Links
 
-**Benefits:**
-- ✅ Same connection object remains usable through disconnections
-- ✅ Message buffer preserved during temporary disconnections
-- ✅ Event listeners don't need to be re-registered
-- ✅ Seamless reconnection experience for offerer side
-
-## Examples
-
-- [React Demo](https://github.com/xtr-dev/rondevu-demo) - Full browser UI ([live](https://ronde.vu))
-
-## Changelog
-
-### v0.20.0 (Latest)
-- **Connection Persistence** - OffererConnection objects now persist across disconnections
-- **Offer Rotation** - When connection fails, same object is rebound to new offer
-- **Message Buffering** - Now works seamlessly on offerer side through rotations
-- **New Event**: `connection:rotated` emitted when offer is rotated
-- **Internal**: Added `OffererConnection.rebindToOffer()` method
-- **Internal**: Modified OfferPool failure handler to rotate offers instead of destroying connections
-- **Internal**: Added rotation lock to prevent concurrent rotations
-- **Internal**: Added max rotation attempts limit (default: 5)
-- 100% backward compatible - no breaking changes
-
-### v0.19.0
-- **Internal Refactoring** - Improved codebase maintainability (no API changes)
-- Extract OfferPool class for offer lifecycle management
-- Consolidate ICE polling logic (remove ~86 lines of duplicate code)
-- Add AsyncLock utility for race-free concurrent operations
-- Disable reconnection for offerer connections (offers are ephemeral)
-- 100% backward compatible - upgrade without code changes
-
-### v0.18.11
-- Restore EventEmitter-based durable connections (same as v0.18.9)
-- Durable WebRTC connections with state machine
-- Automatic reconnection with exponential backoff
-- Message buffering during disconnections
-- ICE polling lifecycle management
-- **Breaking:** `connectToService()` returns `AnswererConnection` instead of `ConnectionContext`
-- See [MIGRATION.md](./MIGRATION.md) for upgrade guide
-
-### v0.18.10
-- Temporary revert to callback-based API (reverted in v0.18.11)
-
-### v0.18.9
-- Add durable WebRTC connections with state machine
-- Implement automatic reconnection with exponential backoff
-- Add message buffering during disconnections
-- Fix ICE polling lifecycle (stops when connected)
-- Add fillOffers() semaphore to prevent exceeding maxOffers
-- **Breaking:** `connectToService()` returns `AnswererConnection` instead of `ConnectionContext`
-- **Breaking:** `connection:opened` event signature changed
-- See [MIGRATION.md](./MIGRATION.md) for upgrade guide
-
-### v0.18.8
-- Initial durable connections implementation
-
-### v0.18.3
-- Fix EventEmitter cross-platform compatibility
+- [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

@@ -1,61 +1,83 @@
 /**
- * RPC Batcher - Throttles and batches RPC requests to reduce HTTP overhead
+ * 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 {
-    /**
-     * Maximum number of requests to batch together
-     * Default: 10
-     */
+    /** Delay in ms before flushing queued requests (default: 10) */
+    delay?: number;
+    /** Maximum batch size for unauthenticated requests (default: 50) */
     maxBatchSize?: number;
-    /**
-     * Maximum time to wait before sending a batch (ms)
-     * Default: 50ms
-     */
-    maxWaitTime?: number;
-    /**
-     * Minimum time between batches (ms)
-     * Default: 10ms
-     */
-    throttleInterval?: number;
 }
 /**
- * Batches and throttles RPC requests to optimize network usage
+ * RpcBatcher - Batches RPC requests with throttling
  *
  * @example
  * ```typescript
- * const batcher = new RpcBatcher(
- *   (requests) => api.rpcBatch(requests),
- *   { maxBatchSize: 10, maxWaitTime: 50 }
- * )
+ * const batcher = new RpcBatcher('https://api.example.com', {
+ *   delay: 10,
+ *   maxBatchSize: 50
+ * })
  *
- * // These will be batched together if called within maxWaitTime
- * const result1 = await batcher.add(request1)
- * const result2 = await batcher.add(request2)
- * const result3 = await batcher.add(request3)
+ * // 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 batchTimeout;
-    private lastBatchTime;
-    private options;
-    private sendBatch;
-    constructor(sendBatch: (requests: any[]) => Promise<any[]>, options?: BatcherOptions);
+    private flushTimer;
+    private readonly delay;
+    private readonly maxBatchSize;
+    constructor(baseUrl: string, options?: BatcherOptions);
     /**
-     * Add an RPC request to the batch queue
-     * Returns a promise that resolves when the request completes
+     * 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: any): Promise<any>;
+    add(request: RpcRequest, authHeaders: Record<string, string> | null): Promise<any>;
     /**
-     * Flush the queue immediately
+     * Schedule a flush after the delay
      */
-    flush(): Promise<void>;
+    private scheduleFlush;
     /**
-     * Get current queue size
+     * Flush all queued requests
      */
-    getQueueSize(): number;
+    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;
     /**
-     * Clear the queue without sending
+     * Flush immediately (useful for cleanup/testing)
      */
-    clear(): void;
+    flushNow(): Promise<void>;
 }