@xtr-dev/rondevu-client 0.18.10 → 0.21.1

package/dist/core/rondevu.d.ts

@@ -0,0 +1,296 @@
+import { Credential, IceCandidate } from '../api/client.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
+import { EventEmitter } from 'eventemitter3';
+import { OffererConnection } from '../connections/offerer.js';
+import { Peer, PeerOptions } from './peer.js';
+import type { RondevuOptions, OfferOptions, OfferHandle, DiscoverOptions, DiscoverResult } from './rondevu-types.js';
+export type { RondevuOptions, OfferContext, OfferFactory, OfferOptions, OfferHandle, ConnectionContext, DiscoverOptions, DiscoveredOffer, DiscoverResult, } from './rondevu-types.js';
+export { ICE_SERVER_PRESETS } from './ice-config.js';
+export type { IceServerPreset, IcePresetConfig } from './ice-config.js';
+export type { PollAnswerEvent, PollIceEvent } from './polling-manager.js';
+/**
+ * Rondevu - Complete WebRTC signaling client with durable connections
+ *
+ * Uses a tags-based discovery system where offers have 1+ tags for matching.
+ *
+ * @example
+ * ```typescript
+ * // Create and initialize Rondevu instance with preset ICE servers
+ * const rondevu = await Rondevu.connect({
+ *   apiUrl: 'https://signal.example.com',
+ *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
+ * })
+ *
+ * // Create offers with tags for discovery
+ * await rondevu.offer({
+ *   tags: ['chat', 'video'],
+ *   maxOffers: 5  // Maintain up to 5 concurrent offers
+ * })
+ *
+ * // Start accepting connections (auto-fills offers and polls)
+ * await rondevu.startFilling()
+ *
+ * // Listen for connections
+ * rondevu.on('connection:opened', (offerId, connection) => {
+ *   connection.on('connected', () => console.log('Connected!'))
+ *   connection.on('message', (data) => console.log('Received:', data))
+ *   connection.send('Hello!')
+ * })
+ *
+ * // Connect by discovering offers with matching tags
+ * const connection = await rondevu.connect({
+ *   tags: ['chat']
+ * })
+ *
+ * connection.on('connected', () => {
+ *   console.log('Connected!')
+ *   connection.send('Hello!')
+ * })
+ *
+ * connection.on('message', (data) => {
+ *   console.log('Received:', data)
+ * })
+ *
+ * connection.on('reconnecting', (attempt) => {
+ *   console.log(`Reconnecting, attempt ${attempt}`)
+ * })
+ * ```
+ */
+export declare class Rondevu extends EventEmitter {
+    private static readonly DEFAULT_API_URL;
+    private static readonly DEFAULT_TTL_MS;
+    private static readonly POLLING_INTERVAL_MS;
+    private api;
+    private readonly apiUrl;
+    private credential;
+    private cryptoAdapter?;
+    private webrtcAdapter;
+    private iceServers;
+    private iceTransportPolicy?;
+    private debugEnabled;
+    private currentTags;
+    private connectionConfig?;
+    private offerPool;
+    private pollingManager;
+    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({})  // Uses default API URL
+     * // or
+     * const rondevu = await Rondevu.connect({
+     *   apiUrl: 'https://custom.api.com'
+     * })
+     * ```
+     */
+    static connect(options?: RondevuOptions): Promise<Rondevu>;
+    /**
+     * Get the current credential name
+     */
+    getName(): string;
+    /**
+     * Get the full credential (name + secret)
+     * Use this to persist credentials for future sessions
+     *
+     * ⚠️ SECURITY WARNING:
+     * - The secret grants full access to this identity
+     * - Store credentials securely (encrypted storage, never in logs)
+     * - Never expose credentials in URLs, console output, or error messages
+     * - Treat the secret like a password or API key
+     */
+    getCredential(): Credential;
+    /**
+     * Get the WebRTC adapter for creating peer connections
+     * Used internally by offer pool and connections
+     */
+    getWebRTCAdapter(): WebRTCAdapter;
+    /**
+     * Default offer factory - creates a simple data channel connection
+     * The RTCPeerConnection is created by Rondevu and passed in
+     */
+    private defaultOfferFactory;
+    /**
+     * Create offers with tags for discovery (offerer/host side)
+     * Auto-starts filling by default. Use the returned object to cancel.
+     *
+     * @example
+     * ```typescript
+     * // Auto-start (default)
+     * const offer = await rondevu.offer({
+     *   tags: ['chat', 'video'],
+     *   maxOffers: 5
+     * })
+     * // Later: offer.cancel() to stop
+     *
+     * // Manual start
+     * await rondevu.offer({ tags: ['chat'], maxOffers: 5, autoStart: false })
+     * await rondevu.startFilling()
+     * ```
+     */
+    offer(options: OfferOptions): Promise<OfferHandle>;
+    /**
+     * Start filling offers and polling for answers/ICE
+     * Call this after offer() to begin accepting connections
+     */
+    startFilling(): Promise<void>;
+    /**
+     * Stop filling offers and polling
+     * Closes all active peer connections
+     */
+    stopFilling(): void;
+    /**
+     * Start the centralized polling manager
+     * Use this when you need polling without offers (e.g., answerer connections)
+     */
+    startPolling(): void;
+    /**
+     * Stop the centralized polling manager
+     */
+    stopPolling(): void;
+    /**
+     * Check if polling is active
+     */
+    isPolling(): boolean;
+    /**
+     * 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 is connected
+     */
+    isConnected(offerId: string): boolean;
+    /**
+     * Disconnect all active offers
+     * Similar to stopFilling() but doesn't stop the polling/filling process
+     */
+    disconnectAll(): void;
+    /**
+     * Get the current publishing status
+     * @returns Object with publishing state information
+     */
+    getPublishStatus(): {
+        active: boolean;
+        offerCount: number;
+        tags: string[] | null;
+    };
+    /**
+     * Create a peer connection with simplified DX
+     * Returns a Peer object with clean state management and events
+     *
+     * @example
+     * ```typescript
+     * // Connect to any peer matching tags
+     * const peer = await rondevu.peer({ tags: ['chat'] })
+     *
+     * // Connect to specific user
+     * const peer = await rondevu.peer({
+     *   username: 'alice',
+     *   tags: ['chat']
+     * })
+     *
+     * peer.on('open', () => {
+     *   console.log('Connected to', peer.peerUsername)
+     *   peer.send('Hello!')
+     * })
+     *
+     * peer.on('message', (data) => {
+     *   console.log('Received:', data)
+     * })
+     *
+     * peer.on('state', (state, prevState) => {
+     *   console.log(`State: ${prevState} → ${state}`)
+     * })
+     *
+     * // Access underlying RTCPeerConnection
+     * if (peer.peerConnection) {
+     *   console.log('ICE state:', peer.peerConnection.iceConnectionState)
+     * }
+     * ```
+     */
+    peer(options: PeerOptions): Promise<Peer>;
+    /**
+     * Discover offers by tags
+     *
+     * @param tags - Tags to search for (OR logic - matches any tag)
+     * @param options - Discovery options (pagination)
+     *
+     * @example
+     * ```typescript
+     * // Discover offers matching any of the tags
+     * const result = await rondevu.discover(['chat', 'video'])
+     *
+     * // Paginated discovery
+     * const result = await rondevu.discover(['chat'], {
+     *   limit: 20,
+     *   offset: 0
+     * })
+     *
+     * // Access offers
+     * for (const offer of result.offers) {
+     *   console.log(offer.username, offer.tags)
+     * }
+     * ```
+     */
+    discover(tags: string[], options?: DiscoverOptions): Promise<DiscoverResult>;
+    /**
+     * Post answer SDP to specific offer
+     */
+    postOfferAnswer(offerId: string, sdp: string): Promise<{
+        success: boolean;
+        offerId: string;
+    }>;
+    /**
+     * Get answer SDP (offerer polls this)
+     */
+    getOfferAnswer(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;
+            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(offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
+        count: number;
+        offerId: string;
+    }>;
+    /**
+     * Get ICE candidates for specific offer (with polling support)
+     */
+    getOfferIceCandidates(offerId: string, since?: number): Promise<{
+        candidates: IceCandidate[];
+        offerId: string;
+    }>;
+    /**
+     * Get active connections (for offerer side)
+     */
+    getActiveConnections(): Map<string, OffererConnection>;
+}