Update README to document current v0.4 API

- Remove outdated ServiceHost/ServiceClient/RTCDurableConnection documentation - Document actual Rondevu, RondevuSignaler, and RondevuAPI classes - Add pollOffers() combined polling documentation - Add complete usage examples for offerer and answerer sides - Document role-based ICE candidate filtering - Add migration guide from v0.3.x
2025-12-14 04:43:24 +00:00 · 2025-12-10 21:04:16 +01:00
parent 3327c5b219
commit 239563ac5c
1 changed files with 532 additions and 349 deletions
--- a/README.md
+++ b/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,15 @@ TypeScript/JavaScript client for Rondevu, providing easy-to-use WebRTC connectio
 ## Features
- **High-Level Wrappers**: ServiceHost and ServiceClient eliminate WebRTC boilerplate
+- **Username Claiming**: Secure ownership with Ed25519 signatures
- **Username-Based Discovery**: Connect to peers by username, not complex offer/answer exchange
+- **Service Publishing**: Publish services with multiple offers for connection pooling
- **Semver-Compatible Matching**: Requesting chat@1.0.0 matches any compatible 1.x.x version
+- **Service Discovery**: Direct lookup, random discovery, or paginated search
- **Privacy-First Design**: Services are hidden by default - no enumeration possible
+- **Efficient Batch Polling**: Single endpoint for answers and ICE candidates (50% fewer requests)
- **Automatic Reconnection**: Built-in retry logic with exponential backoff
+- **Semantic Version Matching**: Compatible version resolution (chat:1.0.0 matches any 1.x.x)
 - **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
 - **TypeScript**: Full type safety and autocomplete
- **Configurable Polling**: Exponential backoff with jitter to reduce server load
+- **Keypair Management**: Generate or reuse Ed25519 keypairs
-## Install
+## Installation
 ```bash
 npm install @xtr-dev/rondevu-client
@@ -34,376 +31,534 @@ 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'
+import { Rondevu } from '@xtr-dev/rondevu-client'
-// Step 1: Create and initialize service
+// 1. Initialize and claim username
-const service = new RondevuService({
+const rondevu = new Rondevu({
-    apiUrl: 'https://api.ronde.vu',
+  apiUrl: 'https://api.ronde.vu',
-    username: 'alice'
+  username: 'alice'
 })
-await service.initialize()  // Generates keypair
+await rondevu.initialize()  // Generates keypair automatically
-await service.claimUsername()  // Claims username with signature
+await rondevu.claimUsername()
-// Step 2: Create ServiceHost
+// 2. Create WebRTC offer
-const host = new ServiceHost({
+const pc = new RTCPeerConnection({
-    service: 'chat.app@1.0.0',
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
    rondevuService: service,
    maxPeers: 5,  // Accept up to 5 connections
    ttl: 300000   // 5 minutes
 })
-// Step 3: Listen for incoming connections
+const dc = pc.createDataChannel('chat')
 host.events.on('connection', (connection) => {
    console.log('✅ New connection!')
-    connection.events.on('message', (msg) => {
+const offer = await pc.createOffer()
-        console.log('📨 Received:', msg)
+await pc.setLocalDescription(offer)
        connection.sendMessage('Hello from Alice!')
    })
-    connection.events.on('state-change', (state) => {
+// 3. Publish service
-        console.log('Connection state:', state)
+const service = await rondevu.publishService({
-    })
+  serviceFqn: 'chat:1.0.0@alice',
  offers: [{ sdp: offer.sdp }],
  ttl: 300000
 })
-host.events.on('error', (error) => {
+const offerId = service.offers[0].offerId
    console.error('Host error:', error)
 })
-// Step 4: Start hosting
+// 4. Poll for answer and ICE candidates (combined)
-await host.start()
+let lastPollTimestamp = 0
-console.log('Service is now live! Others can connect to @alice')
+const pollInterval = setInterval(async () => {
  const result = await rondevu.pollOffers(lastPollTimestamp)
-// Later: stop hosting
+  // Check for answer
-host.dispose()
+  if (result.answers.length > 0) {
-```
+    const answer = result.answers.find(a => a.offerId === offerId)
    if (answer) {
      await pc.setRemoteDescription({ type: 'answer', sdp: answer.sdp })
      lastPollTimestamp = answer.answeredAt
    }
  }
-### Connecting to a Service (Bob)
+  // Process ICE candidates
  if (result.iceCandidates[offerId]) {
    const candidates = result.iceCandidates[offerId]
      .filter(c => c.role === 'answerer')  // Only answerer's candidates
-```typescript
+    for (const item of candidates) {
-import { RondevuService, ServiceClient } from '@xtr-dev/rondevu-client'
+      await pc.addIceCandidate(new RTCIceCandidate(item.candidate))
      lastPollTimestamp = Math.max(lastPollTimestamp, item.createdAt)
    }
  }
 }, 1000)
-// Step 1: Create and initialize service
+// 5. Send ICE candidates
-const service = new RondevuService({
+pc.onicecandidate = (event) => {
-    apiUrl: 'https://api.ronde.vu',
+  if (event.candidate) {
-    username: 'bob'
+    rondevu.addOfferIceCandidates(
-})
+      'chat:1.0.0@alice',
      offerId,
      [event.candidate.toJSON()]
    )
  }
 }
-await service.initialize()
+// 6. Handle messages
-await service.claimUsername()
+dc.onmessage = (event) => {
  console.log('Received:', event.data)
 }
-// Step 2: Create ServiceClient
+dc.onopen = () => {
-const client = new ServiceClient({
+  dc.send('Hello from Alice!')
    username: 'alice',  // Connect to Alice
    serviceFqn: 'chat.app@1.0.0',
    rondevuService: service,
    autoReconnect: true,
    maxReconnectAttempts: 5
 })
 // Step 3: Listen for connection events
 client.events.on('connected', (connection) => {
    console.log('✅ Connected to Alice!')
    connection.events.on('message', (msg) => {
        console.log('📨 Received:', msg)
    })
    // 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)
 })
 // Step 4: Connect
 await client.connect()
 // Later: disconnect
 client.dispose()
 ```
 ## 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
 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
 ```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
 })
 // 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
 ```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
 })
 // 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) => {})
 ```
 ### RTCDurableConnection
 ```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>
 // Disconnect
 connection.disconnect(): void
 // Events
 connection.events.on('message', (msg: string) => {})
 connection.events.on('state-change', (state: ConnectionStates) => {})
 ```
 ## Configuration
 ### Polling Configuration
 The signaling uses configurable polling with exponential backoff:
 ```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.
+### Connecting to a Service (Answerer)
 ### WebRTC Configuration
 Provide custom STUN/TURN servers:
 ```typescript
-const host = new ServiceHost({
+import { Rondevu } from '@xtr-dev/rondevu-client'
-    service: 'chat.app@1.0.0',
+
-    rondevuService: service,
+// 1. Initialize
-    rtcConfiguration: {
+const rondevu = new Rondevu({
-        iceServers: [
+  apiUrl: 'https://api.ronde.vu',
-            { urls: 'stun:stun.l.google.com:19302' },
+  username: 'bob'
-            {
+})
-                urls: 'turn:turn.example.com:3478',
+
-                username: 'user',
+await rondevu.initialize()
-                credential: 'pass'
+await rondevu.claimUsername()
-            }
+
-        ]
+// 2. Get service offer
 const serviceData = await rondevu.getService('chat:1.0.0@alice')
 // 3. Create peer connection
 const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
 })
 // 4. Set remote offer and create answer
 await pc.setRemoteDescription({ type: 'offer', sdp: serviceData.sdp })
 const answer = await pc.createAnswer()
 await pc.setLocalDescription(answer)
 // 5. Send answer
 await rondevu.postOfferAnswer(
  serviceData.serviceFqn,
  serviceData.offerId,
  answer.sdp
 )
 // 6. Send ICE candidates
 pc.onicecandidate = (event) => {
  if (event.candidate) {
    rondevu.addOfferIceCandidates(
      serviceData.serviceFqn,
      serviceData.offerId,
      [event.candidate.toJSON()]
    )
  }
 }
 // 7. Poll for ICE candidates
 let lastIceTimestamp = 0
 const iceInterval = setInterval(async () => {
  const result = await rondevu.getOfferIceCandidates(
    serviceData.serviceFqn,
    serviceData.offerId,
    lastIceTimestamp
  )
  for (const item of result.candidates) {
    if (item.candidate) {
      await pc.addIceCandidate(new RTCIceCandidate(item.candidate))
      lastIceTimestamp = item.createdAt
    }
  }
 }, 1000)
 // 8. Handle data channel
 pc.ondatachannel = (event) => {
  const dc = event.channel
  dc.onmessage = (event) => {
    console.log('Received:', event.data)
  }
  dc.onopen = () => {
    dc.send('Hello from Bob!')
  }
 }
 ```
 ## API Reference
 ### Rondevu Class
 Main class for all Rondevu operations.
 ```typescript
 import { Rondevu } from '@xtr-dev/rondevu-client'
 const rondevu = new Rondevu({
  apiUrl: string,           // Signaling server URL
  username: string,         // Your username
  keypair?: Keypair,        // Optional: reuse existing keypair
  credentials?: Credentials // Optional: reuse existing credentials
 })
 ```
-## Username Rules
+#### Initialization
- **Format**: Lowercase alphanumeric + dash (`a-z`, `0-9`, `-`)
+```typescript
- **Length**: 3-32 characters
+// Initialize (generates keypair and credentials if not provided)
- **Pattern**: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
+await rondevu.initialize(): Promise<void>
- **Validity**: 365 days from claim/last use
+```
 - **Ownership**: Secured by Ed25519 public key signature
-## Examples
+#### Username Management
-### Chat Application
+```typescript
 // Claim username with Ed25519 signature
 await rondevu.claimUsername(): Promise<void>
-See [demo/demo.js](./demo/demo.js) for a complete working example.
+// Check if username is claimed (checks server)
 await rondevu.isUsernameClaimed(): Promise<boolean>
 // Get username
 rondevu.getUsername(): string
 // Get public key
 rondevu.getPublicKey(): string | null
 // Get keypair (for backup/storage)
 rondevu.getKeypair(): Keypair | null
 ```
 #### Service Publishing
 ```typescript
 // Publish service with offers
 await rondevu.publishService({
  serviceFqn: string,  // e.g., 'chat:1.0.0@alice'
  offers: Array<{ sdp: string }>,
  ttl?: number         // Optional: milliseconds (default: 300000)
 }): Promise<Service>
 ```
 #### Service Discovery
 ```typescript
 // Direct lookup by FQN (with username)
 await rondevu.getService('chat:1.0.0@alice'): Promise<ServiceOffer>
 // Random discovery (without username)
 await rondevu.discoverService('chat:1.0.0'): Promise<ServiceOffer>
 // Paginated discovery (returns multiple offers)
 await rondevu.discoverServices(
  'chat:1.0.0',  // serviceVersion
  10,            // limit
  0              // offset
 ): Promise<{ services: ServiceOffer[], count: number, limit: number, offset: number }>
 ```
 #### WebRTC Signaling
 ```typescript
 // Post answer SDP
 await rondevu.postOfferAnswer(
  serviceFqn: string,
  offerId: string,
  sdp: string
 ): Promise<{ success: boolean, offerId: string }>
 // Get answer SDP (offerer polls this - deprecated, use pollOffers instead)
 await rondevu.getOfferAnswer(
  serviceFqn: string,
  offerId: string
 ): Promise<{ sdp: string, offerId: string, answererId: string, answeredAt: number } | null>
 // Combined polling for answers and ICE candidates (RECOMMENDED for offerers)
 await rondevu.pollOffers(since?: number): Promise<{
  answers: Array<{
    offerId: string
    serviceId?: string
    answererId: string
    sdp: string
    answeredAt: number
  }>
  iceCandidates: Record<string, Array<{
    candidate: any
    role: 'offerer' | 'answerer'
    peerId: string
    createdAt: number
  }>>
 }>
 // Add ICE candidates
 await rondevu.addOfferIceCandidates(
  serviceFqn: string,
  offerId: string,
  candidates: RTCIceCandidateInit[]
 ): Promise<{ count: number, offerId: string }>
 // Get ICE candidates (with polling support)
 await rondevu.getOfferIceCandidates(
  serviceFqn: string,
  offerId: string,
  since: number = 0
 ): Promise<{ candidates: IceCandidate[], offerId: string }>
 ```
 ### RondevuSignaler Class
 Higher-level signaling abstraction with automatic polling and event listeners.
 ```typescript
 import { RondevuSignaler } from '@xtr-dev/rondevu-client'
 const signaler = new RondevuSignaler(
  rondevu: Rondevu,
  service: string,      // Service FQN without username (e.g., 'chat:1.0.0')
  host?: string,        // Optional: target username for answerer
  pollingConfig?: {
    initialInterval?: number      // Default: 500ms
    maxInterval?: number           // Default: 5000ms
    backoffMultiplier?: number     // Default: 1.5
    maxRetries?: number            // Default: 50
    jitter?: boolean               // Default: true
  }
 )
 ```
 #### Offerer Side
 ```typescript
 // Set offer (automatically starts polling for answer and ICE)
 await signaler.setOffer(offer: RTCSessionDescriptionInit): Promise<void>
 // Listen for answer
 const unbind = signaler.addAnswerListener((answer) => {
  console.log('Received answer:', answer)
 })
 // Listen for ICE candidates
 signaler.addListener((candidate) => {
  console.log('Received ICE candidate:', candidate)
 })
 // Send ICE candidate
 await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise<void>
 ```
 #### Answerer Side
 ```typescript
 // Listen for offer (automatically searches for service)
 const unbind = signaler.addOfferListener((offer) => {
  console.log('Received offer:', offer)
 })
 // Set answer (automatically starts polling for ICE)
 await signaler.setAnswer(answer: RTCSessionDescriptionInit): Promise<void>
 // Send ICE candidate
 await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise<void>
 // Listen for ICE candidates
 signaler.addListener((candidate) => {
  console.log('Received ICE candidate:', candidate)
 })
 ```
 #### Cleanup
 ```typescript
 // Stop all polling and cleanup
 signaler.dispose(): void
 ```
 ### RondevuAPI Class
 Low-level HTTP API client (used internally by Rondevu class).
 ```typescript
 import { RondevuAPI } from '@xtr-dev/rondevu-client'
 const api = new RondevuAPI(
  baseUrl: string,
  credentials?: Credentials
 )
 // Set credentials
 api.setCredentials(credentials: Credentials): void
 // Register peer
 await api.register(): Promise<Credentials>
 // Check username
 await api.checkUsername(username: string): Promise<{
  available: boolean
  publicKey?: string
  claimedAt?: number
  expiresAt?: number
 }>
 // Claim username
 await api.claimUsername(
  username: string,
  publicKey: string,
  signature: string,
  message: string
 ): Promise<{ success: boolean, username: string }>
 // ... (all other HTTP endpoints)
 ```
 #### Cryptographic Helpers
 ```typescript
 // Generate Ed25519 keypair
 const keypair = await RondevuAPI.generateKeypair(): Promise<Keypair>
 // Sign message
 const signature = await RondevuAPI.signMessage(
  message: string,
  privateKey: string
 ): Promise<string>
 // Verify signature
 const valid = await RondevuAPI.verifySignature(
  message: string,
  signature: string,
  publicKey: string
 ): Promise<boolean>
 ```
 ## Types
 ```typescript
 interface Keypair {
  publicKey: string   // Base64-encoded Ed25519 public key
  privateKey: string  // Base64-encoded Ed25519 private key
 }
 interface Credentials {
  peerId: string
  secret: string
 }
 interface Service {
  serviceId: string
  offers: ServiceOffer[]
  username: string
  serviceFqn: string
  createdAt: number
  expiresAt: number
 }
 interface ServiceOffer {
  offerId: string
  sdp: string
  createdAt: number
  expiresAt: number
 }
 interface IceCandidate {
  candidate: RTCIceCandidateInit
  createdAt: number
 }
 interface PollingConfig {
  initialInterval?: number     // Default: 500ms
  maxInterval?: number          // Default: 5000ms
  backoffMultiplier?: number    // Default: 1.5
  maxRetries?: number           // Default: 50
  jitter?: boolean              // Default: true
 }
 ```
 ## Advanced Usage
 ### Persistent Keypair
 ```typescript
 // Save keypair to localStorage
-const service = new RondevuService({
+const rondevu = new Rondevu({
-    apiUrl: 'https://api.ronde.vu',
+  apiUrl: 'https://api.ronde.vu',
-    username: 'alice'
+  username: 'alice'
 })
-await service.initialize()
+await rondevu.initialize()
-await service.claimUsername()
+await rondevu.claimUsername()
 // Save for later
-localStorage.setItem('rondevu-keypair', JSON.stringify(service.getKeypair()))
+localStorage.setItem('rondevu-keypair', JSON.stringify(rondevu.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({
+const rondevu2 = new Rondevu({
-    apiUrl: 'https://api.ronde.vu',
+  apiUrl: 'https://api.ronde.vu',
-    username: savedUsername,
+  username: 'alice',
-    keypair: savedKeypair
+  keypair: savedKeypair
 })
-await service2.initialize()  // Reuses keypair
+await rondevu2.initialize()  // Reuses keypair
 ```
-### Message Queue Example
+### Service Discovery
 ```typescript
-// Messages are automatically queued if not connected yet
+// Get a random available service
-client.events.on('connected', (connection) => {
+const service = await rondevu.discoverService('chat:1.0.0')
-    // Send immediately
+console.log('Discovered:', service.username)
    connection.sendMessage('Hello!')
 })
-// Or queue for later
+// Get multiple services (paginated)
-await client.connect()
+const result = await rondevu.discoverServices('chat:1.0.0', 10, 0)
-const conn = client.getConnection()
+console.log(`Found ${result.count} services:`)
-await conn.queueMessage('This will be sent when connected', {
+result.services.forEach(s => console.log(`  - ${s.username}`))
    expiresAt: Date.now() + 60000  // Expire after 1 minute
 })
 ```
-## Migration from v0.9.x
+### Multiple Concurrent Offers
 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
+// Publish service with multiple offers for connection pooling
-const signaler = new RondevuSignaler(service, 'chat@1.0.0')
+const offers = []
-const context = new WebRTCContext()
+const connections = []
 const pc = context.createPeerConnection()
 // ... 50+ lines of boilerplate
-// After (v0.11.0) - ServiceHost wrapper
+for (let i = 0; i < 5; i++) {
-const host = new ServiceHost({
+  const pc = new RTCPeerConnection(rtcConfig)
-    service: 'chat@1.0.0',
+  const dc = pc.createDataChannel('chat')
-    rondevuService: service
+  const offer = await pc.createOffer()
  await pc.setLocalDescription(offer)
  offers.push({ sdp: offer.sdp })
  connections.push({ pc, dc })
 }
 const service = await rondevu.publishService({
  serviceFqn: 'chat:1.0.0@alice',
  offers,
  ttl: 300000
 })
-await host.start()
+
-// Done!
+// Each offer can be answered independently
 console.log(`Published ${service.offers.length} offers`)
 ```
 ### Custom Polling Configuration
 ```typescript
 const signaler = new RondevuSignaler(
  rondevu,
  'chat:1.0.0',
  'alice',
  {
    initialInterval: 1000,    // Start at 1 second
    maxInterval: 10000,       // Max 10 seconds
    backoffMultiplier: 2,     // Double each time
    maxRetries: 30,           // Stop after 30 retries
    jitter: true              // Add randomness
  }
 )
 ```
 ## Platform Support
@@ -419,38 +574,66 @@ npm install wrtc
 ```
 ```typescript
 import { WebRTCContext } from '@xtr-dev/rondevu-client'
 import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc'
-// Configure WebRTC context
+// Use wrtc implementations
-const context = new WebRTCContext({
+const pc = new RTCPeerConnection()
    RTCPeerConnection,
    RTCSessionDescription,
    RTCIceCandidate
 } as any)
 ```
-## TypeScript
+## Username Rules
-All types are exported:
+- **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
 ## Service FQN Format
 - **Format**: `service:version@username`
 - **Service**: Lowercase alphanumeric + dash (e.g., `chat`, `video-call`)
 - **Version**: Semantic versioning (e.g., `1.0.0`, `2.1.3`)
 - **Username**: Claimed username
 - **Example**: `chat:1.0.0@alice`
 ## Examples
 See the [demo](https://github.com/xtr-dev/rondevu-demo) for a complete working example with React UI.
 ## Migration from v0.3.x
 v0.4.0 removes high-level abstractions and uses manual WebRTC setup:
 **Removed:**
 - `ServiceHost` class (use manual WebRTC + `publishService()`)
 - `ServiceClient` class (use manual WebRTC + `getService()`)
 - `RTCDurableConnection` class (use native WebRTC APIs)
 - `RondevuService` class (merged into `Rondevu`)
 **Added:**
 - `pollOffers()` - Combined polling for answers and ICE candidates
 - `RondevuSignaler` - Simplified signaling with automatic polling
 **Migration Example:**
 ```typescript
-import type {
+// Before (v0.3.x) - ServiceHost
-    RondevuServiceOptions,
+const host = new ServiceHost({
-    ServiceHostOptions,
+  service: 'chat@1.0.0',
-    ServiceHostEvents,
+  rondevuService: service
-    ServiceClientOptions,
+})
-    ServiceClientEvents,
+await host.start()
-    ConnectionInterface,
+
-    ConnectionEvents,
+// After (v0.4.0) - Manual setup
-    ConnectionStates,
+const pc = new RTCPeerConnection()
-    Message,
+const dc = pc.createDataChannel('chat')
-    QueueMessageOptions,
+const offer = await pc.createOffer()
-    Signaler,
+await pc.setLocalDescription(offer)
-    PollingConfig,
+
-    Credentials,
+await rondevu.publishService({
-    Keypair
+  serviceFqn: 'chat:1.0.0@alice',
-} from '@xtr-dev/rondevu-client'
+  offers: [{ sdp: offer.sdp }]
 })
 ```
 ## License