@xtr-dev/rondevu-client 0.0.3 → 0.0.5

package/README.md

@@ -1,640 +1,60 @@
-# @xtr-dev/rondevu-client
+# Rondevu
 
-TypeScript/JavaScript client for WebRTC peer-to-peer connections with automatic signaling and connection management.
+🎯 Meet WebRTC peers by topic, by peer ID, or by connection ID.
 
-## Features
+## @xtr-dev/rondevu-client
 
-- ✨ **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
+[![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-client)](https://www.npmjs.com/package/@xtr-dev/rondevu-client)
 
-## Installation
+TypeScript Rondevu HTTP and WebRTC client, for simple peer discovery and connection.
+
+### Install
 
 ```bash
 npm install @xtr-dev/rondevu-client
 ```
 
-## Quick Start
+### Usage
 
 ```typescript
 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' }]
-  }
-});
-
-// 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);
-});
-```
-
-## API Documentation
-
-### Rondevu Class
-
-The main class for WebRTC connection management with automatic signaling.
-
-#### Constructor
-
-```typescript
-const rdv = new Rondevu(options: RondevuOptions);
-```
-
-**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)
-}
-```
-
-#### 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
-const connection = await rdv.create('my-connection-id', 'my-topic');
-```
+const rdv = new Rondevu({ baseUrl: 'https://server.com' });
 
-**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.
-
----
-
-##### `connect(id: string): Promise<RondevuConnection>`
-
-Connects to an existing connection by ID (answerer role).
-
-```typescript
-const connection = await rdv.connect('my-connection-id');
-```
+// Connect by topic
+const conn = await rdv.join('room');
 
-**Parameters:**
-- `id` - The connection ID to join
+// Or connect by ID
+const conn = await rdv.connect('meeting-123');
 
-**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
-const connection = await rdv.join('my-topic');
-```
-
-**Parameters:**
-- `topic` - Topic name to join
-- `options` - Optional join options
-
-```typescript
-interface JoinOptions {
-  filter?: (session: { code: string; peerId: string }) => boolean;
-  select?: 'first' | 'newest' | 'oldest' | 'random';
-}
-```
-
-**Returns:** `RondevuConnection` object
-
-**Use case:** When you want automatic peer discovery and connection.
-
-**Example with options:**
-```typescript
-const connection = await rdv.join('game-room', {
-  filter: (session) => session.peerId.startsWith('player-'),
-  select: 'random'
-});
-```
-
----
-
-##### `updatePeerId(newPeerId: string): void`
-
-Updates the peer ID (useful when user identity changes).
-
-```typescript
-rdv.updatePeerId('new-peer-id');
-```
-
----
-
-### 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!');
-```
-
-**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
-const stream = await navigator.mediaDevices.getUserMedia({
-  video: true,
-  audio: true
-});
-connection.addStream(stream);
-```
-
----
-
-##### `getPeerConnection(): RTCPeerConnection`
-
-Gets the underlying `RTCPeerConnection` for advanced use cases.
-
-```typescript
-const pc = connection.getPeerConnection();
-const stats = await pc.getStats();
-```
-
-**Use case:** Accessing WebRTC stats, adding custom tracks, or other advanced WebRTC features.
-
----
-
-##### `close(): void`
-
-Closes the connection and cleans up resources.
-
-```typescript
-connection.close();
-```
-
----
-
-#### Events
-
-Listen to connection events using the `.on()` method:
-
-##### `'connect'`
-
-Emitted when the WebRTC connection is established.
-
-```typescript
-connection.on('connect', () => {
-  console.log('Connected!');
-});
-```
-
----
-
-##### `'disconnect'`
-
-Emitted when the connection is closed or lost.
-
-```typescript
-connection.on('disconnect', () => {
-  console.log('Disconnected');
-});
-```
-
----
-
-##### `'error'`
-
-Emitted when an error occurs.
-
-```typescript
-connection.on('error', (error: Error) => {
-  console.error('Connection error:', error.message);
-});
-```
-
----
-
-##### `'datachannel'`
-
-Emitted when a remote peer creates a data channel.
-
-```typescript
-connection.on('datachannel', (channel: RTCDataChannel) => {
-  console.log('Received channel:', channel.label);
-  channel.onmessage = (e) => console.log(e.data);
-});
-```
-
----
-
-##### `'stream'`
-
-Emitted when a remote media stream is received.
-
-```typescript
-connection.on('stream', (stream: MediaStream) => {
-  videoElement.srcObject = stream;
-});
-```
-
----
-
-## Usage Examples
-
-### Example 1: Simple Chat Application
-
-```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');
-
-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}`);
-    };
-  }
-});
-
-// Share 'chat-room-123' with Peer B
-
-// 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 { 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);
-  };
-});
-```
-
----
-
-### 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 { RondevuClient } from '@xtr-dev/rondevu-client';
-
-const client = new RondevuClient({
-  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
-
-Always handle connection errors:
-
-```typescript
-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
+// Use the connection
+conn.on('connect', () => {
+  const channel = conn.dataChannel('chat');
+  channel.send('Hello!');
 });
 ```
 
----
+### API
 
-## Browser Compatibility
+**Main Methods:**
+- `rdv.join(topic)` - Auto-connect to first peer in topic
+- `rdv.join(topic, {filter})` - Connect to specific peer by ID
+- `rdv.create(id, topic)` - Create connection for others to join
+- `rdv.connect(id)` - Join connection by ID
 
-- Chrome/Edge 56+
-- Firefox 44+
-- Safari 11+
-- Opera 43+
+**Connection Events:**
+- `connect` - Connection established
+- `disconnect` - Connection closed
+- `datachannel` - Remote peer created data channel
+- `stream` - Remote media stream received
+- `error` - Error occurred
 
-Requires WebRTC support (`RTCPeerConnection`, `RTCDataChannel`).
+**Connection Methods:**
+- `conn.dataChannel(label)` - Get or create data channel
+- `conn.addStream(stream)` - Add media stream
+- `conn.getPeerConnection()` - Get underlying RTCPeerConnection
+- `conn.close()` - Close connection
 
----
-
-## License
+### 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)

package/dist/rondevu.d.ts

@@ -6,6 +6,8 @@ import { RondevuOptions, JoinOptions } from './types';
 export declare class Rondevu {
     readonly peerId: string;
     private client;
+    private baseUrl;
+    private fetchImpl?;
     private rtcConfig?;
     private pollingInterval;
     private connectionTimeout;
@@ -13,7 +15,7 @@ export declare class Rondevu {
      * Creates a new Rondevu client instance
      * @param options - Client configuration options
      */
-    constructor(options: RondevuOptions);
+    constructor(options?: RondevuOptions);
     /**
      * Generate a unique peer ID
      */
@@ -32,9 +34,10 @@ export declare class Rondevu {
     /**
      * Connect to an existing connection by ID (answerer role)
      * @param id - Connection identifier
+     * @param origin - Optional origin header override for this connection
      * @returns Promise that resolves to RondevuConnection
      */
-    connect(id: string): Promise<RondevuConnection>;
+    connect(id: string, origin?: string): Promise<RondevuConnection>;
     /**
      * Join a topic and discover available peers (answerer role)
      * @param topic - Topic name
@@ -54,5 +57,5 @@ export declare class Rondevu {
      * Find a session by connection ID
      * This requires polling since we don't know which topic it's in
      */
-    private findSessionById;
+    private findSessionByIdWithClient;
 }

package/dist/rondevu.js

@@ -8,9 +8,11 @@ export class Rondevu {
      * Creates a new Rondevu client instance
      * @param options - Client configuration options
      */
-    constructor(options) {
+    constructor(options = {}) {
+        this.baseUrl = options.baseUrl || 'https://rondevu.xtrdev.workers.dev';
+        this.fetchImpl = options.fetch;
         this.client = new RondevuClient({
-            baseUrl: options.baseUrl,
+            baseUrl: this.baseUrl,
             origin: options.origin,
             fetch: options.fetch,
         });
@@ -73,11 +75,20 @@ export class Rondevu {
     /**
      * Connect to an existing connection by ID (answerer role)
      * @param id - Connection identifier
+     * @param origin - Optional origin header override for this connection
      * @returns Promise that resolves to RondevuConnection
      */
-    async connect(id) {
+    async connect(id, origin) {
+        // Create a client with overridden origin if specified
+        const client = origin
+            ? new RondevuClient({
+                baseUrl: this.baseUrl,
+                origin,
+                fetch: this.fetchImpl,
+            })
+            : this.client;
         // Poll server to get session by ID
-        const sessionData = await this.findSessionById(id);
+        const sessionData = await this.findSessionByIdWithClient(id, client);
         if (!sessionData) {
             throw new Error(`Connection ${id} not found or expired`);
         }
@@ -94,7 +105,7 @@ export class Rondevu {
         // Wait for ICE gathering
         await this.waitForIceGathering(pc);
         // Send answer to server
-        await this.client.sendAnswer({
+        await client.sendAnswer({
             code: id,
             answer: pc.localDescription.sdp,
             side: 'answerer',
@@ -110,7 +121,7 @@ export class Rondevu {
             pollingInterval: this.pollingInterval,
             connectionTimeout: this.connectionTimeout,
         };
-        const connection = new RondevuConnection(connectionParams, this.client);
+        const connection = new RondevuConnection(connectionParams, client);
         // Start polling for ICE candidates
         connection.startPolling();
         return connection;
@@ -181,11 +192,11 @@ export class Rondevu {
      * Find a session by connection ID
      * This requires polling since we don't know which topic it's in
      */
-    async findSessionById(id) {
+    async findSessionByIdWithClient(id, client) {
         try {
             // Try to poll for the session directly
             // The poll endpoint should return the session data
-            const response = await this.client.poll(id, 'answerer');
+            const response = await client.poll(id, 'answerer');
             const answererResponse = response;
             if (answererResponse.offer) {
                 return {

package/dist/types.d.ts

@@ -150,8 +150,8 @@ export interface RondevuClientOptions {
  * Configuration options for Rondevu WebRTC client
  */
 export interface RondevuOptions {
-    /** Base URL of the Rondevu server (e.g., 'https://example.com') */
-    baseUrl: string;
+    /** Base URL of the Rondevu server (defaults to 'https://rondevu.xtrdev.workers.dev') */
+    baseUrl?: string;
     /** Peer identifier (optional, auto-generated if not provided) */
     peerId?: string;
     /** Origin header value for session isolation (defaults to baseUrl origin) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtr-dev/rondevu-client",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "TypeScript client for Rondevu peer signaling and discovery server",
   "type": "module",
   "main": "dist/index.js",