@xtr-dev/rondevu-client 0.20.1 → 0.21.1

package/dist/core/rondevu.d.ts

@@ -1,146 +1,45 @@
-import { RondevuAPI, Keypair, IceCandidate, BatcherOptions } from '../api/client.js';
-import { CryptoAdapter } from '../crypto/adapter.js';
+import { Credential, IceCandidate } from '../api/client.js';
+import { WebRTCAdapter } from '../webrtc/adapter.js';
 import { EventEmitter } from 'eventemitter3';
 import { OffererConnection } from '../connections/offerer.js';
-import { AnswererConnection } from '../connections/answerer.js';
-import { ConnectionConfig } from '../connections/config.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;
-    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;
-    connectionConfig?: Partial<ConnectionConfig>;
-}
-export interface ConnectionContext {
-    pc: RTCPeerConnection;
-    dc: RTCDataChannel;
-    serviceFqn: string;
-    offerId: string;
-    peerUsername: string;
-}
-export interface ConnectToServiceOptions {
-    serviceFqn?: string;
-    service?: string;
-    username?: string;
-    rtcConfig?: RTCConfiguration;
-    connectionConfig?: Partial<ConnectionConfig>;
-}
-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>);
-}
+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
  *
- * v1.0.0 introduces breaking changes:
- * - connectToService() now returns AnswererConnection instead of ConnectionContext
- * - Automatic reconnection and message buffering built-in
- * - Connection objects expose .send() method instead of raw DataChannel
- * - Rich event system for connection lifecycle (connected, disconnected, reconnecting, etc.)
+ * 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',
- *   username: 'alice',
  *   iceServers: 'ipv4-turn'  // Use preset: 'ipv4-turn', 'hostname-turns', 'google-stun', or 'relay-only'
  * })
  *
- * // Publish a service with automatic offer management
- * await rondevu.publishService({
- *   service: 'chat:2.0.0',
+ * // 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 (v1.0.0 API)
+ * // 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 to a service (v1.0.0 - returns AnswererConnection)
- * const connection = await rondevu.connectToService({
- *   serviceFqn: 'chat:2.0.0@bob'
+ * // Connect by discovering offers with matching tags
+ * const connection = await rondevu.connect({
+ *   tags: ['chat']
  * })
  *
  * connection.on('connected', () => {
@@ -158,22 +57,21 @@ export declare class ConnectionError extends RondevuError {
  * ```
  */
 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 username;
-    private keypair;
-    private usernameClaimed;
+    private credential;
     private cryptoAdapter?;
-    private batchingOptions?;
+    private webrtcAdapter;
     private iceServers;
+    private iceTransportPolicy?;
     private debugEnabled;
-    private rtcPeerConnection?;
-    private rtcIceCandidate?;
-    private currentService;
+    private currentTags;
     private connectionConfig?;
     private offerPool;
+    private pollingManager;
     private constructor();
     /**
      * Internal debug logging - only logs if debug mode is enabled
@@ -184,47 +82,61 @@ export declare class Rondevu extends EventEmitter {
      *
      * @example
      * ```typescript
+     * const rondevu = await Rondevu.connect({})  // Uses default API URL
+     * // or
      * const rondevu = await Rondevu.connect({
-     *   apiUrl: 'https://api.ronde.vu',
-     *   username: 'alice'
+     *   apiUrl: 'https://custom.api.com'
      * })
      * ```
      */
-    static connect(options: RondevuOptions): Promise<Rondevu>;
+    static connect(options?: RondevuOptions): Promise<Rondevu>;
     /**
-     * Generate an anonymous username with timestamp and random component
+     * Get the current credential name
      */
-    private static generateAnonymousUsername;
+    getName(): string;
     /**
-     * Check if username has been claimed (checks with server)
+     * 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
      */
-    isUsernameClaimed(): Promise<boolean>;
+    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;
     /**
-     * Publish a service with automatic offer management
-     * Call startFilling() to begin accepting connections
+     * Create offers with tags for discovery (offerer/host side)
+     * Auto-starts filling by default. Use the returned object to cancel.
      *
      * @example
      * ```typescript
-     * await rondevu.publishService({
-     *   service: 'chat:2.0.0',
-     *   maxOffers: 5,
-     *   connectionConfig: {
-     *     reconnectEnabled: true,
-     *     bufferEnabled: true
-     *   }
+     * // 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()
      * ```
      */
-    publishService(options: PublishServiceOptions): Promise<void>;
+    offer(options: OfferOptions): Promise<OfferHandle>;
     /**
      * Start filling offers and polling for answers/ICE
-     * Call this after publishService() to begin accepting connections
+     * Call this after offer() to begin accepting connections
      */
     startFilling(): Promise<void>;
     /**
@@ -232,6 +144,19 @@ export declare class Rondevu extends EventEmitter {
      * 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
@@ -249,89 +174,84 @@ export declare class Rondevu extends EventEmitter {
      */
     disconnectAll(): void;
     /**
-     * Get the current service status
-     * @returns Object with service state information
+     * Get the current publishing status
+     * @returns Object with publishing state information
      */
-    getServiceStatus(): {
+    getPublishStatus(): {
         active: boolean;
         offerCount: number;
+        tags: string[] | null;
     };
     /**
-     * Resolve the full service FQN from various input options
-     * Supports direct FQN, service+username, or service discovery
-     */
-    private resolveServiceFqn;
-    /**
-     * Connect to a service (answerer side) - v1.0.0 API
-     * Returns an AnswererConnection with automatic reconnection and buffering
-     *
-     * BREAKING CHANGE: This now returns AnswererConnection instead of ConnectionContext
+     * 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 connection = await rondevu.connectToService({
-     *   serviceFqn: 'chat:2.0.0@alice',
-     *   connectionConfig: {
-     *     reconnectEnabled: true,
-     *     bufferEnabled: true
-     *   }
+     * const peer = await rondevu.peer({
+     *   username: 'alice',
+     *   tags: ['chat']
      * })
      *
-     * connection.on('connected', () => {
-     *   console.log('Connected!')
-     *   connection.send('Hello!')
+     * peer.on('open', () => {
+     *   console.log('Connected to', peer.peerUsername)
+     *   peer.send('Hello!')
      * })
      *
-     * connection.on('message', (data) => {
+     * peer.on('message', (data) => {
      *   console.log('Received:', data)
      * })
      *
-     * connection.on('reconnecting', (attempt) => {
-     *   console.log(`Reconnecting, attempt ${attempt}`)
+     * peer.on('state', (state, prevState) => {
+     *   console.log(`State: ${prevState} → ${state}`)
      * })
      *
-     * // Discover random service
-     * const connection = await rondevu.connectToService({
-     *   service: 'chat:2.0.0'
-     * })
+     * // Access underlying RTCPeerConnection
+     * if (peer.peerConnection) {
+     *   console.log('ICE state:', peer.peerConnection.iceConnectionState)
+     * }
      * ```
      */
-    connectToService(options: ConnectToServiceOptions): Promise<AnswererConnection>;
+    peer(options: PeerOptions): Promise<Peer>;
     /**
-     * Find a service - unified discovery method
+     * Discover offers by tags
      *
-     * @param serviceFqn - Service identifier (e.g., 'chat:1.0.0' or 'chat:1.0.0@alice')
-     * @param options - Discovery options
+     * @param tags - Tags to search for (OR logic - matches any tag)
+     * @param options - Discovery options (pagination)
      *
      * @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')
+     * // Discover offers matching any of the tags
+     * const result = await rondevu.discover(['chat', 'video'])
      *
      * // Paginated discovery
-     * const result = await rondevu.findService('chat:1.0.0', {
-     *   mode: 'paginated',
+     * const result = await rondevu.discover(['chat'], {
      *   limit: 20,
      *   offset: 0
      * })
+     *
+     * // Access offers
+     * for (const offer of result.offers) {
+     *   console.log(offer.username, offer.tags)
+     * }
      * ```
      */
-    findService(serviceFqn: string, options?: FindServiceOptions): Promise<ServiceResult | PaginatedServiceResult>;
+    discover(tags: string[], options?: DiscoverOptions): Promise<DiscoverResult>;
     /**
      * Post answer SDP to specific offer
      */
-    postOfferAnswer(serviceFqn: string, offerId: string, sdp: string): Promise<{
+    postOfferAnswer(offerId: string, sdp: string): Promise<{
         success: boolean;
         offerId: string;
     }>;
     /**
      * Get answer SDP (offerer polls this)
      */
-    getOfferAnswer(serviceFqn: string, offerId: string): Promise<{
+    getOfferAnswer(offerId: string): Promise<{
         sdp: string;
         offerId: string;
         answererId: string;
@@ -344,7 +264,6 @@ export declare class Rondevu extends EventEmitter {
     poll(since?: number): Promise<{
         answers: Array<{
             offerId: string;
-            serviceId?: string;
             answererId: string;
             sdp: string;
             answeredAt: number;
@@ -359,41 +278,19 @@ export declare class Rondevu extends EventEmitter {
     /**
      * Add ICE candidates to specific offer
      */
-    addOfferIceCandidates(serviceFqn: string, offerId: string, candidates: RTCIceCandidateInit[]): Promise<{
+    addOfferIceCandidates(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<{
+    getOfferIceCandidates(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;
     /**
      * Get active connections (for offerer side)
      */
     getActiveConnections(): Map<string, OffererConnection>;
-    /**
-     * Get all active offers (legacy compatibility)
-     * @deprecated Use getActiveConnections() instead
-     */
-    getActiveOffers(): ActiveOffer[];
-    /**
-     * Access to underlying API for advanced operations
-     * @deprecated Use direct methods on Rondevu instance instead
-     */
-    getAPIPublic(): RondevuAPI;
 }