@xtr-dev/rondevu-client 0.13.0 → 0.17.0

package/dist/rondevu.d.ts

@@ -1,22 +1,47 @@
-import { RondevuAPI, Credentials, Keypair, Service, IceCandidate } from './api.js';
+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;
+    username?: string;
     keypair?: Keypair;
-    credentials?: Credentials;
+    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 {
-    serviceFqn: string;
-    offers: Array<{
-        sdp: string;
-    }>;
+    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:
- * - Username claiming with Ed25519 signatures
+ * - 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)
@@ -24,55 +49,173 @@ export interface PublishServiceOptions {
  *
  * @example
  * ```typescript
- * // Initialize (generates keypair automatically)
- * const rondevu = new Rondevu({
+ * // 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'
  * })
  *
- * await rondevu.initialize()
- *
- * // Claim username (one time)
- * await rondevu.claimUsername()
+ * // 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
- * const publishedService = await rondevu.publishService({
- *   serviceFqn: 'chat:1.0.0@alice',
- *   offers: [{ sdp: offerSdp }],
- *   ttl: 300000,
+ * // 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 }
+ *   }
  * })
  *
- * // Discover a service
- * const service = await rondevu.getService('chat:1.0.0@bob')
+ * // Start accepting connections (auto-fills offers and polls)
+ * await rondevu.startFilling()
  *
- * // Post answer
- * await rondevu.postOfferAnswer(service.serviceFqn, service.offerId, answerSdp)
+ * // 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 readonly api;
-    private readonly username;
+    private static readonly DEFAULT_TTL_MS;
+    private static readonly POLLING_INTERVAL_MS;
+    private api;
+    private readonly apiUrl;
+    private username;
     private keypair;
     private usernameClaimed;
-    constructor(options: RondevuOptions);
+    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;
     /**
-     * Initialize the service - generates keypair if not provided
-     * Call this before using other methods
+     * Create and initialize a Rondevu client
+     *
+     * @example
+     * ```typescript
+     * const rondevu = await Rondevu.connect({
+     *   apiUrl: 'https://api.ronde.vu',
+     *   username: 'alice'
+     * })
+     * ```
      */
-    initialize(): Promise<void>;
+    static connect(options: RondevuOptions): Promise<Rondevu>;
     /**
-     * Claim the username with Ed25519 signature
-     * Should be called once before publishing services
+     * Generate an anonymous username with timestamp and random component
      */
-    claimUsername(): Promise<void>;
+    private static generateAnonymousUsername;
     /**
      * Check if username has been claimed (checks with server)
      */
     isUsernameClaimed(): Promise<boolean>;
     /**
-     * Publish a service with automatic signature generation
+     * 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)
+     *   }
+     * })
+     * ```
      */
-    publishService(options: PublishServiceOptions): Promise<Service>;
+    connectToService(options: ConnectToServiceOptions): Promise<ConnectionContext>;
     /**
      * Get service by FQN (with username) - Direct lookup
      * Example: chat:1.0.0@alice
@@ -133,6 +276,25 @@ export declare class Rondevu {
         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
      */
@@ -150,7 +312,7 @@ export declare class Rondevu {
     /**
      * Get the current keypair (for backup/storage)
      */
-    getKeypair(): Keypair | null;
+    getKeypair(): Keypair;
     /**
      * Get the username
      */
@@ -158,10 +320,10 @@ export declare class Rondevu {
     /**
      * Get the public key
      */
-    getPublicKey(): string | null;
+    getPublicKey(): string;
     /**
      * Access to underlying API for advanced operations
      * @deprecated Use direct methods on Rondevu instance instead
      */
-    getAPI(): RondevuAPI;
+    getAPIPublic(): RondevuAPI;
 }