@xtr-dev/rondevu-client 0.13.0 → 0.17.0

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-🌐 **Simple, high-level WebRTC peer-to-peer connections**
+🌐 **Simple WebRTC signaling client with username-based discovery**
 
-TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connections with automatic signaling, username-based discovery, and built-in reconnection support.
+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))
@@ -15,18 +15,17 @@ TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connectio
 
 ## Features
 
-- **High-Level Wrappers**: ServiceHost and ServiceClient eliminate WebRTC boilerplate
-- **Username-Based Discovery**: Connect to peers by username, not complex offer/answer exchange
-- **Semver-Compatible Matching**: Requesting chat@1.0.0 matches any compatible 1.x.x version
-- **Privacy-First Design**: Services are hidden by default - no enumeration possible
-- **Automatic Reconnection**: Built-in retry logic with exponential backoff
-- **Message Queuing**: Messages sent while disconnected are queued and flushed on reconnect
-- **Cryptographic Username Claiming**: Secure ownership with Ed25519 signatures
-- **Service Publishing**: Package-style naming (chat.app@1.0.0) with multiple simultaneous offers
+- **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
-- **Configurable Polling**: Exponential backoff with jitter to reduce server load
+- **Keypair Management**: Generate or reuse Ed25519 keypairs
+- **Automatic Signatures**: All authenticated requests signed automatically
 
-## Install
+## Installation
 
 ```bash
 npm install @xtr-dev/rondevu-client
@@ -34,424 +33,144 @@ npm install @xtr-dev/rondevu-client
 
 ## Quick Start
 
-### Hosting a Service (Alice)
+### Publishing a Service (Offerer)
 
 ```typescript
-import { RondevuService, ServiceHost } from '@xtr-dev/rondevu-client'
-
-// Step 1: Create and initialize service
-const service = new RondevuService({
-    apiUrl: 'https://api.ronde.vu',
-    username: 'alice'
-})
-
-await service.initialize()  // Generates keypair
-await service.claimUsername()  // Claims username with signature
-
-// Step 2: Create ServiceHost
-const host = new ServiceHost({
-    service: 'chat.app@1.0.0',
-    rondevuService: service,
-    maxPeers: 5,  // Accept up to 5 connections
-    ttl: 300000   // 5 minutes
-})
-
-// Step 3: Listen for incoming connections
-host.events.on('connection', (connection) => {
-    console.log('✅ New connection!')
-
-    connection.events.on('message', (msg) => {
-        console.log('📨 Received:', msg)
-        connection.sendMessage('Hello from Alice!')
+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 (rtcConfig) => {
+    const pc = new RTCPeerConnection(rtcConfig)
+    const dc = pc.createDataChannel('chat')
+
+    dc.addEventListener('open', () => {
+      console.log('Connection opened!')
+      dc.send('Hello from Alice!')
     })
 
-    connection.events.on('state-change', (state) => {
-        console.log('Connection state:', state)
+    dc.addEventListener('message', (e) => {
+      console.log('Received:', e.data)
     })
-})
 
-host.events.on('error', (error) => {
-    console.error('Host error:', error)
+    const offer = await pc.createOffer()
+    await pc.setLocalDescription(offer)
+    return { pc, dc, offer }
+  }
 })
 
-// Step 4: Start hosting
-await host.start()
-console.log('Service is now live! Others can connect to @alice')
-
-// Later: stop hosting
-host.dispose()
+// 3. Start accepting connections
+await rondevu.startFilling()
 ```
 
-### Connecting to a Service (Bob)
+### Connecting to a Service (Answerer)
 
 ```typescript
-import { RondevuService, ServiceClient } from '@xtr-dev/rondevu-client'
-
-// Step 1: Create and initialize service
-const service = new RondevuService({
-    apiUrl: 'https://api.ronde.vu',
-    username: 'bob'
-})
-
-await service.initialize()
-await service.claimUsername()
+import { Rondevu } from '@xtr-dev/rondevu-client'
 
-// Step 2: Create ServiceClient
-const client = new ServiceClient({
-    username: 'alice',  // Connect to Alice
-    serviceFqn: 'chat.app@1.0.0',
-    rondevuService: service,
-    autoReconnect: true,
-    maxReconnectAttempts: 5
+// 1. Connect to Rondevu
+const rondevu = await Rondevu.connect({
+  apiUrl: 'https://api.ronde.vu',
+  username: 'bob',
+  iceServers: 'ipv4-turn'
 })
 
-// Step 3: Listen for connection events
-client.events.on('connected', (connection) => {
-    console.log('✅ Connected to Alice!')
+// 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)
 
-    connection.events.on('message', (msg) => {
-        console.log('📨 Received:', msg)
+    dc.addEventListener('message', (e) => {
+      console.log('Received:', e.data)
     })
 
-    // Send a message
-    connection.sendMessage('Hello from Bob!')
-})
-
-client.events.on('disconnected', () => {
-    console.log('🔌 Disconnected')
-})
-
-client.events.on('reconnecting', ({ attempt, maxAttempts }) => {
-    console.log(`🔄 Reconnecting (${attempt}/${maxAttempts})...`)
-})
-
-client.events.on('error', (error) => {
-    console.error('❌ Error:', error)
+    dc.addEventListener('open', () => {
+      dc.send('Hello from Bob!')
+    })
+  }
 })
 
-// Step 4: Connect
-await client.connect()
-
-// Later: disconnect
-client.dispose()
+// Access connection
+connection.dc.send('Another message')
+connection.pc.close()  // Close when done
 ```
 
-## Core Concepts
-
-### RondevuService
-
-Handles authentication and username management:
-- Generates Ed25519 keypair for signing
-- Claims usernames with cryptographic proof
-- Provides API client for signaling server
-
-### ServiceHost
-
-High-level wrapper for hosting a WebRTC service:
-- Automatically creates and publishes offers
-- Handles incoming connections
-- Manages ICE candidate exchange
-- Supports multiple simultaneous peers
-
-### ServiceClient
+## Core API
 
-High-level wrapper for connecting to services:
-- Discovers services by username
-- Handles offer/answer exchange automatically
-- Built-in auto-reconnection with exponential backoff
-- Event-driven API
-
-### RTCDurableConnection
-
-Low-level connection wrapper (used internally):
-- Manages WebRTC PeerConnection lifecycle
-- Handles ICE candidate polling
-- Provides message queue for reliability
-- State management and events
-
-## API Reference
-
-### RondevuService
-
-```typescript
-const service = new RondevuService({
-    apiUrl: string,           // Signaling server URL
-    username: string,         // Your username
-    keypair?: Keypair         // Optional: reuse existing keypair
-})
-
-// Initialize service (generates keypair if not provided)
-await service.initialize(): Promise<void>
-
-// Claim username with cryptographic signature
-await service.claimUsername(): Promise<void>
-
-// Check if username is claimed
-service.isUsernameClaimed(): boolean
-
-// Get current username
-service.getUsername(): string
-
-// Get keypair
-service.getKeypair(): Keypair
-
-// Get API client
-service.getAPI(): RondevuAPI
-```
-
-### ServiceHost
+### Rondevu.connect()
 
 ```typescript
-const host = new ServiceHost({
-    service: string,              // Service FQN (e.g., 'chat.app@1.0.0')
-    rondevuService: RondevuService,
-    maxPeers?: number,            // Default: 5
-    ttl?: number,                 // Default: 300000 (5 minutes)
-    isPublic?: boolean,           // Default: true
-    rtcConfiguration?: RTCConfiguration
+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)
 })
-
-// Start hosting
-await host.start(): Promise<void>
-
-// Stop hosting and cleanup
-host.dispose(): void
-
-// Get all active connections
-host.getConnections(): RTCDurableConnection[]
-
-// Events
-host.events.on('connection', (conn: RTCDurableConnection) => {})
-host.events.on('error', (error: Error) => {})
 ```
 
-### ServiceClient
+### Service Publishing
 
 ```typescript
-const client = new ServiceClient({
-    username: string,             // Host username to connect to
-    serviceFqn: string,          // Service FQN (e.g., 'chat.app@1.0.0')
-    rondevuService: RondevuService,
-    autoReconnect?: boolean,     // Default: true
-    maxReconnectAttempts?: number, // Default: 5
-    rtcConfiguration?: RTCConfiguration
+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)
 })
 
-// Connect to service
-await client.connect(): Promise<RTCDurableConnection>
-
-// Disconnect and cleanup
-client.dispose(): void
-
-// Get current connection
-client.getConnection(): RTCDurableConnection | null
-
-// Events
-client.events.on('connected', (conn: RTCDurableConnection) => {})
-client.events.on('disconnected', () => {})
-client.events.on('reconnecting', (info: { attempt: number, maxAttempts: number }) => {})
-client.events.on('error', (error: Error) => {})
+await rondevu.startFilling()  // Start accepting connections
+rondevu.stopFilling()         // Stop and close all connections
 ```
 
-### RTCDurableConnection
+### Service Discovery
 
 ```typescript
-// Connection state
-connection.state: 'connected' | 'connecting' | 'disconnected'
-
-// Send message (returns true if sent, false if queued)
-await connection.sendMessage(message: string): Promise<boolean>
-
-// Queue message for sending when connected
-await connection.queueMessage(message: string, options?: QueueMessageOptions): Promise<void>
+// Direct lookup (with username)
+await rondevu.getService('chat:1.0.0@alice')
 
-// Disconnect
-connection.disconnect(): void
+// Random discovery (without username)
+await rondevu.discoverService('chat:1.0.0')
 
-// Events
-connection.events.on('message', (msg: string) => {})
-connection.events.on('state-change', (state: ConnectionStates) => {})
+// Paginated discovery
+await rondevu.discoverServices('chat:1.0.0', limit, offset)
 ```
 
-## Configuration
-
-### Polling Configuration
-
-The signaling uses configurable polling with exponential backoff:
+### Connecting to Services
 
 ```typescript
-// Default polling config
-{
-    initialInterval: 500,      // Start at 500ms
-    maxInterval: 5000,         // Max 5 seconds
-    backoffMultiplier: 1.5,    // Increase by 1.5x each time
-    maxRetries: 50,            // Max 50 attempts
-    jitter: true               // Add random 0-100ms to prevent thundering herd
-}
-```
-
-This is handled automatically - no configuration needed.
-
-### WebRTC Configuration
-
-Provide custom STUN/TURN servers:
-
-```typescript
-const host = new ServiceHost({
-    service: 'chat.app@1.0.0',
-    rondevuService: service,
-    rtcConfiguration: {
-        iceServers: [
-            { urls: 'stun:stun.l.google.com:19302' },
-            {
-                urls: 'turn:turn.example.com:3478',
-                username: 'user',
-                credential: 'pass'
-            }
-        ]
-    }
+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
 })
 ```
 
-## Username Rules
+## Documentation
 
-- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
-- **Length**: 3-32 characters
-- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
-- **Validity**: 365 days from claim/last use
-- **Ownership**: Secured by Ed25519 public key signature
+📚 **[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
 
 ## Examples
 
-### Chat Application
-
-See [demo/demo.js](./demo/demo.js) for a complete working example.
-
-### Persistent Keypair
-
-```typescript
-// Save keypair to localStorage
-const service = new RondevuService({
-    apiUrl: 'https://api.ronde.vu',
-    username: 'alice'
-})
-
-await service.initialize()
-await service.claimUsername()
-
-// Save for later
-localStorage.setItem('rondevu-keypair', JSON.stringify(service.getKeypair()))
-localStorage.setItem('rondevu-username', service.getUsername())
-
-// Load on next session
-const savedKeypair = JSON.parse(localStorage.getItem('rondevu-keypair'))
-const savedUsername = localStorage.getItem('rondevu-username')
-
-const service2 = new RondevuService({
-    apiUrl: 'https://api.ronde.vu',
-    username: savedUsername,
-    keypair: savedKeypair
-})
-
-await service2.initialize()  // Reuses keypair
-```
-
-### Message Queue Example
-
-```typescript
-// Messages are automatically queued if not connected yet
-client.events.on('connected', (connection) => {
-    // Send immediately
-    connection.sendMessage('Hello!')
-})
-
-// Or queue for later
-await client.connect()
-const conn = client.getConnection()
-await conn.queueMessage('This will be sent when connected', {
-    expiresAt: Date.now() + 60000  // Expire after 1 minute
-})
-```
-
-## Migration from v0.9.x
-
-v0.11.0+ introduces high-level wrappers, RESTful API changes, and semver-compatible discovery:
-
-**API Changes:**
-- Server endpoints restructured (`/usernames/*` → `/users/*`)
-- Added `ServiceHost` and `ServiceClient` wrappers
-- Message queue fully implemented
-- Configurable polling with exponential backoff
-- Removed deprecated `cleanup()` methods (use `dispose()`)
-- **v0.11.0+**: Services use `offers` array instead of single `sdp`
-- **v0.11.0+**: Semver-compatible service discovery (chat@1.0.0 matches 1.x.x)
-- **v0.11.0+**: All services are hidden - no listing endpoint
-- **v0.11.0+**: Services support multiple simultaneous offers for connection pooling
-
-**Migration Guide:**
-
-```typescript
-// Before (v0.9.x) - Manual WebRTC setup
-const signaler = new RondevuSignaler(service, 'chat@1.0.0')
-const context = new WebRTCContext()
-const pc = context.createPeerConnection()
-// ... 50+ lines of boilerplate
-
-// After (v0.11.0) - ServiceHost wrapper
-const host = new ServiceHost({
-    service: 'chat@1.0.0',
-    rondevuService: service
-})
-await host.start()
-// Done!
-```
-
-## Platform Support
-
-### Modern Browsers
-Works out of the box - no additional setup needed.
-
-### Node.js 18+
-Native fetch is available, but WebRTC requires polyfills:
-
-```bash
-npm install wrtc
-```
-
-```typescript
-import { WebRTCContext } from '@xtr-dev/rondevu-client'
-import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
-
-// Configure WebRTC context
-const context = new WebRTCContext({
-    RTCPeerConnection,
-    RTCSessionDescription,
-    RTCIceCandidate
-} as any)
-```
-
-## TypeScript
-
-All types are exported:
-
-```typescript
-import type {
-    RondevuServiceOptions,
-    ServiceHostOptions,
-    ServiceHostEvents,
-    ServiceClientOptions,
-    ServiceClientEvents,
-    ConnectionInterface,
-    ConnectionEvents,
-    ConnectionStates,
-    Message,
-    QueueMessageOptions,
-    Signaler,
-    PollingConfig,
-    Credentials,
-    Keypair
-} from '@xtr-dev/rondevu-client'
-```
+- [React Demo](https://github.com/xtr-dev/rondevu-demo) - Full browser UI ([live](https://ronde.vu))
 
 ## License