@xtr-dev/rondevu-client 0.8.2 → 0.9.1

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)
 
-🌐 **DNS-like WebRTC client with username claiming and service discovery**
+🌐 **WebRTC with durable connections and automatic reconnection**
 
-TypeScript/JavaScript client for Rondevu, providing cryptographic username claiming, service publishing, and privacy-preserving discovery.
+TypeScript/JavaScript client for Rondevu, providing durable WebRTC connections that survive network interruptions with automatic reconnection and message queuing.
 
 **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,13 +15,14 @@ TypeScript/JavaScript client for Rondevu, providing cryptographic username claim
 
 ## Features
 
+- **Durable Connections**: Automatic reconnection on network drops
+- **Message Queuing**: Messages sent during disconnections are queued and flushed on reconnect
+- **Durable Channels**: RTCDataChannel wrappers that survive connection drops
+- **TTL Auto-Refresh**: Services automatically republish before expiration
 - **Username Claiming**: Cryptographic ownership with Ed25519 signatures
 - **Service Publishing**: Package-style naming (com.example.chat@1.0.0)
-- **Privacy-Preserving Discovery**: UUID-based service index
-- **Public/Private Services**: Control service visibility
-- **Complete WebRTC Signaling**: Full offer/answer and ICE candidate exchange
-- **Trickle ICE**: Send ICE candidates as they're discovered
 - **TypeScript**: Full type safety and autocomplete
+- **Configurable**: All timeouts, retry limits, and queue sizes are configurable
 
 ## Install
 
@@ -44,36 +45,36 @@ await client.register();
 const claim = await client.usernames.claimUsername('alice');
 client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
 
-console.log(`Username claimed: ${claim.username}`);
-console.log(`Expires: ${new Date(claim.expiresAt)}`);
-
 // Step 2: Expose service with handler
 const keypair = client.usernames.loadKeypairFromStorage('alice');
 
-const handle = await client.services.exposeService({
+const service = await client.exposeService({
   username: 'alice',
   privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.chat@1.0.0',
+  serviceFqn: 'chat@1.0.0',
   isPublic: true,
-  handler: (channel, peer) => {
-    console.log('📡 New connection established');
+  poolSize: 10,  // Handle 10 concurrent connections
+  handler: (channel, connectionId) => {
+    console.log(`📡 New connection: ${connectionId}`);
 
-    channel.onmessage = (e) => {
-      console.log('📥 Received:', e.data);
-      channel.send(`Echo: ${e.data}`);
-    };
+    channel.on('message', (data) => {
+      console.log('📥 Received:', data);
+      channel.send(`Echo: ${data}`);
+    });
 
-    channel.onopen = () => {
-      console.log('✅ Data channel open');
-    };
+    channel.on('close', () => {
+      console.log(`👋 Connection ${connectionId} closed`);
+    });
   }
 });
 
-console.log(`Service published with UUID: ${handle.uuid}`);
+// Start the service
+const info = await service.start();
+console.log(`Service published with UUID: ${info.uuid}`);
 console.log('Waiting for connections...');
 
-// Later: unpublish
-await handle.unpublish();
+// Later: stop the service
+await service.stop();
 ```
 
 ### Connecting to a Service (Bob)
@@ -85,46 +86,75 @@ import { Rondevu } from '@xtr-dev/rondevu-client';
 const client = new Rondevu({ baseUrl: 'https://api.ronde.vu' });
 await client.register();
 
-// Option 1: Connect by username + FQN
-const { peer, channel } = await client.discovery.connect(
-  'alice',
-  'com.example.chat@1.0.0'
-);
+// Connect to Alice's service
+const connection = await client.connect('alice', 'chat@1.0.0', {
+  maxReconnectAttempts: 5
+});
+
+// Create a durable channel
+const channel = connection.createChannel('main');
 
-channel.onmessage = (e) => {
-  console.log('📥 Received:', e.data);
-};
+channel.on('message', (data) => {
+  console.log('📥 Received:', data);
+});
 
-channel.onopen = () => {
-  console.log('✅ Connected!');
+channel.on('open', () => {
+  console.log('✅ Channel open');
   channel.send('Hello Alice!');
-};
+});
 
-peer.on('connected', () => {
-  console.log('🎉 WebRTC connection established');
+// Listen for connection events
+connection.on('connected', () => {
+  console.log('🎉 Connected to Alice');
 });
 
-peer.on('failed', (error) => {
-  console.error('❌ Connection failed:', error);
+connection.on('reconnecting', (attempt, max, delay) => {
+  console.log(`🔄 Reconnecting... (${attempt}/${max}, retry in ${delay}ms)`);
 });
 
-// Option 2: List services first, then connect
-const services = await client.discovery.listServices('alice');
-console.log(`Found ${services.services.length} services`);
+connection.on('disconnected', () => {
+  console.log('🔌 Disconnected');
+});
 
-for (const service of services.services) {
-  console.log(`- UUID: ${service.uuid}`);
-  if (service.isPublic) {
-    console.log(`  FQN: ${service.serviceFqn}`);
-  }
-}
+connection.on('failed', (error) => {
+  console.error('❌ Connection failed permanently:', error);
+});
 
-// Connect by UUID
-const { peer: peer2, channel: channel2 } = await client.discovery.connectByUuid(
-  services.services[0].uuid
-);
+// Establish the connection
+await connection.connect();
+
+// Messages sent during disconnection are automatically queued
+channel.send('This will be queued if disconnected');
+
+// Later: close the connection
+await connection.close();
 ```
 
+## Core Concepts
+
+### DurableConnection
+
+Manages WebRTC peer lifecycle with automatic reconnection:
+- Automatically reconnects when connection drops
+- Exponential backoff with jitter (1s → 2s → 4s → 8s → ... max 30s)
+- Configurable max retry attempts (default: 10)
+- Manages multiple DurableChannel instances
+
+### DurableChannel
+
+Wraps RTCDataChannel with message queuing:
+- Queues messages during disconnection
+- Flushes queue on reconnection
+- Configurable queue size and message age limits
+- RTCDataChannel-compatible API with event emitters
+
+### DurableService
+
+Server-side service with TTL auto-refresh:
+- Automatically republishes service before TTL expires
+- Creates DurableConnection for each incoming peer
+- Manages connection pool for multiple simultaneous connections
+
 ## API Reference
 
 ### Main Client
@@ -161,39 +191,12 @@ const check = await client.usernames.checkUsername('alice');
 const claim = await client.usernames.claimUsername('alice');
 // { username, publicKey, privateKey, claimedAt, expiresAt }
 
-// Claim with existing keypair
-const keypair = await client.usernames.generateKeypair();
-const claim2 = await client.usernames.claimUsername('bob', keypair);
-
 // Save keypair to localStorage
-client.usernames.saveKeypairToStorage('alice', publicKey, privateKey);
+client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
 
 // Load keypair from localStorage
-const stored = client.usernames.loadKeypairFromStorage('alice');
+const keypair = client.usernames.loadKeypairFromStorage('alice');
 // { publicKey, privateKey } | null
-
-// Export keypair for backup
-const exported = client.usernames.exportKeypair('alice');
-// { username, publicKey, privateKey }
-
-// Import keypair from backup
-client.usernames.importKeypair({ username: 'alice', publicKey, privateKey });
-
-// Low-level: Generate keypair
-const { publicKey, privateKey } = await client.usernames.generateKeypair();
-
-// Low-level: Sign message
-const signature = await client.usernames.signMessage(
-  'claim:alice:1234567890',
-  privateKey
-);
-
-// Low-level: Verify signature
-const valid = await client.usernames.verifySignature(
-  'claim:alice:1234567890',
-  signature,
-  publicKey
-);
 ```
 
 **Username Rules:**
@@ -203,446 +206,413 @@ const valid = await client.usernames.verifySignature(
 - Validity: 365 days from claim/last use
 - Ownership: Secured by Ed25519 public key
 
-### Services API
+### Durable Service API
 
 ```typescript
-// Publish service (returns UUID)
-const service = await client.services.publishService({
+// Expose a durable service
+const service = await client.exposeService({
   username: 'alice',
   privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.chat@1.0.0',
-  isPublic: false,              // optional, default false
-  metadata: { description: '...' },  // optional
-  ttl: 5 * 60 * 1000,           // optional, default 5 minutes
-  rtcConfig: { ... }            // optional RTCConfiguration
-});
-// { serviceId, uuid, offerId, expiresAt }
-
-console.log(`Service UUID: ${service.uuid}`);
-console.log('Share this UUID to allow connections');
+  serviceFqn: 'chat@1.0.0',
+
+  // Service options
+  isPublic: true,               // optional, default: false
+  metadata: { version: '1.0' }, // optional
+  ttl: 300000,                  // optional, default: 5 minutes
+  ttlRefreshMargin: 0.2,        // optional, refresh at 80% of TTL
+
+  // Connection pooling
+  poolSize: 10,                 // optional, default: 1
+  pollingInterval: 2000,        // optional, default: 2000ms
+
+  // Connection options (applied to incoming connections)
+  maxReconnectAttempts: 10,     // optional, default: 10
+  reconnectBackoffBase: 1000,   // optional, default: 1000ms
+  reconnectBackoffMax: 30000,   // optional, default: 30000ms
+  reconnectJitter: 0.2,         // optional, default: 0.2 (±20%)
+  connectionTimeout: 30000,     // optional, default: 30000ms
+
+  // Message queuing
+  maxQueueSize: 1000,           // optional, default: 1000
+  maxMessageAge: 60000,         // optional, default: 60000ms (1 minute)
+
+  // WebRTC configuration
+  rtcConfig: {
+    iceServers: [
+      { urls: 'stun:stun.l.google.com:19302' }
+    ]
+  },
 
-// Expose service with automatic connection handling
-const handle = await client.services.exposeService({
-  username: 'alice',
-  privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.echo@1.0.0',
-  isPublic: true,
-  handler: (channel, peer) => {
-    channel.onmessage = (e) => {
-      console.log('Received:', e.data);
-      channel.send(`Echo: ${e.data}`);
-    };
+  // Connection handler
+  handler: (channel, connectionId) => {
+    // Handle incoming connection
+    channel.on('message', (data) => {
+      console.log('Received:', data);
+      channel.send(`Echo: ${data}`);
+    });
   }
 });
 
-// Later: unpublish
-await handle.unpublish();
+// Start the service
+const info = await service.start();
+// { serviceId: '...', uuid: '...', expiresAt: 1234567890 }
 
-// Unpublish service manually
-await client.services.unpublishService(serviceId, username);
-```
+// Get active connections
+const connections = service.getActiveConnections();
+// ['conn-123', 'conn-456']
 
-#### Multi-Connection Service Hosting (Offer Pooling)
+// Get service info
+const serviceInfo = service.getServiceInfo();
+// { serviceId: '...', uuid: '...', expiresAt: 1234567890 } | null
 
-By default, `exposeService()` creates a single offer and can only accept one connection. To handle multiple concurrent connections, use the `poolSize` option to enable **offer pooling**:
+// Stop the service
+await service.stop();
+```
 
+**Service Events:**
 ```typescript
-// Expose service with offer pooling for multiple concurrent connections
-const handle = await client.services.exposeService({
-  username: 'alice',
-  privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.chat@1.0.0',
-  isPublic: true,
-  poolSize: 5,  // Maintain 5 simultaneous open offers
-  pollingInterval: 2000,  // Optional: polling interval in ms (default: 2000)
-  handler: (channel, peer, connectionId) => {
-    console.log(`📡 New connection: ${connectionId}`);
+service.on('published', (serviceId, uuid) => {
+  console.log(`Service published: ${uuid}`);
+});
 
-    channel.onmessage = (e) => {
-      console.log(`📥 [${connectionId}] Received:`, e.data);
-      channel.send(`Echo: ${e.data}`);
-    };
+service.on('connection', (connectionId) => {
+  console.log(`New connection: ${connectionId}`);
+});
 
-    channel.onclose = () => {
-      console.log(`👋 [${connectionId}] Connection closed`);
-    };
-  },
-  onPoolStatus: (status) => {
-    console.log('Pool status:', {
-      activeOffers: status.activeOffers,
-      activeConnections: status.activeConnections,
-      totalHandled: status.totalConnectionsHandled
-    });
-  },
-  onError: (error, context) => {
-    console.error(`Pool error (${context}):`, error);
-  }
+service.on('disconnection', (connectionId) => {
+  console.log(`Connection closed: ${connectionId}`);
 });
 
-// Get current pool status
-const status = handle.getStatus();
-console.log(`Active offers: ${status.activeOffers}`);
-console.log(`Active connections: ${status.activeConnections}`);
+service.on('ttl-refreshed', (expiresAt) => {
+  console.log(`TTL refreshed, expires at: ${new Date(expiresAt)}`);
+});
 
-// Manually add more offers if needed
-await handle.addOffers(3);
-```
+service.on('error', (error, context) => {
+  console.error(`Service error (${context}):`, error);
+});
 
-**How Offer Pooling Works:**
-1. The pool maintains `poolSize` simultaneous open offers at all times
-2. When an offer is answered (connection established), a new offer is automatically created
-3. Polling checks for answers every `pollingInterval` milliseconds (default: 2000ms)
-4. Each connection gets a unique `connectionId` passed to the handler
-5. No limit on total concurrent connections - only pool size (open offers) is controlled
-
-**Use Cases:**
-- Chat servers handling multiple clients
-- File sharing services with concurrent downloads
-- Multiplayer game lobbies
-- Collaborative editing sessions
-- Any service that needs to accept multiple simultaneous connections
-
-**Pool Status Interface:**
-```typescript
-interface PoolStatus {
-  activeOffers: number;          // Current number of open offers
-  activeConnections: number;     // Current number of connected peers
-  totalConnectionsHandled: number;  // Total connections since start
-  failedOfferCreations: number;  // Failed offer creation attempts
-}
+service.on('closed', () => {
+  console.log('Service stopped');
+});
 ```
 
-**Pooled Service Handle:**
+### Durable Connection API
+
 ```typescript
-interface PooledServiceHandle extends ServiceHandle {
-  getStatus: () => PoolStatus;        // Get current pool status
-  addOffers: (count: number) => Promise<void>;  // Manually add offers
-}
-```
+// Connect by username and service FQN
+const connection = await client.connect('alice', 'chat@1.0.0', {
+  // Connection options
+  maxReconnectAttempts: 10,     // optional, default: 10
+  reconnectBackoffBase: 1000,   // optional, default: 1000ms
+  reconnectBackoffMax: 30000,   // optional, default: 30000ms
+  reconnectJitter: 0.2,         // optional, default: 0.2 (±20%)
+  connectionTimeout: 30000,     // optional, default: 30000ms
+
+  // Message queuing
+  maxQueueSize: 1000,           // optional, default: 1000
+  maxMessageAge: 60000,         // optional, default: 60000ms
+
+  // WebRTC configuration
+  rtcConfig: {
+    iceServers: [
+      { urls: 'stun:stun.l.google.com:19302' }
+    ]
+  }
+});
 
-**Service FQN Format:**
-- Service name: Reverse domain notation (e.g., `com.example.chat`)
-- Version: Semantic versioning (e.g., `1.0.0`, `2.1.3-beta`)
-- Complete FQN: `service-name@version`
-- Examples: `com.example.chat@1.0.0`, `io.github.alice.notes@0.1.0-beta`
+// Connect by UUID
+const connection2 = await client.connectByUuid('service-uuid-here', {
+  maxReconnectAttempts: 5
+});
 
-**Validation Rules:**
-- Service name pattern: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$`
-- Length: 3-128 characters
-- Minimum 2 components (at least one dot)
-- Version pattern: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$`
+// Create channels before connecting
+const channel = connection.createChannel('main');
+const fileChannel = connection.createChannel('files', {
+  ordered: false,
+  maxRetransmits: 3
+});
 
-### Discovery API
+// Get existing channel
+const existingChannel = connection.getChannel('main');
 
-```typescript
-// List all services for a username
-const services = await client.discovery.listServices('alice');
-// {
-//   username: 'alice',
-//   services: [
-//     { uuid: 'abc123', isPublic: false },
-//     { uuid: 'def456', isPublic: true, serviceFqn: '...', metadata: {...} }
-//   ]
-// }
-
-// Query service by FQN
-const query = await client.discovery.queryService('alice', 'com.example.chat@1.0.0');
-// { uuid: 'abc123', allowed: true }
-
-// Get service details by UUID
-const details = await client.discovery.getServiceDetails('abc123');
-// { serviceId, username, serviceFqn, offerId, sdp, isPublic, metadata, ... }
-
-// Connect to service by UUID
-const peer = await client.discovery.connectToService('abc123', {
-  rtcConfig: { ... },           // optional
-  onConnected: () => { ... },   // optional
-  onData: (data) => { ... }     // optional
-});
-
-// Connect by username + FQN (convenience method)
-const { peer, channel } = await client.discovery.connect(
-  'alice',
-  'com.example.chat@1.0.0',
-  { rtcConfig: { ... } }  // optional
-);
-
-// Connect by UUID with channel
-const { peer, channel } = await client.discovery.connectByUuid('abc123');
-```
+// Check connection state
+const state = connection.getState();
+// 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'failed' | 'closed'
 
-### Low-Level Peer Connection
+const isConnected = connection.isConnected();
 
-```typescript
-// Create peer connection
-const peer = client.createPeer({
-  iceServers: [
-    { urls: 'stun:stun.l.google.com:19302' },
-    {
-      urls: 'turn:turn.example.com:3478',
-      username: 'user',
-      credential: 'pass'
-    }
-  ],
-  iceTransportPolicy: 'relay'  // optional: force TURN relay
-});
+// Connect
+await connection.connect();
 
-// Event listeners
-peer.on('state', (state) => {
-  console.log('Peer state:', state);
-});
+// Close connection
+await connection.close();
+```
 
-peer.on('connected', () => {
-  console.log('✅ Connected');
+**Connection Events:**
+```typescript
+connection.on('state', (newState, previousState) => {
+  console.log(`State: ${previousState} → ${newState}`);
 });
 
-peer.on('disconnected', () => {
-  console.log('🔌 Disconnected');
+connection.on('connected', () => {
+  console.log('Connected');
 });
 
-peer.on('failed', (error) => {
-  console.error('❌ Failed:', error);
+connection.on('reconnecting', (attempt, maxAttempts, delay) => {
+  console.log(`Reconnecting (${attempt}/${maxAttempts}) in ${delay}ms`);
 });
 
-peer.on('datachannel', (channel) => {
-  console.log('📡 Data channel ready');
+connection.on('disconnected', () => {
+  console.log('Disconnected');
 });
 
-peer.on('track', (event) => {
-  // Media track received
-  const stream = event.streams[0];
-  videoElement.srcObject = stream;
+connection.on('failed', (error, permanent) => {
+  console.error('Connection failed:', error, 'Permanent:', permanent);
 });
 
-// Create offer
-const offerId = await peer.createOffer({
-  ttl: 300000,  // optional
-  timeouts: {   // optional
-    iceGathering: 10000,
-    waitingForAnswer: 30000,
-    creatingAnswer: 10000,
-    iceConnection: 30000
-  }
+connection.on('closed', () => {
+  console.log('Connection closed');
 });
+```
 
-// Answer offer
-await peer.answer(offerId, sdp);
+### Durable Channel API
 
-// Add media tracks
-const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
-stream.getTracks().forEach(track => {
-  peer.addTrack(track, stream);
+```typescript
+const channel = connection.createChannel('chat', {
+  ordered: true,          // optional, default: true
+  maxRetransmits: undefined  // optional, for unordered channels
 });
 
-// Close connection
-await peer.close();
+// Send data (queued if disconnected)
+channel.send('Hello!');
+channel.send(new ArrayBuffer(1024));
+channel.send(new Blob(['data']));
 
-// Properties
-peer.stateName;        // 'idle', 'creating-offer', 'connected', etc.
-peer.connectionState;  // RTCPeerConnectionState
-peer.offerId;          // string | undefined
-peer.role;             // 'offerer' | 'answerer' | undefined
-```
+// Check state
+const state = channel.readyState;
+// 'connecting' | 'open' | 'closing' | 'closed'
 
-## Connection Lifecycle
-
-### Service Publisher (Offerer)
-1. **idle** - Initial state
-2. **creating-offer** - Creating WebRTC offer
-3. **waiting-for-answer** - Polling for answer from peer
-4. **exchanging-ice** - Exchanging ICE candidates
-5. **connected** - Successfully connected
-6. **failed** - Connection failed
-7. **closed** - Connection closed
-
-### Service Consumer (Answerer)
-1. **idle** - Initial state
-2. **answering** - Creating WebRTC answer
-3. **exchanging-ice** - Exchanging ICE candidates
-4. **connected** - Successfully connected
-5. **failed** - Connection failed
-6. **closed** - Connection closed
+// Get buffered amount
+const buffered = channel.bufferedAmount;
 
-## Platform-Specific Setup
+// Set buffered amount low threshold
+channel.bufferedAmountLowThreshold = 16 * 1024; // 16KB
 
-### Modern Browsers
-Works out of the box - no additional setup needed.
-
-### Node.js 18+
-Native fetch is available, but you need WebRTC polyfills:
+// Get queue size (for debugging)
+const queueSize = channel.getQueueSize();
 
-```bash
-npm install wrtc
+// Close channel
+channel.close();
 ```
 
+**Channel Events:**
 ```typescript
-import { Rondevu } from '@xtr-dev/rondevu-client';
-import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
-
-const client = new Rondevu({
-  baseUrl: 'https://api.ronde.vu',
-  RTCPeerConnection,
-  RTCSessionDescription,
-  RTCIceCandidate
+channel.on('open', () => {
+  console.log('Channel open');
 });
-```
-
-### Node.js < 18
-Install both fetch and WebRTC polyfills:
 
-```bash
-npm install node-fetch wrtc
-```
+channel.on('message', (data) => {
+  console.log('Received:', data);
+});
 
-```typescript
-import { Rondevu } from '@xtr-dev/rondevu-client';
-import fetch from 'node-fetch';
-import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
+channel.on('error', (error) => {
+  console.error('Channel error:', error);
+});
 
-const client = new Rondevu({
-  baseUrl: 'https://api.ronde.vu',
-  fetch: fetch as any,
-  RTCPeerConnection,
-  RTCSessionDescription,
-  RTCIceCandidate
+channel.on('close', () => {
+  console.log('Channel closed');
 });
-```
 
-### Deno
-```typescript
-import { Rondevu } from 'npm:@xtr-dev/rondevu-client';
+channel.on('bufferedAmountLow', () => {
+  console.log('Buffer drained, safe to send more');
+});
 
-const client = new Rondevu({
-  baseUrl: 'https://api.ronde.vu'
+channel.on('queueOverflow', (droppedCount) => {
+  console.warn(`Queue overflow: ${droppedCount} messages dropped`);
 });
 ```
 
-### Bun
-Works out of the box - no additional setup needed.
+## Configuration Options
+
+### Connection Configuration
 
-### Cloudflare Workers
 ```typescript
-import { Rondevu } from '@xtr-dev/rondevu-client';
+interface DurableConnectionConfig {
+  maxReconnectAttempts?: number;      // default: 10
+  reconnectBackoffBase?: number;      // default: 1000 (1 second)
+  reconnectBackoffMax?: number;       // default: 30000 (30 seconds)
+  reconnectJitter?: number;           // default: 0.2 (±20%)
+  connectionTimeout?: number;         // default: 30000 (30 seconds)
+  maxQueueSize?: number;              // default: 1000 messages
+  maxMessageAge?: number;             // default: 60000 (1 minute)
+  rtcConfig?: RTCConfiguration;
+}
+```
 
-export default {
-  async fetch(request: Request, env: Env) {
-    const client = new Rondevu({
-      baseUrl: 'https://api.ronde.vu'
-    });
+### Service Configuration
 
-    const creds = await client.register();
-    return new Response(JSON.stringify(creds));
-  }
-};
+```typescript
+interface DurableServiceConfig extends DurableConnectionConfig {
+  username: string;
+  privateKey: string;
+  serviceFqn: string;
+  isPublic?: boolean;                 // default: false
+  metadata?: Record<string, any>;
+  ttl?: number;                       // default: 300000 (5 minutes)
+  ttlRefreshMargin?: number;          // default: 0.2 (refresh at 80%)
+  poolSize?: number;                  // default: 1
+  pollingInterval?: number;           // default: 2000 (2 seconds)
+}
 ```
 
 ## Examples
 
-### Echo Service
+### Chat Application
 
 ```typescript
-// Publisher
-const client1 = new Rondevu();
-await client1.register();
-
-const claim = await client1.usernames.claimUsername('alice');
-client1.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
+// Server
+const client = new Rondevu();
+await client.register();
 
-const keypair = client1.usernames.loadKeypairFromStorage('alice');
+const claim = await client.usernames.claimUsername('alice');
+client.usernames.saveKeypairToStorage('alice', claim.publicKey, claim.privateKey);
+const keypair = client.usernames.loadKeypairFromStorage('alice');
 
-await client1.services.exposeService({
+const service = await client.exposeService({
   username: 'alice',
   privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.echo@1.0.0',
+  serviceFqn: 'chat@1.0.0',
   isPublic: true,
-  handler: (channel, peer) => {
-    channel.onmessage = (e) => {
-      console.log('Received:', e.data);
-      channel.send(`Echo: ${e.data}`);
-    };
+  poolSize: 50,  // Handle 50 concurrent users
+  handler: (channel, connectionId) => {
+    console.log(`User ${connectionId} joined`);
+
+    channel.on('message', (data) => {
+      console.log(`[${connectionId}]: ${data}`);
+      // Broadcast to all users (implement your broadcast logic)
+    });
+
+    channel.on('close', () => {
+      console.log(`User ${connectionId} left`);
+    });
   }
 });
 
-// Consumer
+await service.start();
+
+// Client
 const client2 = new Rondevu();
 await client2.register();
 
-const { peer, channel } = await client2.discovery.connect(
-  'alice',
-  'com.example.echo@1.0.0'
-);
+const connection = await client2.connect('alice', 'chat@1.0.0');
+const channel = connection.createChannel('chat');
 
-channel.onmessage = (e) => console.log('Received:', e.data);
-channel.send('Hello!');
+channel.on('message', (data) => {
+  console.log('Message:', data);
+});
+
+await connection.connect();
+channel.send('Hello everyone!');
 ```
 
-### File Transfer Service
+### File Transfer with Progress
 
 ```typescript
-// Publisher
-await client.services.exposeService({
+// Server
+const service = await client.exposeService({
   username: 'alice',
   privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.files@1.0.0',
-  isPublic: false,
-  handler: (channel, peer) => {
-    channel.binaryType = 'arraybuffer';
-
-    channel.onmessage = (e) => {
-      if (typeof e.data === 'string') {
-        console.log('Request:', JSON.parse(e.data));
-      } else {
-        console.log('Received file chunk:', e.data.byteLength, 'bytes');
+  serviceFqn: 'files@1.0.0',
+  handler: (channel, connectionId) => {
+    channel.on('message', async (data) => {
+      const request = JSON.parse(data);
+
+      if (request.action === 'download') {
+        const file = await fs.readFile(request.path);
+        const chunkSize = 16 * 1024; // 16KB chunks
+
+        for (let i = 0; i < file.byteLength; i += chunkSize) {
+          const chunk = file.slice(i, i + chunkSize);
+          channel.send(chunk);
+
+          // Wait for buffer to drain if needed
+          while (channel.bufferedAmount > 16 * 1024 * 1024) { // 16MB
+            await new Promise(resolve => setTimeout(resolve, 100));
+          }
+        }
+
+        channel.send(JSON.stringify({ done: true }));
       }
-    };
+    });
   }
 });
 
-// Consumer
-const { peer, channel } = await client.discovery.connect(
-  'alice',
-  'com.example.files@1.0.0'
-);
+await service.start();
 
-channel.binaryType = 'arraybuffer';
+// Client
+const connection = await client.connect('alice', 'files@1.0.0');
+const channel = connection.createChannel('files');
 
-// Request file
-channel.send(JSON.stringify({ action: 'get', path: '/readme.txt' }));
-
-channel.onmessage = (e) => {
-  if (e.data instanceof ArrayBuffer) {
-    console.log('Received file:', e.data.byteLength, 'bytes');
+const chunks = [];
+channel.on('message', (data) => {
+  if (typeof data === 'string') {
+    const msg = JSON.parse(data);
+    if (msg.done) {
+      const blob = new Blob(chunks);
+      console.log('Download complete:', blob.size, 'bytes');
+    }
+  } else {
+    chunks.push(data);
+    console.log('Progress:', chunks.length * 16 * 1024, 'bytes');
   }
-};
+});
+
+await connection.connect();
+channel.send(JSON.stringify({ action: 'download', path: '/file.zip' }));
 ```
 
-### Video Chat Service
+## Platform-Specific Setup
 
-```typescript
-// Publisher
-const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+### Modern Browsers
+Works out of the box - no additional setup needed.
 
-const peer = client.createPeer();
-stream.getTracks().forEach(track => peer.addTrack(track, stream));
+### Node.js 18+
+Native fetch is available, but you need WebRTC polyfills:
 
-const offerId = await peer.createOffer({ ttl: 300000 });
+```bash
+npm install wrtc
+```
 
-await client.services.publishService({
-  username: 'alice',
-  privateKey: keypair.privateKey,
-  serviceFqn: 'com.example.videochat@1.0.0',
-  isPublic: true
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
+
+const client = new Rondevu({
+  baseUrl: 'https://api.ronde.vu',
+  RTCPeerConnection,
+  RTCSessionDescription,
+  RTCIceCandidate
 });
+```
+
+### Node.js < 18
+Install both fetch and WebRTC polyfills:
 
-// Consumer
-const { peer, channel } = await client.discovery.connect(
-  'alice',
-  'com.example.videochat@1.0.0'
-);
+```bash
+npm install node-fetch wrtc
+```
 
-peer.on('track', (event) => {
-  const remoteStream = event.streams[0];
-  videoElement.srcObject = remoteStream;
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+import fetch from 'node-fetch';
+import { RTCPeerConnection, RTCSessionDescription, RTCIceCandidate } from 'wrtc';
+
+const client = new Rondevu({
+  baseUrl: 'https://api.ronde.vu',
+  fetch: fetch as any,
+  RTCPeerConnection,
+  RTCSessionDescription,
+  RTCIceCandidate
 });
 ```
 
@@ -652,41 +622,37 @@ All types are exported:
 
 ```typescript
 import type {
+  // Client types
   Credentials,
   RondevuOptions,
 
   // Username types
   UsernameCheckResult,
   UsernameClaimResult,
-  Keypair,
-
-  // Service types
-  ServicePublishResult,
-  PublishServiceOptions,
-  ServiceHandle,
-
-  // Discovery types
-  ServiceInfo,
-  ServiceListResult,
-  ServiceQueryResult,
-  ServiceDetails,
-  ConnectResult,
-
-  // Peer types
-  PeerOptions,
-  PeerEvents,
-  PeerTimeouts
+
+  // Durable connection types
+  DurableConnectionState,
+  DurableChannelState,
+  DurableConnectionConfig,
+  DurableChannelConfig,
+  DurableServiceConfig,
+  QueuedMessage,
+  DurableConnectionEvents,
+  DurableChannelEvents,
+  DurableServiceEvents,
+  ConnectionInfo,
+  ServiceInfo
 } from '@xtr-dev/rondevu-client';
 ```
 
-## Migration from V1
+## Migration from v0.8.x
 
-V2 is a **breaking change** that replaces topic-based discovery with username claiming and service publishing. See the main [MIGRATION.md](../MIGRATION.md) for detailed migration guide.
+v0.9.0 is a **breaking change** that replaces the low-level APIs with high-level durable connections. See [MIGRATION.md](./MIGRATION.md) for detailed migration guide.
 
 **Key Changes:**
-- ❌ Removed: `offers.findByTopic()`, `offers.getTopics()`, bloom filters
-- ✅ Added: `usernames.*`, `services.*`, `discovery.*` APIs
-- ✅ Changed: Focus on service-based discovery instead of topics
+- ❌ Removed: `client.services.*`, `client.discovery.*`, `client.createPeer()` (low-level APIs)
+- ✅ Added: `client.exposeService()`, `client.connect()`, `client.connectByUuid()` (durable APIs)
+- ✅ Changed: Focus on durable connections with automatic reconnection and message queuing
 
 ## License