@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/dist/rondevu.d.ts

@@ -1,407 +0,0 @@
-import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from './api.js';
-import { CryptoAdapter } from './crypto-adapter.js';
-import { EventEmitter } from 'eventemitter3';
-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;
-    rtcPeerConnection?: typeof RTCPeerConnection;
-    rtcIceCandidate?: typeof RTCIceCandidate;
-}
-export interface OfferContext {
-    dc?: RTCDataChannel;
-    offer: RTCSessionDescriptionInit;
-}
-/**
- * Factory function for creating WebRTC offers.
- * Rondevu creates the RTCPeerConnection and passes it to the factory,
- * allowing ICE candidate handlers to be set up before setLocalDescription() is called.
- *
- * @param pc - The RTCPeerConnection created by Rondevu (already configured with ICE servers)
- * @returns Promise containing the data channel (optional) and offer SDP
- */
-export type OfferFactory = (pc: RTCPeerConnection) => 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;
-}
-export interface ActiveOffer {
-    offerId: string;
-    serviceFqn: string;
-    pc: RTCPeerConnection;
-    dc?: RTCDataChannel;
-    answered: boolean;
-    createdAt: number;
-}
-export interface FindServiceOptions {
-    mode?: 'direct' | 'random' | 'paginated';
-    limit?: number;
-    offset?: number;
-}
-export interface ServiceResult {
-    serviceId: string;
-    username: string;
-    serviceFqn: string;
-    offerId: string;
-    sdp: string;
-    createdAt: number;
-    expiresAt: number;
-}
-export interface PaginatedServiceResult {
-    services: ServiceResult[];
-    count: number;
-    limit: number;
-    offset: number;
-}
-/**
- * Base error class for Rondevu errors
- */
-export declare class RondevuError extends Error {
-    context?: Record<string, any> | undefined;
-    constructor(message: string, context?: Record<string, any> | undefined);
-}
-/**
- * Network-related errors (API calls, connectivity)
- */
-export declare class NetworkError extends RondevuError {
-    constructor(message: string, context?: Record<string, any>);
-}
-/**
- * Validation errors (invalid input, malformed data)
- */
-export declare class ValidationError extends RondevuError {
-    constructor(message: string, context?: Record<string, any>);
-}
-/**
- * WebRTC connection errors (peer connection failures, ICE issues)
- */
-export declare class ConnectionError extends RondevuError {
-    constructor(message: string, context?: Record<string, any>);
-}
-/**
- * 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 (pc) => {
- *     // pc is created by Rondevu with ICE handlers already attached
- *     const dc = pc.createDataChannel('chat')
- *     const offer = await pc.createOffer()
- *     await pc.setLocalDescription(offer)
- *     return { 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 extends EventEmitter {
-    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 rtcPeerConnection?;
-    private rtcIceCandidate?;
-    private currentService;
-    private maxOffers;
-    private offerFactory;
-    private ttl;
-    private activeOffers;
-    private filling;
-    private pollingInterval;
-    private lastPollTimestamp;
-    private isPolling;
-    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
-     * The RTCPeerConnection is created by Rondevu and passed in
-     */
-    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
-     *
-     * Note: This is used by connectToService() where the offerId is already known.
-     * For createOffer(), we use inline ICE handling with early candidate queuing
-     * since the offerId isn't available until after the factory completes.
-     */
-    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;
-    /**
-     * Get the count of active offers
-     * @returns Number of active offers
-     */
-    getOfferCount(): number;
-    /**
-     * Check if an offer is currently connected
-     * @param offerId - The offer ID to check
-     * @returns True if the offer exists and has been answered
-     */
-    isConnected(offerId: string): boolean;
-    /**
-     * Disconnect all active offers
-     * Similar to stopFilling() but doesn't stop the polling/filling process
-     */
-    disconnectAll(): Promise<void>;
-    /**
-     * Get the current service status
-     * @returns Object with service state information
-     */
-    getServiceStatus(): {
-        active: boolean;
-        offerCount: number;
-        maxOffers: number;
-        filling: boolean;
-    };
-    /**
-     * 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>;
-    /**
-     * Find a service - unified discovery method
-     *
-     * Replaces getService(), discoverService(), and discoverServices() with a single method.
-     *
-     * @param serviceFqn - Service identifier (e.g., 'chat:1.0.0' or 'chat:1.0.0@alice')
-     * @param options - Discovery options
-     *
-     * @example
-     * ```typescript
-     * // Direct lookup (has username)
-     * const service = await rondevu.findService('chat:1.0.0@alice')
-     *
-     * // Random discovery (no username)
-     * const service = await rondevu.findService('chat:1.0.0')
-     *
-     * // Paginated discovery
-     * const result = await rondevu.findService('chat:1.0.0', {
-     *   mode: 'paginated',
-     *   limit: 20,
-     *   offset: 0
-     * })
-     * ```
-     */
-    findService(serviceFqn: string, options?: FindServiceOptions): Promise<ServiceResult | PaginatedServiceResult>;
-    /**
-     * 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;
-}