@xtr-dev/rondevu-client 0.9.2 → 0.10.0

package/dist/api.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Rondevu API Client - Single class for all API endpoints
+ */
+export interface Credentials {
+    peerId: string;
+    secret: string;
+}
+export interface Keypair {
+    publicKey: string;
+    privateKey: string;
+}
+export interface OfferRequest {
+    sdp: string;
+    topics?: string[];
+    ttl?: number;
+    secret?: string;
+}
+export interface Offer {
+    id: string;
+    peerId: string;
+    sdp: string;
+    topics: string[];
+    ttl: number;
+    createdAt: number;
+    expiresAt: number;
+    answererPeerId?: string;
+}
+export interface ServiceRequest {
+    username: string;
+    serviceFqn: string;
+    sdp: string;
+    ttl?: number;
+    isPublic?: boolean;
+    metadata?: Record<string, any>;
+    signature: string;
+    message: string;
+}
+export interface Service {
+    serviceId: string;
+    uuid: string;
+    offerId: string;
+    username: string;
+    serviceFqn: string;
+    isPublic: boolean;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    expiresAt: number;
+}
+export interface IceCandidate {
+    candidate: RTCIceCandidateInit;
+    createdAt: number;
+}
+/**
+ * RondevuAPI - Complete API client for Rondevu signaling server
+ */
+export declare class RondevuAPI {
+    private baseUrl;
+    private credentials?;
+    constructor(baseUrl: string, credentials?: Credentials | undefined);
+    /**
+     * Authentication header
+     */
+    private getAuthHeader;
+    /**
+     * Generate an Ed25519 keypair for username claiming and service publishing
+     */
+    static generateKeypair(): Promise<Keypair>;
+    /**
+     * Sign a message with an Ed25519 private key
+     */
+    static signMessage(message: string, privateKeyBase64: string): Promise<string>;
+    /**
+     * Verify a signature
+     */
+    static verifySignature(message: string, signatureBase64: string, publicKeyBase64: string): Promise<boolean>;
+    /**
+     * Register a new peer and get credentials
+     */
+    register(): Promise<Credentials>;
+    /**
+     * Create one or more offers
+     */
+    createOffers(offers: OfferRequest[]): Promise<Offer[]>;
+    /**
+     * Get offer by ID
+     */
+    getOffer(offerId: string): Promise<Offer>;
+    /**
+     * Answer an offer
+     */
+    answerOffer(offerId: string, sdp: string, secret?: string): Promise<void>;
+    /**
+     * Get answer for an offer (offerer polls this)
+     */
+    getAnswer(offerId: string): Promise<{
+        sdp: string;
+    } | null>;
+    /**
+     * Search offers by topic
+     */
+    searchOffers(topic: string): Promise<Offer[]>;
+    /**
+     * Add ICE candidates to an offer
+     */
+    addIceCandidates(offerId: string, candidates: RTCIceCandidateInit[]): Promise<void>;
+    /**
+     * Get ICE candidates for an offer (with polling support)
+     */
+    getIceCandidates(offerId: string, since?: number): Promise<IceCandidate[]>;
+    /**
+     * Publish a service
+     */
+    publishService(service: ServiceRequest): Promise<Service>;
+    /**
+     * Get service by UUID
+     */
+    getService(uuid: string): Promise<Service & {
+        offerId: string;
+        sdp: string;
+    }>;
+    /**
+     * Search services by username
+     */
+    searchServicesByUsername(username: string): Promise<Service[]>;
+    /**
+     * Search services by FQN
+     */
+    searchServicesByFqn(serviceFqn: string): Promise<Service[]>;
+    /**
+     * Search services by username AND FQN
+     */
+    searchServices(username: string, serviceFqn: string): Promise<Service[]>;
+    /**
+     * Check if username is available
+     */
+    checkUsername(username: string): Promise<{
+        available: boolean;
+        owner?: string;
+    }>;
+    /**
+     * Claim a username (requires Ed25519 signature)
+     */
+    claimUsername(username: string, publicKey: string, signature: string, message: string): Promise<{
+        success: boolean;
+        username: string;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,307 @@
+/**
+ * Rondevu API Client - Single class for all API endpoints
+ */
+import * as ed25519 from '@noble/ed25519';
+// Set SHA-512 hash function for ed25519 (required in @noble/ed25519 v3+)
+ed25519.hashes.sha512Async = async (message) => {
+    return new Uint8Array(await crypto.subtle.digest('SHA-512', message));
+};
+/**
+ * Helper: Convert Uint8Array to base64 string
+ */
+function bytesToBase64(bytes) {
+    const binString = Array.from(bytes, byte => String.fromCodePoint(byte)).join('');
+    return btoa(binString);
+}
+/**
+ * Helper: Convert base64 string to Uint8Array
+ */
+function base64ToBytes(base64) {
+    const binString = atob(base64);
+    return Uint8Array.from(binString, char => char.codePointAt(0));
+}
+/**
+ * RondevuAPI - Complete API client for Rondevu signaling server
+ */
+export class RondevuAPI {
+    constructor(baseUrl, credentials) {
+        this.baseUrl = baseUrl;
+        this.credentials = credentials;
+    }
+    /**
+     * Authentication header
+     */
+    getAuthHeader() {
+        if (!this.credentials) {
+            return {};
+        }
+        return {
+            Authorization: `Bearer ${this.credentials.peerId}:${this.credentials.secret}`,
+        };
+    }
+    // ============================================
+    // Ed25519 Cryptography Helpers
+    // ============================================
+    /**
+     * Generate an Ed25519 keypair for username claiming and service publishing
+     */
+    static async generateKeypair() {
+        const privateKey = ed25519.utils.randomSecretKey();
+        const publicKey = await ed25519.getPublicKeyAsync(privateKey);
+        return {
+            publicKey: bytesToBase64(publicKey),
+            privateKey: bytesToBase64(privateKey),
+        };
+    }
+    /**
+     * Sign a message with an Ed25519 private key
+     */
+    static async signMessage(message, privateKeyBase64) {
+        const privateKey = base64ToBytes(privateKeyBase64);
+        const encoder = new TextEncoder();
+        const messageBytes = encoder.encode(message);
+        const signature = await ed25519.signAsync(messageBytes, privateKey);
+        return bytesToBase64(signature);
+    }
+    /**
+     * Verify a signature
+     */
+    static async verifySignature(message, signatureBase64, publicKeyBase64) {
+        const publicKey = base64ToBytes(publicKeyBase64);
+        const signature = base64ToBytes(signatureBase64);
+        const encoder = new TextEncoder();
+        const messageBytes = encoder.encode(message);
+        return await ed25519.verifyAsync(signature, messageBytes, publicKey);
+    }
+    // ============================================
+    // Authentication
+    // ============================================
+    /**
+     * Register a new peer and get credentials
+     */
+    async register() {
+        const response = await fetch(`${this.baseUrl}/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Registration failed: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    // ============================================
+    // Offers
+    // ============================================
+    /**
+     * Create one or more offers
+     */
+    async createOffers(offers) {
+        const response = await fetch(`${this.baseUrl}/offers`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.getAuthHeader(),
+            },
+            body: JSON.stringify({ offers }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to create offers: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Get offer by ID
+     */
+    async getOffer(offerId) {
+        const response = await fetch(`${this.baseUrl}/offers/${offerId}`, {
+            headers: this.getAuthHeader(),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to get offer: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Answer an offer
+     */
+    async answerOffer(offerId, sdp, secret) {
+        const response = await fetch(`${this.baseUrl}/offers/${offerId}/answer`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.getAuthHeader(),
+            },
+            body: JSON.stringify({ sdp, secret }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to answer offer: ${error.error || response.statusText}`);
+        }
+    }
+    /**
+     * Get answer for an offer (offerer polls this)
+     */
+    async getAnswer(offerId) {
+        const response = await fetch(`${this.baseUrl}/offers/${offerId}/answer`, {
+            headers: this.getAuthHeader(),
+        });
+        if (response.status === 404) {
+            return null; // No answer yet
+        }
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to get answer: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Search offers by topic
+     */
+    async searchOffers(topic) {
+        const response = await fetch(`${this.baseUrl}/offers?topic=${encodeURIComponent(topic)}`, {
+            headers: this.getAuthHeader(),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to search offers: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    // ============================================
+    // ICE Candidates
+    // ============================================
+    /**
+     * Add ICE candidates to an offer
+     */
+    async addIceCandidates(offerId, candidates) {
+        const response = await fetch(`${this.baseUrl}/offers/${offerId}/ice-candidates`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.getAuthHeader(),
+            },
+            body: JSON.stringify({ candidates }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to add ICE candidates: ${error.error || response.statusText}`);
+        }
+    }
+    /**
+     * Get ICE candidates for an offer (with polling support)
+     */
+    async getIceCandidates(offerId, since = 0) {
+        const response = await fetch(`${this.baseUrl}/offers/${offerId}/ice-candidates?since=${since}`, { headers: this.getAuthHeader() });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to get ICE candidates: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    // ============================================
+    // Services
+    // ============================================
+    /**
+     * Publish a service
+     */
+    async publishService(service) {
+        const response = await fetch(`${this.baseUrl}/services`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.getAuthHeader(),
+            },
+            body: JSON.stringify(service),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to publish service: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Get service by UUID
+     */
+    async getService(uuid) {
+        const response = await fetch(`${this.baseUrl}/services/${uuid}`, {
+            headers: this.getAuthHeader(),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to get service: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Search services by username
+     */
+    async searchServicesByUsername(username) {
+        const response = await fetch(`${this.baseUrl}/services?username=${encodeURIComponent(username)}`, { headers: this.getAuthHeader() });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to search services: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Search services by FQN
+     */
+    async searchServicesByFqn(serviceFqn) {
+        const response = await fetch(`${this.baseUrl}/services?serviceFqn=${encodeURIComponent(serviceFqn)}`, { headers: this.getAuthHeader() });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to search services: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Search services by username AND FQN
+     */
+    async searchServices(username, serviceFqn) {
+        const response = await fetch(`${this.baseUrl}/services?username=${encodeURIComponent(username)}&serviceFqn=${encodeURIComponent(serviceFqn)}`, { headers: this.getAuthHeader() });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to search services: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    // ============================================
+    // Usernames
+    // ============================================
+    /**
+     * Check if username is available
+     */
+    async checkUsername(username) {
+        const response = await fetch(`${this.baseUrl}/usernames/${encodeURIComponent(username)}/check`);
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to check username: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+    /**
+     * Claim a username (requires Ed25519 signature)
+     */
+    async claimUsername(username, publicKey, signature, message) {
+        const response = await fetch(`${this.baseUrl}/usernames/${encodeURIComponent(username)}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.getAuthHeader(),
+            },
+            body: JSON.stringify({
+                publicKey,
+                signature,
+                message,
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Unknown error' }));
+            throw new Error(`Failed to claim username: ${error.error || response.statusText}`);
+        }
+        return await response.json();
+    }
+}

package/dist/bin.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Binnable - A cleanup function that can be synchronous or asynchronous
+ *
+ * Used to unsubscribe from events, close connections, or perform other cleanup operations.
+ */
+export type Binnable = () => void | Promise<void>;
+/**
+ * Create a cleanup function collector (garbage bin)
+ *
+ * Collects cleanup functions and provides a single `clean()` method to execute all of them.
+ * Useful for managing multiple cleanup operations in a single place.
+ *
+ * @returns A function that accepts cleanup functions and has a `clean()` method
+ *
+ * @example
+ * ```typescript
+ * const bin = createBin();
+ *
+ * // Add cleanup functions
+ * bin(
+ *   () => console.log('Cleanup 1'),
+ *   () => connection.close(),
+ *   () => clearInterval(timer)
+ * );
+ *
+ * // Later, clean everything
+ * bin.clean(); // Executes all cleanup functions
+ * ```
+ */
+export declare const createBin: () => ((...rubbish: Binnable[]) => number) & {
+    /**
+     * Execute all cleanup functions and clear the bin
+     */
+    clean: () => void;
+};

package/dist/bin.js

@@ -0,0 +1,35 @@
+/**
+ * Create a cleanup function collector (garbage bin)
+ *
+ * Collects cleanup functions and provides a single `clean()` method to execute all of them.
+ * Useful for managing multiple cleanup operations in a single place.
+ *
+ * @returns A function that accepts cleanup functions and has a `clean()` method
+ *
+ * @example
+ * ```typescript
+ * const bin = createBin();
+ *
+ * // Add cleanup functions
+ * bin(
+ *   () => console.log('Cleanup 1'),
+ *   () => connection.close(),
+ *   () => clearInterval(timer)
+ * );
+ *
+ * // Later, clean everything
+ * bin.clean(); // Executes all cleanup functions
+ * ```
+ */
+export const createBin = () => {
+    const bin = [];
+    return Object.assign((...rubbish) => bin.push(...rubbish), {
+        /**
+         * Execute all cleanup functions and clear the bin
+         */
+        clean: () => {
+            bin.forEach(binnable => binnable());
+            bin.length = 0;
+        },
+    });
+};

package/dist/connection-manager.d.ts

@@ -0,0 +1,104 @@
+import { WebRTCRondevuConnection } from './connection.js';
+import { Credentials } from './api.js';
+import { ConnectionInterface } from './types.js';
+export interface ConnectionManagerOptions {
+    apiUrl: string;
+    username: string;
+    credentials?: Credentials;
+    autoReconnect?: boolean;
+    reconnectDelay?: number;
+    maxReconnectAttempts?: number;
+}
+export interface HostServiceOptions {
+    service: string;
+    ttl?: number;
+    onConnection?: (connection: ConnectionInterface) => void;
+}
+export interface ConnectToServiceOptions {
+    username: string;
+    service: string;
+    onConnection?: (connection: ConnectionInterface) => void;
+}
+/**
+ * ConnectionManager - High-level connection management
+ *
+ * @example
+ * // Host a service
+ * const manager = new ConnectionManager({
+ *   apiUrl: 'https://api.ronde.vu',
+ *   credentials: await api.register()
+ * })
+ *
+ * await manager.hostService({
+ *   service: 'chat.app@1.0.0',
+ *   onConnection: (conn) => {
+ *     conn.events.on('message', msg => console.log('Received:', msg))
+ *   }
+ * })
+ *
+ * @example
+ * // Connect to a service
+ * const connection = await manager.connectToService({
+ *   username: 'alice',
+ *   service: 'chat.app@1.0.0'
+ * })
+ *
+ * await connection.sendMessage('Hello!')
+ */
+export declare class ConnectionManager {
+    private readonly api;
+    private readonly username;
+    private readonly connections;
+    private readonly autoReconnect;
+    private readonly reconnectDelay;
+    private readonly maxReconnectAttempts;
+    private readonly bin;
+    constructor(options: ConnectionManagerOptions);
+    /**
+     * Host a service - Creates an offer and publishes it to the signaling server
+     *
+     * The service will automatically accept incoming connections and manage them.
+     * Each new connection triggers the onConnection callback.
+     *
+     * @param options - Service hosting options
+     * @returns Promise that resolves when the service is published
+     */
+    hostService(options: HostServiceOptions): Promise<void>;
+    /**
+     * Connect to a hosted service
+     *
+     * Searches for the service, retrieves the offer, and creates an answering connection.
+     *
+     * @param options - Connection options
+     * @returns The established connection
+     */
+    connectToService(options: ConnectToServiceOptions): Promise<WebRTCRondevuConnection>;
+    /**
+     * Get a connection by ID
+     */
+    getConnection(id: string): WebRTCRondevuConnection | undefined;
+    /**
+     * Get all managed connections
+     */
+    getAllConnections(): WebRTCRondevuConnection[];
+    /**
+     * Remove a connection
+     */
+    private removeConnection;
+    /**
+     * Schedule reconnection for a failed connection
+     */
+    private scheduleReconnect;
+    /**
+     * Attempt to reconnect a failed connection
+     */
+    private attemptReconnect;
+    /**
+     * Create a temporary signaler (used during initial offer creation)
+     */
+    private createTempSignaler;
+    /**
+     * Clean up all connections and resources
+     */
+    destroy(): void;
+}