@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.

Installation

npm install @xtr-dev/rondevu-client

Usage

Basic Setup

import { RondevuClient } from '@xtr-dev/rondevu-client';

const client = new RondevuClient({
  baseUrl: 'https://rondevu.example.com',
  // Optional: custom origin for session isolation
  origin: 'https://myapp.com'
});

Peer Discovery Flow

1. List Available Topics

// Get all topics with peer counts
const { topics, pagination } = await client.listTopics();

topics.forEach(topic => {
  console.log(`${topic.topic}: ${topic.count} peers available`);
});

2. Create an Offer (Peer A)

// Announce availability in a topic
const { code } = await client.createOffer('my-room', {
  info: 'peer-A-unique-id',
  offer: webrtcOfferData
});

console.log('Session code:', code);

3. Discover Peers (Peer B)

// Find available peers in a topic
const { sessions } = await client.listSessions('my-room');

// Filter out your own sessions
const otherPeers = sessions.filter(s => s.info !== 'my-peer-id');

if (otherPeers.length > 0) {
  const peer = otherPeers[0];
  console.log('Found peer:', peer.info);
}

4. Send Answer (Peer B)

// Connect to a peer by answering their offer
await client.sendAnswer({
  code: peer.code,
  answer: webrtcAnswerData,
  side: 'answerer'
});

5. Poll for Data (Both Peers)

// Offerer polls for answer
const offererData = await client.poll(code, 'offerer');
if (offererData.answer) {
  console.log('Received answer from peer');
}

// Answerer polls for offer details
const answererData = await client.poll(code, 'answerer');
console.log('Offer candidates:', answererData.offerCandidates);

6. Exchange ICE Candidates

// Send additional signaling data
await client.sendAnswer({
  code: sessionCode,
  candidate: iceCandidate,
  side: 'offerer' // or 'answerer'
});

Health Check

const health = await client.health();
console.log('Server status:', health.status);
console.log('Timestamp:', health.timestamp);

API Reference

RondevuClient

Constructor

new RondevuClient(options: RondevuClientOptions)

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

listTopics(page?, limit?)

Lists all topics with peer counts.

Parameters:

• page (number, optional): Page number, default 1
• limit (number, optional): Results per page, default 100, max 1000

Returns: Promise<ListTopicsResponse>

listSessions(topic)

Discovers available peers for a given topic.

Parameters:

• topic (string): Topic identifier

Returns: Promise<ListSessionsResponse>

createOffer(topic, request)

Announces peer availability and creates a new session.

Parameters:

• topic (string): Topic identifier (max 256 characters)
• request (CreateOfferRequest):
  • info (string): Peer identifier/metadata (max 1024 characters)
  • offer (string): WebRTC signaling data

Returns: Promise<CreateOfferResponse>

sendAnswer(request)

Sends an answer or candidate to an existing session.

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

Returns: Promise<AnswerResponse>

poll(code, side)

Polls for session data from the other peer.

Parameters:

• code (string): Session UUID
• side ('offerer' | 'answerer'): Which side is polling

Returns: Promise<PollOffererResponse | PollAnswererResponse>

health()

Checks server health.

Returns: Promise<HealthResponse>

TypeScript Types

All types are exported from the main package:

import {
  RondevuClient,
  Session,
  TopicInfo,
  CreateOfferRequest,
  AnswerRequest,
  PollRequest,
  Side,
  // ... and more
} from '@xtr-dev/rondevu-client';

Node.js Usage

For Node.js environments (v18+), the built-in fetch is used automatically. For older Node.js versions, provide a fetch implementation:

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
});

Error Handling

All API methods throw errors with descriptive messages:

try {
  await client.createOffer('my-room', {
    info: 'peer-id',
    offer: data
  });
} catch (error) {
  console.error('Failed to create offer:', error.message);
}

License

MIT