@xtr-dev/rondevu-client 0.12.4 → 0.17.0

package/dist/rondevu.d.ts

@@ -0,0 +1,329 @@
+import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from './api.js';
+import { CryptoAdapter } from './crypto-adapter.js';
+export type IceServerPreset = 'ipv4-turn' | 'hostname-turns' | 'google-stun' | 'relay-only';
+export declare const ICE_SERVER_PRESETS: Record<IceServerPreset, RTCIceServer[]>;
+export interface RondevuOptions {
+    apiUrl: string;
+    username?: string;
+    keypair?: Keypair;
+    cryptoAdapter?: CryptoAdapter;
+    batching?: BatcherOptions | false;
+    iceServers?: IceServerPreset | RTCIceServer[];
+    debug?: boolean;
+}
+export interface OfferContext {
+    pc: RTCPeerConnection;
+    dc?: RTCDataChannel;
+    offer: RTCSessionDescriptionInit;
+}
+export type OfferFactory = (rtcConfig: RTCConfiguration) => Promise<OfferContext>;
+export interface PublishServiceOptions {
+    service: string;
+    maxOffers: number;
+    offerFactory?: OfferFactory;
+    ttl?: number;
+}
+export interface ConnectionContext {
+    pc: RTCPeerConnection;
+    dc: RTCDataChannel;
+    serviceFqn: string;
+    offerId: string;
+    peerUsername: string;
+}
+export interface ConnectToServiceOptions {
+    serviceFqn?: string;
+    service?: string;
+    username?: string;
+    onConnection?: (context: ConnectionContext) => void | Promise<void>;
+    rtcConfig?: RTCConfiguration;
+}
+/**
+ * Rondevu - Complete WebRTC signaling client
+ *
+ * Provides a unified API for:
+ * - Implicit username claiming (auto-claimed on first authenticated request)
+ * - Service publishing with automatic signature generation
+ * - Service discovery (direct, random, paginated)
+ * - WebRTC signaling (offer/answer exchange, ICE relay)
+ * - Keypair management
+ *
+ * @example
+ * ```typescript
+ * // Create and initialize Rondevu instance with preset ICE servers
+ * const rondevu = await Rondevu.connect({
+ *   apiUrl: 'https://signal.example.com',
+ *   username: 'alice',
+ *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
+ * })
+ *
+ * // Or use custom ICE servers
+ * const rondevu2 = await Rondevu.connect({
+ *   apiUrl: 'https://signal.example.com',
+ *   username: 'bob',
+ *   iceServers: [
+ *     { urls: 'stun:stun.l.google.com:19302' },
+ *     { urls: 'turn:turn.example.com:3478', username: 'user', credential: 'pass' }
+ *   ]
+ * })
+ *
+ * // Publish a service with automatic offer management
+ * await rondevu.publishService({
+ *   service: 'chat:2.0.0',
+ *   maxOffers: 5,  // Maintain up to 5 concurrent offers
+ *   offerFactory: async (rtcConfig) => {
+ *     const pc = new RTCPeerConnection(rtcConfig)
+ *     const dc = pc.createDataChannel('chat')
+ *     const offer = await pc.createOffer()
+ *     await pc.setLocalDescription(offer)
+ *     return { pc, dc, offer }
+ *   }
+ * })
+ *
+ * // Start accepting connections (auto-fills offers and polls)
+ * await rondevu.startFilling()
+ *
+ * // Access active connections
+ * for (const offer of rondevu.getActiveOffers()) {
+ *   offer.dc?.addEventListener('message', (e) => console.log(e.data))
+ * }
+ *
+ * // Stop when done
+ * rondevu.stopFilling()
+ * ```
+ */
+export declare class Rondevu {
+    private static readonly DEFAULT_TTL_MS;
+    private static readonly POLLING_INTERVAL_MS;
+    private api;
+    private readonly apiUrl;
+    private username;
+    private keypair;
+    private usernameClaimed;
+    private cryptoAdapter?;
+    private batchingOptions?;
+    private iceServers;
+    private debugEnabled;
+    private currentService;
+    private maxOffers;
+    private offerFactory;
+    private ttl;
+    private activeOffers;
+    private filling;
+    private pollingInterval;
+    private lastPollTimestamp;
+    private constructor();
+    /**
+     * Internal debug logging - only logs if debug mode is enabled
+     */
+    private debug;
+    /**
+     * Create and initialize a Rondevu client
+     *
+     * @example
+     * ```typescript
+     * const rondevu = await Rondevu.connect({
+     *   apiUrl: 'https://api.ronde.vu',
+     *   username: 'alice'
+     * })
+     * ```
+     */
+    static connect(options: RondevuOptions): Promise<Rondevu>;
+    /**
+     * Generate an anonymous username with timestamp and random component
+     */
+    private static generateAnonymousUsername;
+    /**
+     * Check if username has been claimed (checks with server)
+     */
+    isUsernameClaimed(): Promise<boolean>;
+    /**
+     * Default offer factory - creates a simple data channel connection
+     */
+    private defaultOfferFactory;
+    /**
+     * Publish a service with automatic offer management
+     * Call startFilling() to begin accepting connections
+     *
+     * @example
+     * ```typescript
+     * await rondevu.publishService({
+     *   service: 'chat:2.0.0',
+     *   maxOffers: 5
+     * })
+     * await rondevu.startFilling()
+     * ```
+     */
+    publishService(options: PublishServiceOptions): Promise<void>;
+    /**
+     * Set up ICE candidate handler to send candidates to the server
+     */
+    private setupIceCandidateHandler;
+    /**
+     * Create a single offer and publish it to the server
+     */
+    private createOffer;
+    /**
+     * Fill offers to reach maxOffers count
+     */
+    private fillOffers;
+    /**
+     * Poll for answers and ICE candidates (internal use for automatic offer management)
+     */
+    private pollInternal;
+    /**
+     * Start filling offers and polling for answers/ICE
+     * Call this after publishService() to begin accepting connections
+     */
+    startFilling(): Promise<void>;
+    /**
+     * Stop filling offers and polling
+     * Closes all active peer connections
+     */
+    stopFilling(): void;
+    /**
+     * Resolve the full service FQN from various input options
+     * Supports direct FQN, service+username, or service discovery
+     */
+    private resolveServiceFqn;
+    /**
+     * Start polling for remote ICE candidates
+     * Returns the polling interval ID
+     */
+    private startIcePolling;
+    /**
+     * Automatically connect to a service (answerer side)
+     * Handles the entire connection flow: discovery, WebRTC setup, answer exchange, ICE candidates
+     *
+     * @example
+     * ```typescript
+     * // Connect to specific user
+     * const connection = await rondevu.connectToService({
+     *   serviceFqn: 'chat:2.0.0@alice',
+     *   onConnection: ({ dc, peerUsername }) => {
+     *     console.log('Connected to', peerUsername)
+     *     dc.addEventListener('message', (e) => console.log(e.data))
+     *     dc.addEventListener('open', () => dc.send('Hello!'))
+     *   }
+     * })
+     *
+     * // Discover random service
+     * const connection = await rondevu.connectToService({
+     *   service: 'chat:2.0.0',
+     *   onConnection: ({ dc, peerUsername }) => {
+     *     console.log('Connected to', peerUsername)
+     *   }
+     * })
+     * ```
+     */
+    connectToService(options: ConnectToServiceOptions): Promise<ConnectionContext>;
+    /**
+     * Get service by FQN (with username) - Direct lookup
+     * Example: chat:1.0.0@alice
+     */
+    getService(serviceFqn: string): Promise<{
+        serviceId: string;
+        username: string;
+        serviceFqn: string;
+        offerId: string;
+        sdp: string;
+        createdAt: number;
+        expiresAt: number;
+    }>;
+    /**
+     * Discover a random available service without knowing the username
+     * Example: chat:1.0.0 (without @username)
+     */
+    discoverService(serviceVersion: string): Promise<{
+        serviceId: string;
+        username: string;
+        serviceFqn: string;
+        offerId: string;
+        sdp: string;
+        createdAt: number;
+        expiresAt: number;
+    }>;
+    /**
+     * Discover multiple available services with pagination
+     * Example: chat:1.0.0 (without @username)
+     */
+    discoverServices(serviceVersion: string, limit?: number, offset?: number): Promise<{
+        services: Array<{
+            serviceId: string;
+            username: string;
+            serviceFqn: string;
+            offerId: string;
+            sdp: string;
+            createdAt: number;
+            expiresAt: number;
+        }>;
+        count: number;
+        limit: number;
+        offset: number;
+    }>;
+    /**
+     * Post answer SDP to specific offer
+     */
+    postOfferAnswer(serviceFqn: string, offerId: string, sdp: string): Promise<{
+        success: boolean;
+        offerId: string;
+    }>;
+    /**
+     * Get answer SDP (offerer polls this)
+     */
+    getOfferAnswer(serviceFqn: string, offerId: string): Promise<{
+        sdp: string;
+        offerId: string;
+        answererId: string;
+        answeredAt: number;
+    } | null>;
+    /**
+     * Combined polling for answers and ICE candidates
+     * Returns all answered offers and ICE candidates for all peer's offers since timestamp
+     */
+    poll(since?: number): Promise<{
+        answers: Array<{
+            offerId: string;
+            serviceId?: string;
+            answererId: string;
+            sdp: string;
+            answeredAt: number;
+        }>;
+        iceCandidates: Record<string, Array<{
+            candidate: RTCIceCandidateInit | null;
+            role: 'offerer' | 'answerer';
+            peerId: string;
+            createdAt: number;
+        }>>;
+    }>;
+    /**
+     * Add ICE candidates to specific offer
+     */
+    addOfferIceCandidates(serviceFqn: string, offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
+        count: number;
+        offerId: string;
+    }>;
+    /**
+     * Get ICE candidates for specific offer (with polling support)
+     */
+    getOfferIceCandidates(serviceFqn: string, offerId: string, since?: number): Promise<{
+        candidates: IceCandidate[];
+        offerId: string;
+    }>;
+    /**
+     * Get the current keypair (for backup/storage)
+     */
+    getKeypair(): Keypair;
+    /**
+     * Get the username
+     */
+    getUsername(): string;
+    /**
+     * Get the public key
+     */
+    getPublicKey(): string;
+    /**
+     * Access to underlying API for advanced operations
+     * @deprecated Use direct methods on Rondevu instance instead
+     */
+    getAPIPublic(): RondevuAPI;
+}