@xtr-dev/rondevu-client 0.0.2 → 0.0.3

package/README.md

@@ -1,6 +1,15 @@
 # @xtr-dev/rondevu-client
 
-TypeScript client for interacting with the Rondevu peer signaling and discovery server. Provides a simple, type-safe API for WebRTC peer discovery and connection establishment.
+TypeScript/JavaScript client for WebRTC peer-to-peer connections with automatic signaling and connection management.
+
+## Features
+
+- ✨ **Simple API** - Three methods to establish connections: `create()`, `connect()`, `join()`
+- 🔄 **Automatic Everything** - Handles signaling, ICE candidates, and connection lifecycle
+- 📡 **Event-Driven** - Clean event-based API for connection state and data
+- 🎯 **Type-Safe** - Full TypeScript support with comprehensive type definitions
+- 🌐 **Universal** - Works in browsers and Node.js
+- 🚀 **Zero Dependencies** - Lightweight with no runtime dependencies
 
 ## Installation
 
@@ -8,227 +17,624 @@ TypeScript client for interacting with the Rondevu peer signaling and discovery
 npm install @xtr-dev/rondevu-client
 ```
 
-## Usage
-
-### Basic Setup
+## Quick Start
 
 ```typescript
-import { RondevuClient } from '@xtr-dev/rondevu-client';
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+// Initialize once
+const rdv = new Rondevu({
+  baseUrl: 'https://your-rondevu-server.com',
+  rtcConfig: {
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+  }
+});
 
-const client = new RondevuClient({
-  baseUrl: 'https://rondevu.example.com',
-  // Optional: custom origin for session isolation
-  origin: 'https://myapp.com'
+// Peer A: Create a connection
+const connA = await rdv.create('meeting-123', 'meetings');
+connA.on('connect', () => {
+  const channel = connA.dataChannel('chat');
+  channel.send('Hello!');
+});
+
+// Peer B: Connect to the connection
+const connB = await rdv.connect('meeting-123');
+connB.on('datachannel', (channel) => {
+  channel.onmessage = (e) => console.log('Received:', e.data);
 });
 ```
 
-### Peer Discovery Flow
+## API Documentation
+
+### Rondevu Class
 
-#### 1. List Available Topics
+The main class for WebRTC connection management with automatic signaling.
+
+#### Constructor
 
 ```typescript
-// Get all topics with peer counts
-const { topics, pagination } = await client.listTopics();
+const rdv = new Rondevu(options: RondevuOptions);
+```
 
-topics.forEach(topic => {
-  console.log(`${topic.topic}: ${topic.count} peers available`);
-});
+**Options:**
+```typescript
+interface RondevuOptions {
+  baseUrl: string;                    // Rondevu server URL (required)
+  peerId?: string;                    // Custom peer ID (auto-generated if not provided)
+  origin?: string;                    // Origin for session isolation
+  fetch?: typeof fetch;               // Custom fetch (for Node.js)
+  rtcConfig?: RTCConfiguration;       // WebRTC configuration (ICE servers, etc.)
+  pollingInterval?: number;           // Polling interval in ms (default: 1000)
+  connectionTimeout?: number;         // Connection timeout in ms (default: 30000)
+}
 ```
 
-#### 2. Create an Offer (Peer A)
+#### Properties
+
+- `peerId: string` - The current peer identifier (read-only)
+
+#### Methods
+
+##### `create(id: string, topic: string): Promise<RondevuConnection>`
+
+Creates a new connection (offerer role) and waits for a peer to join.
 
 ```typescript
-// Announce availability in a topic
-const { code } = await client.createOffer('my-room', {
-  info: 'peer-A-unique-id',
-  offer: webrtcOfferData
-});
+const connection = await rdv.create('my-connection-id', 'my-topic');
+```
+
+**Parameters:**
+- `id` - Connection identifier (can be any string)
+- `topic` - Topic name for grouping connections (max 1024 chars)
+
+**Returns:** `RondevuConnection` object
+
+**Use case:** When you want to create a new connection and share its ID with others.
 
-console.log('Session code:', code);
+---
+
+##### `connect(id: string): Promise<RondevuConnection>`
+
+Connects to an existing connection by ID (answerer role).
+
+```typescript
+const connection = await rdv.connect('my-connection-id');
 ```
 
-#### 3. Discover Peers (Peer B)
+**Parameters:**
+- `id` - The connection ID to join
+
+**Returns:** `RondevuConnection` object
+
+**Use case:** When you have a specific connection ID (e.g., from a QR code, link, or shared message).
+
+---
+
+##### `join(topic: string, options?: JoinOptions): Promise<RondevuConnection>`
+
+Joins a topic and automatically connects to the first available peer (answerer role).
 
 ```typescript
-// Find available peers in a topic
-const { sessions } = await client.listSessions('my-room');
+const connection = await rdv.join('my-topic');
+```
 
-// Filter out your own sessions
-const otherPeers = sessions.filter(s => s.info !== 'my-peer-id');
+**Parameters:**
+- `topic` - Topic name to join
+- `options` - Optional join options
 
-if (otherPeers.length > 0) {
-  const peer = otherPeers[0];
-  console.log('Found peer:', peer.info);
+```typescript
+interface JoinOptions {
+  filter?: (session: { code: string; peerId: string }) => boolean;
+  select?: 'first' | 'newest' | 'oldest' | 'random';
 }
 ```
 
-#### 4. Send Answer (Peer B)
+**Returns:** `RondevuConnection` object
 
+**Use case:** When you want automatic peer discovery and connection.
+
+**Example with options:**
 ```typescript
-// Connect to a peer by answering their offer
-await client.sendAnswer({
-  code: peer.code,
-  answer: webrtcAnswerData,
-  side: 'answerer'
+const connection = await rdv.join('game-room', {
+  filter: (session) => session.peerId.startsWith('player-'),
+  select: 'random'
 });
 ```
 
-#### 5. Poll for Data (Both Peers)
+---
+
+##### `updatePeerId(newPeerId: string): void`
+
+Updates the peer ID (useful when user identity changes).
 
 ```typescript
-// Offerer polls for answer
-const offererData = await client.poll(code, 'offerer');
-if (offererData.answer) {
-  console.log('Received answer from peer');
-}
+rdv.updatePeerId('new-peer-id');
+```
 
-// Answerer polls for offer details
-const answererData = await client.poll(code, 'answerer');
-console.log('Offer candidates:', answererData.offerCandidates);
+---
+
+### RondevuConnection Class
+
+Represents a WebRTC connection with event-driven API.
+
+#### Properties
+
+- `id: string` - Connection identifier (read-only)
+- `topic: string` - Topic name (read-only)
+- `role: 'offerer' | 'answerer'` - Connection role (read-only)
+- `remotePeerId: string` - Remote peer's ID (read-only)
+
+#### Methods
+
+##### `dataChannel(label: string, options?: RTCDataChannelInit): RTCDataChannel`
+
+Gets or creates a data channel.
+
+```typescript
+const channel = connection.dataChannel('chat');
+channel.onopen = () => channel.send('Hello!');
 ```
 
-#### 6. Exchange ICE Candidates
+**Parameters:**
+- `label` - Data channel label/name
+- `options` - Optional RTCDataChannel configuration
+
+**Returns:** `RTCDataChannel` object
+
+---
+
+##### `addStream(stream: MediaStream): void`
+
+Adds a local media stream (audio/video) to the connection.
 
 ```typescript
-// Send additional signaling data
-await client.sendAnswer({
-  code: sessionCode,
-  candidate: iceCandidate,
-  side: 'offerer' // or 'answerer'
+const stream = await navigator.mediaDevices.getUserMedia({
+  video: true,
+  audio: true
 });
+connection.addStream(stream);
 ```
 
-### Health Check
+---
+
+##### `getPeerConnection(): RTCPeerConnection`
+
+Gets the underlying `RTCPeerConnection` for advanced use cases.
 
 ```typescript
-const health = await client.health();
-console.log('Server status:', health.status);
-console.log('Timestamp:', health.timestamp);
+const pc = connection.getPeerConnection();
+const stats = await pc.getStats();
 ```
 
-## API Reference
+**Use case:** Accessing WebRTC stats, adding custom tracks, or other advanced WebRTC features.
 
-### `RondevuClient`
+---
 
-#### Constructor
+##### `close(): void`
+
+Closes the connection and cleans up resources.
 
 ```typescript
-new RondevuClient(options: RondevuClientOptions)
+connection.close();
 ```
 
-**Options:**
-- `baseUrl` (string, required): Base URL of the Rondevu server
-- `origin` (string, optional): Origin header for session isolation (defaults to baseUrl origin)
-- `fetch` (function, optional): Custom fetch implementation (for Node.js)
+---
 
-#### Methods
+#### Events
 
-##### `listTopics(page?, limit?)`
+Listen to connection events using the `.on()` method:
 
-Lists all topics with peer counts.
+##### `'connect'`
 
-**Parameters:**
-- `page` (number, optional): Page number, default 1
-- `limit` (number, optional): Results per page, default 100, max 1000
+Emitted when the WebRTC connection is established.
 
-**Returns:** `Promise<ListTopicsResponse>`
+```typescript
+connection.on('connect', () => {
+  console.log('Connected!');
+});
+```
 
-##### `listSessions(topic)`
+---
 
-Discovers available peers for a given topic.
+##### `'disconnect'`
 
-**Parameters:**
-- `topic` (string): Topic identifier
+Emitted when the connection is closed or lost.
 
-**Returns:** `Promise<ListSessionsResponse>`
+```typescript
+connection.on('disconnect', () => {
+  console.log('Disconnected');
+});
+```
 
-##### `createOffer(topic, request)`
+---
 
-Announces peer availability and creates a new session.
+##### `'error'`
 
-**Parameters:**
-- `topic` (string): Topic identifier (max 256 characters)
-- `request` (CreateOfferRequest):
-  - `info` (string): Peer identifier/metadata (max 1024 characters)
-  - `offer` (string): WebRTC signaling data
+Emitted when an error occurs.
 
-**Returns:** `Promise<CreateOfferResponse>`
+```typescript
+connection.on('error', (error: Error) => {
+  console.error('Connection error:', error.message);
+});
+```
 
-##### `sendAnswer(request)`
+---
 
-Sends an answer or candidate to an existing session.
+##### `'datachannel'`
 
-**Parameters:**
-- `request` (AnswerRequest):
-  - `code` (string): Session UUID
-  - `answer` (string, optional): Answer signaling data
-  - `candidate` (string, optional): ICE candidate data
-  - `side` ('offerer' | 'answerer'): Which peer is sending
+Emitted when a remote peer creates a data channel.
 
-**Returns:** `Promise<AnswerResponse>`
+```typescript
+connection.on('datachannel', (channel: RTCDataChannel) => {
+  console.log('Received channel:', channel.label);
+  channel.onmessage = (e) => console.log(e.data);
+});
+```
 
-##### `poll(code, side)`
+---
 
-Polls for session data from the other peer.
+##### `'stream'`
 
-**Parameters:**
-- `code` (string): Session UUID
-- `side` ('offerer' | 'answerer'): Which side is polling
+Emitted when a remote media stream is received.
+
+```typescript
+connection.on('stream', (stream: MediaStream) => {
+  videoElement.srcObject = stream;
+});
+```
+
+---
 
-**Returns:** `Promise<PollOffererResponse | PollAnswererResponse>`
+## Usage Examples
 
-##### `health()`
+### Example 1: Simple Chat Application
 
-Checks server health.
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  rtcConfig: {
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+  }
+});
+
+// Peer A: Create connection
+const connectionA = await rdv.create('chat-room-123', 'chat-rooms');
 
-**Returns:** `Promise<HealthResponse>`
+connectionA.on('connect', () => {
+  const chat = connectionA.dataChannel('messages');
+  chat.send(JSON.stringify({ user: 'Alice', text: 'Hello!' }));
+});
+
+connectionA.on('datachannel', (channel) => {
+  if (channel.label === 'messages') {
+    channel.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      console.log(`${msg.user}: ${msg.text}`);
+    };
+  }
+});
 
-## TypeScript Types
+// Share 'chat-room-123' with Peer B
 
-All types are exported from the main package:
+// Peer B: Join connection
+const connectionB = await rdv.connect('chat-room-123');
+
+connectionB.on('connect', () => {
+  const chat = connectionB.dataChannel('messages');
+  chat.send(JSON.stringify({ user: 'Bob', text: 'Hi Alice!' }));
+});
+```
+
+---
+
+### Example 2: Video Chat
 
 ```typescript
-import {
-  RondevuClient,
-  Session,
-  TopicInfo,
-  CreateOfferRequest,
-  AnswerRequest,
-  PollRequest,
-  Side,
-  // ... and more
-} from '@xtr-dev/rondevu-client';
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  rtcConfig: {
+    iceServers: [
+      { urls: 'stun:stun.l.google.com:19302' },
+      {
+        urls: 'turn:your-turn-server.com:3478',
+        username: 'user',
+        credential: 'pass'
+      }
+    ]
+  }
+});
+
+// Get local video stream
+const localStream = await navigator.mediaDevices.getUserMedia({
+  video: true,
+  audio: true
+});
+document.getElementById('local-video').srcObject = localStream;
+
+// Create connection and add stream
+const connection = await rdv.create('video-call-456', 'video-calls');
+connection.addStream(localStream);
+
+// Handle remote stream
+connection.on('stream', (remoteStream) => {
+  document.getElementById('remote-video').srcObject = remoteStream;
+});
+
+connection.on('connect', () => {
+  console.log('Video call connected!');
+});
+
+// Other peer joins
+// const connection = await rdv.connect('video-call-456');
+```
+
+---
+
+### Example 3: Topic-Based Discovery
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  peerId: 'player-123' // Custom peer ID
+});
+
+// Create a game session
+const host = await rdv.create('game-session-1', 'multiplayer-games');
+
+host.on('connect', () => {
+  console.log('Player joined:', host.remotePeerId);
+
+  const game = host.dataChannel('game-state');
+  game.send(JSON.stringify({ type: 'start', level: 1 }));
+});
+
+// Another player discovers and joins
+const player = await rdv.join('multiplayer-games', {
+  filter: (session) => session.peerId !== rdv.peerId, // Avoid self
+  select: 'first' // Join first available game
+});
+
+player.on('connect', () => {
+  console.log('Joined game with:', player.remotePeerId);
+});
+
+player.on('datachannel', (channel) => {
+  channel.onmessage = (e) => {
+    const data = JSON.parse(e.data);
+    console.log('Game event:', data);
+  };
+});
 ```
 
-## Node.js Usage
+---
 
-For Node.js environments (v18+), the built-in fetch is used automatically. For older Node.js versions, provide a fetch implementation:
+### Example 4: Connection Stats Monitoring
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+
+const rdv = new Rondevu({ baseUrl: 'https://your-server.com' });
+const connection = await rdv.connect('meeting-123');
+
+connection.on('connect', () => {
+  // Access underlying RTCPeerConnection for stats
+  const pc = connection.getPeerConnection();
+
+  setInterval(async () => {
+    const stats = await pc.getStats();
+
+    stats.forEach(report => {
+      if (report.type === 'candidate-pair' && report.state === 'succeeded') {
+        console.log('RTT:', report.currentRoundTripTime * 1000, 'ms');
+        console.log('Bytes sent:', report.bytesSent);
+        console.log('Bytes received:', report.bytesReceived);
+      }
+    });
+  }, 2000);
+});
+```
+
+---
+
+## Low-Level API (Advanced)
+
+For advanced use cases, you can use the low-level `RondevuClient` for manual signaling:
 
 ```typescript
-import fetch from 'node-fetch';
 import { RondevuClient } from '@xtr-dev/rondevu-client';
 
 const client = new RondevuClient({
-  baseUrl: 'https://rondevu.example.com',
-  fetch: fetch as any
+  baseUrl: 'https://your-server.com'
+});
+
+// List topics
+const { topics } = await client.listTopics();
+
+// List sessions in a topic
+const { sessions } = await client.listSessions('my-topic');
+
+// Create offer manually
+const { code } = await client.createOffer('my-topic', {
+  peerId: 'my-peer-id',
+  offer: sdpOffer,
+  code: 'custom-session-id' // Optional
+});
+
+// Send answer
+await client.sendAnswer({
+  code: sessionCode,
+  answer: sdpAnswer,
+  side: 'answerer'
+});
+
+// Poll for remote data
+const data = await client.poll(sessionCode, 'offerer');
+```
+
+See the original README for full low-level API documentation.
+
+---
+
+## Configuration
+
+### ICE Servers
+
+Configure STUN/TURN servers for NAT traversal:
+
+```typescript
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  rtcConfig: {
+    iceServers: [
+      // Public STUN servers
+      { urls: 'stun:stun.l.google.com:19302' },
+      { urls: 'stun:stun1.l.google.com:19302' },
+
+      // Private TURN server (recommended for production)
+      {
+        urls: 'turn:your-turn-server.com:3478',
+        username: 'username',
+        credential: 'password'
+      }
+    ],
+    iceTransportPolicy: 'all' // 'relay' to force TURN
+  }
 });
 ```
 
+### Polling and Timeouts
+
+Customize polling interval and connection timeout:
+
+```typescript
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  pollingInterval: 500,      // Poll every 500ms (default: 1000)
+  connectionTimeout: 60000    // 60 second timeout (default: 30000)
+});
+```
+
+### Custom Peer ID
+
+Provide a custom peer identifier:
+
+```typescript
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  peerId: 'user-alice-session-xyz'
+});
+
+console.log(rdv.peerId); // 'user-alice-session-xyz'
+
+// Update later if needed
+rdv.updatePeerId('user-alice-new-session');
+```
+
+---
+
 ## Error Handling
 
-All API methods throw errors with descriptive messages:
+Always handle connection errors:
 
 ```typescript
-try {
-  await client.createOffer('my-room', {
-    info: 'peer-id',
-    offer: data
-  });
-} catch (error) {
-  console.error('Failed to create offer:', error.message);
-}
+const connection = await rdv.create('session-1', 'topic-1');
+
+connection.on('error', (error) => {
+  console.error('Connection error:', error.message);
+
+  if (error.message.includes('timeout')) {
+    // Handle timeout
+  } else if (error.message.includes('not found')) {
+    // Handle session not found
+  }
+});
+
+connection.on('disconnect', () => {
+  console.log('Connection closed');
+  // Cleanup UI, attempt reconnection, etc.
+});
+```
+
+---
+
+## TypeScript Support
+
+The library is written in TypeScript and includes comprehensive type definitions:
+
+```typescript
+import {
+  Rondevu,
+  RondevuConnection,
+  RondevuOptions,
+  JoinOptions,
+  ConnectionRole
+} from '@xtr-dev/rondevu-client';
+
+const options: RondevuOptions = {
+  baseUrl: 'https://your-server.com',
+  rtcConfig: {
+    iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
+  }
+};
+
+const rdv: Rondevu = new Rondevu(options);
+const connection: RondevuConnection = await rdv.create('id', 'topic');
+
+console.log(connection.role); // Type: 'offerer' | 'answerer'
+```
+
+---
+
+## Node.js Support
+
+The library works in Node.js with a WebRTC polyfill:
+
+```bash
+npm install wrtc
+```
+
+```typescript
+import { Rondevu } from '@xtr-dev/rondevu-client';
+import wrtc from 'wrtc';
+
+// Polyfill WebRTC globals
+global.RTCPeerConnection = wrtc.RTCPeerConnection;
+global.RTCSessionDescription = wrtc.RTCSessionDescription;
+global.RTCIceCandidate = wrtc.RTCIceCandidate;
+
+const rdv = new Rondevu({
+  baseUrl: 'https://your-server.com',
+  fetch: fetch // Use node-fetch if needed
+});
 ```
 
+---
+
+## Browser Compatibility
+
+- Chrome/Edge 56+
+- Firefox 44+
+- Safari 11+
+- Opera 43+
+
+Requires WebRTC support (`RTCPeerConnection`, `RTCDataChannel`).
+
+---
+
 ## License
 
 MIT
+
+---
+
+## Links
+
+- [GitHub Repository](https://github.com/xtr-dev/rondevu)
+- [Server Documentation](https://github.com/xtr-dev/rondevu/tree/main/server)
+- [Demo Application](https://github.com/xtr-dev/rondevu/tree/main/demo)