rondevu-client/USAGE.md

Rondevu Client Usage Guide

Installation

npm install @xtr-dev/rondevu-client

Quick Start

1. Register and Create Connection

import { RondevuAPI, RondevuSignaler, WebRTCRondevuConnection } from '@xtr-dev/rondevu-client';

const API_URL = 'https://api.ronde.vu';

// Register to get credentials
const api = new RondevuAPI(API_URL);
const credentials = await api.register();

// Create authenticated API client
const authenticatedApi = new RondevuAPI(API_URL, credentials);

2. Create an Offer (Offerer Side)

// Create a connection
const connection = new WebRTCRondevuConnection(
  'connection-id',
  'host-username',
  'service-name'
);

// Wait for local description
await connection.ready;

// Create offer on server
const offers = await authenticatedApi.createOffers([{
  sdp: connection.connection.localDescription!.sdp!,
  ttl: 300000 // 5 minutes
}]);

const offerId = offers[0].id;

// Set up signaler for ICE candidate exchange
const signaler = new RondevuSignaler(authenticatedApi, offerId);
connection.setSignaler(signaler);

// Poll for answer
const checkAnswer = setInterval(async () => {
  const answer = await authenticatedApi.getAnswer(offerId);
  if (answer) {
    clearInterval(checkAnswer);
    await connection.connection.setRemoteDescription({
      type: 'answer',
      sdp: answer.sdp
    });
    console.log('Connection established!');
  }
}, 1000);

3. Answer an Offer (Answerer Side)

// Get the offer
const offer = await authenticatedApi.getOffer(offerId);

// Create connection with remote offer
const connection = new WebRTCRondevuConnection(
  'connection-id',
  'peer-username',
  'service-name',
  {
    type: 'offer',
    sdp: offer.sdp
  }
);

// Wait for local description (answer)
await connection.ready;

// Send answer to server
await authenticatedApi.answerOffer(
  offerId,
  connection.connection.localDescription!.sdp!
);

// Set up signaler for ICE candidate exchange
const signaler = new RondevuSignaler(authenticatedApi, offerId);
connection.setSignaler(signaler);

console.log('Connection established!');

Using Services

Publish a Service

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

const api = new RondevuAPI(API_URL, credentials);

const service = await api.publishService({
  username: 'my-username',
  serviceFqn: 'chat.app@1.0.0',
  sdp: localDescription.sdp,
  ttl: 300000,
  isPublic: true,
  metadata: { description: 'My chat service' },
  signature: '...', // Ed25519 signature
  message: '...'    // Signed message
});

console.log('Service UUID:', service.uuid);

Connect to a Service

// Search for services
const services = await api.searchServices('username', 'chat.app@1.0.0');

if (services.length > 0) {
  // Get service details with offer
  const service = await api.getService(services[0].uuid);

  // Create connection with service offer
  const connection = new WebRTCRondevuConnection(
    service.serviceId,
    service.username,
    service.serviceFqn,
    {
      type: 'offer',
      sdp: service.sdp
    }
  );

  await connection.ready;

  // Answer the service offer
  await api.answerOffer(
    service.offerId,
    connection.connection.localDescription!.sdp!
  );

  // Set up signaler
  const signaler = new RondevuSignaler(api, service.offerId);
  connection.setSignaler(signaler);
}

Event Handling

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

// Connection events
connection.events.on('state-change', (state) => {
  console.log('Connection state:', state);
});

connection.events.on('message', (message) => {
  console.log('Received message:', message);
});

// Custom events with EventBus
interface MyEvents {
  'user:connected': { userId: string; timestamp: number };
  'message:sent': string;
}

const events = new EventBus<MyEvents>();

events.on('user:connected', (data) => {
  console.log(`User ${data.userId} connected at ${data.timestamp}`);
});

events.emit('user:connected', {
  userId: '123',
  timestamp: Date.now()
});

Cleanup

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

const bin = createBin();

// Add cleanup functions
bin(
  () => console.log('Cleanup 1'),
  () => console.log('Cleanup 2')
);

// Clean all
bin.clean();

API Reference

RondevuAPI

Complete API client for Rondevu signaling server.

Methods:

• register() - Register new peer
• createOffers(offers) - Create offers
• getOffer(offerId) - Get offer by ID
• answerOffer(offerId, sdp) - Answer an offer
• getAnswer(offerId) - Poll for answer
• searchOffers(topic) - Search by topic
• addIceCandidates(offerId, candidates) - Add ICE candidates
• getIceCandidates(offerId, since) - Get ICE candidates (polling)
• publishService(service) - Publish service
• getService(uuid) - Get service by UUID
• searchServices(username, serviceFqn) - Search services
• checkUsername(username) - Check availability
• claimUsername(username, publicKey, signature, message) - Claim username

RondevuSignaler

Handles ICE candidate exchange via polling.

Constructor:

new RondevuSignaler(api: RondevuAPI, offerId: string)

Methods:

• addIceCandidate(candidate) - Send local candidate
• addListener(callback) - Poll for remote candidates (returns cleanup function)

WebRTCRondevuConnection

WebRTC connection wrapper with type-safe events.

Constructor:

new WebRTCRondevuConnection(
  id: string,
  host: string,
  service: string,
  offer?: RTCSessionDescriptionInit
)

Properties:

• id - Connection ID
• host - Host username
• service - Service FQN
• state - Connection state
• events - EventBus for state changes and messages
• ready - Promise that resolves when local description is set

Methods:

• setSignaler(signaler) - Set signaler for ICE exchange
• queueMessage(message, options) - Queue message for sending
• sendMessage(message) - Send message immediately

EventBus

Type-safe event emitter with inferred types.

Methods:

• on(event, handler) - Subscribe
• once(event, handler) - Subscribe once
• off(event, handler) - Unsubscribe
• emit(event, data) - Emit event
• clear(event?) - Clear handlers
• listenerCount(event) - Get listener count
• eventNames() - Get event names

Examples

See the demo application at https://github.com/xtr-dev/rondevu-demo for a complete working example.