@onlive.ai/common-121 0.2.70 → 0.2.179

package/services/conversation/conversation.service.d.cts

@@ -0,0 +1,543 @@
+/*! @onlive.ai/common-121 v0.2.179 | © 2026 Onlive.ai */
+import { Room as Room$1 } from 'livekit-client';
+import { ConversationServiceOptions, UserApiResponse, AgentData, CreateRoomOptions, EvaluateRoomOptions, GetRoomsOptions, RoomsApiResponse, PersistMessageOptions, MessagesApiResponse, GetMessagesOptions, ApiMessage, MessageReportOptions, MessageReactionOptions, MessageListener, TypingListener, ContextualEvent, RequestNewRoomOptions, RoomApiResponse, CallRequest, CallRequestListener, RoomSyncData, NewRoomRequestData } from './conversation.types.cjs';
+import '@livekit/components-core';
+import '../firebase/firebase-api.cjs';
+import 'firebase/database';
+
+/**
+ * Extended Room class with persistent metadata.
+ *
+ * @description Extends LiveKit Room with additional properties for
+ * tracking room lifecycle and metadata.
+ */
+declare class Room extends Room$1 {
+    /** Unique room identifier */
+    id: string;
+    /** Group identifier for room categorization */
+    groupId: string;
+    /** ISO timestamp of room creation */
+    createdAt: string;
+    /** ISO timestamp when user connected */
+    connectedAt: string;
+    /** Affinity data echoed back from the server */
+    affinity?: Record<string, unknown>;
+}
+/**
+ * @summary Unified service for conversation management.
+ *
+ * @description A comprehensive service that combines real-time communication (LiveKit)
+ * with presence and request management (Firebase) for handling conversations.
+ * This service manages room lifecycle, messaging, typing indicators, call requests,
+ * and agent presence in a unified API.
+ *
+ * @example
+ * ```typescript
+ * const service = new ConversationService({
+ *   organizationId: 'org-123',
+ *   apiUrl: 'https://api.example.com',
+ *   firebaseConfig: { ... }
+ * });
+ *
+ * // Register user and create room
+ * await service.registerUser('user-123', 'secret');
+ * const room = await service.createRoom({
+ *   language: 'en',
+ *   timezone: 'America/New_York'
+ * });
+ *
+ * // Subscribe to messages
+ * service.subscribeMessages((messages) => {
+ *   console.log('New messages:', messages);
+ * });
+ * ```
+ */
+declare class ConversationService {
+    /** Message event listeners */
+    private listeners;
+    /** Typing indicator listeners */
+    private typingListeners;
+    /** Map for deduplicating transcription segments */
+    private transcriptionMap;
+    /** Base API URL */
+    private apiUrl;
+    /** Authentication service URL */
+    private authUrl?;
+    /** Organization identifier */
+    private organizationId;
+    /** LiveKit chat topic */
+    private channelTopic;
+    /** LiveKit transcription topic */
+    private transcriptionTopic;
+    /** LiveKit events topic */
+    private eventsTopic;
+    /** Message persistence mode */
+    private messagePersistence;
+    /** Abort controllers for cancellable requests */
+    private abortControllers;
+    /** Current authentication token */
+    private authToken;
+    /** Firebase API instance (optional) */
+    private firebaseApi?;
+    /** Firebase presence path */
+    private presencePath?;
+    /** Firebase calls path */
+    private callsPath?;
+    /** Active Firebase unsubscribers */
+    private firebaseUnsubscribers;
+    /** Set of seen request IDs for deduplication */
+    private seenRequestIds;
+    /** Map for content-based deduplication */
+    private lastSnapshotById;
+    /** Current LiveKit room instance */
+    room: Room;
+    /**
+     * Initializes a new instance of the ConversationService.
+     *
+     * @param {ConversationServiceOptions} options - Service configuration options.
+     */
+    constructor(options: ConversationServiceOptions);
+    /**
+     * Creates a new LiveKit Room instance with default settings.
+     *
+     * @private
+     * @returns {Room} New Room instance.
+     */
+    private createRoomInstance;
+    /**
+     * Ensures a room instance exists, creating one if necessary.
+     *
+     * @returns {Room} Current or new Room instance.
+     */
+    ensureRoom(): Room;
+    /**
+     * Initializes Firebase services for presence and request management.
+     *
+     * @private
+     * @param {FirebaseConfig} config - Firebase configuration.
+     */
+    private initializeFirebase;
+    /**
+     * Sets up LiveKit room event handlers for messaging and typing.
+     *
+     * @private
+     */
+    private initializeRoomHandlers;
+    /**
+     * Registers a user for conversation access.
+     *
+     * @async
+     * @param {string} externalId - External user identifier.
+     * @param {string} secret - User authentication secret.
+     * @param {Record<string, unknown>} [userData] - Additional user data.
+     * @param {Record<string, unknown>} [metadata] - User metadata.
+     * @returns {Promise<UserApiResponse>} User registration response with token.
+     */
+    registerUser(externalId: string, secret: string, userData?: Record<string, unknown>, metadata?: Record<string, unknown>): Promise<UserApiResponse>;
+    /**
+     * Registers an agent for handling conversations.
+     *
+     * @async
+     * @param {string} externalId - External agent identifier.
+     * @param {AgentData} agentData - Agent profile data.
+     * @returns {Promise<string>} Authentication token.
+     */
+    registerAgent(externalId: string, agentData: AgentData): Promise<string>;
+    /**
+     * Decodes a JWT token payload without verification.
+     *
+     * @private
+     * @param {string} token - JWT token string.
+     * @returns {{ username?: string; sub?: string; iat?: number; exp?: number } | null} Decoded payload or null if invalid.
+     */
+    private decodeJwtPayload;
+    /**
+     * Creates a new conversation room.
+     *
+     * @async
+     * @param {CreateRoomOptions} options - Room creation options.
+     * @param {Record<string, string>} [userData] - User attributes to set.
+     * @returns {Promise<Room>} Connected room instance.
+     */
+    createRoom(options: CreateRoomOptions): Promise<Room>;
+    /**
+     * Joins an existing conversation room.
+     *
+     * @async
+     * @param {string} roomId - Room identifier to join.
+     * @param {string} timezone - User's timezone.
+     * @param {string} language - Preferred language.
+     * @param {Record<string, unknown>} [attributes] - Additional attributes.
+     * @returns {Promise<Room>} Connected room instance.
+     */
+    joinRoom(roomId: string, timezone: string, language: string, attributes?: Record<string, unknown>): Promise<Room>;
+    /**
+     * Sets room metadata from API response.
+     *
+     * @private
+     * @param {RoomApiResponse} response - Room API response.
+     */
+    private setRoomMetadata;
+    /**
+     * Sets up handler for participant attribute changes.
+     *
+     * @private
+     */
+    private setupParticipantAttributesHandler;
+    /**
+     * Evaluates/rates the current room.
+     *
+     * @async
+     * @param {EvaluateRoomOptions} options - Evaluation options.
+     * @returns {Promise<void>}
+     */
+    evaluateRoom(options: EvaluateRoomOptions): Promise<void>;
+    /**
+     * Closes the current room on the server.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    closeRoom(): Promise<void>;
+    /**
+     * Disconnects from the current room.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Stops and unpublishes all currently published local tracks.
+     *
+     * @async
+     * @private
+     * @returns {Promise<void>}
+     */
+    private stopAndUnpublishLocalTracks;
+    /**
+     * Closes the room on server and disconnects locally.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    disconnectAndCloseRoom(): Promise<void>;
+    /**
+     * Marks a room as read.
+     *
+     * @async
+     * @param {string} roomId - Room identifier.
+     * @returns {Promise<void>}
+     */
+    readRoom(roomId: string): Promise<void>;
+    /**
+     * Fetches a list of rooms based on options.
+     *
+     * @async
+     * @param {GetRoomsOptions} options - Room listing options.
+     * @returns {Promise<RoomsApiResponse>} Paginated room list.
+     */
+    getRooms(options: GetRoomsOptions): Promise<RoomsApiResponse>;
+    /**
+     * Handles incoming messages from LiveKit.
+     *
+     * @private
+     */
+    private handleIncomingMessage;
+    /**
+     * Emits a message to all subscribed listeners.
+     *
+     * @private
+     * @param {ApiMessage} message - Message to emit.
+     */
+    private emitMessage;
+    /**
+     * Sends a message in the current room.
+     *
+     * @async
+     * @param {string} message - Message content.
+     * @param {Record<string, string>} [attributes] - Message attributes.
+     * @returns {Promise<void>}
+     */
+    sendMessage(message: string, attributes?: Record<string, string>): Promise<void>;
+    /**
+     * Persists a message to the server.
+     *
+     * @async
+     * @param {PersistMessageOptions} options - Persistence options.
+     * @returns {Promise<MessagesApiResponse>}
+     */
+    persistMessage(options: PersistMessageOptions): Promise<MessagesApiResponse>;
+    /**
+     * Fetches messages based on options.
+     *
+     * @async
+     * @param {GetMessagesOptions} options - Message fetching options.
+     * @returns {Promise<ApiMessage[]>} Array of messages.
+     */
+    getMessages(options: GetMessagesOptions): Promise<ApiMessage[]>;
+    /**
+     * Reports a message for moderation.
+     *
+     * @async
+     * @param {MessageReportOptions} options - Report options.
+     * @returns {Promise<void>}
+     */
+    sendMessageReport(options: MessageReportOptions): Promise<void>;
+    /**
+     * Deletes a message report.
+     *
+     * @async
+     * @param {MessageReportOptions} options - Report options.
+     * @returns {Promise<void>}
+     */
+    deleteMessageReport(options: MessageReportOptions): Promise<void>;
+    /**
+     * Updates reactions on a message.
+     *
+     * @async
+     * @param {MessageReactionOptions} options - Reaction options.
+     * @returns {Promise<void>}
+     */
+    updateMessageReactions(options: MessageReactionOptions): Promise<void>;
+    /**
+     * Subscribes to incoming messages.
+     *
+     * @param {MessageListener<M>} callback - Message listener callback.
+     * @returns {() => void} Unsubscribe function.
+     */
+    subscribeMessages<M extends ApiMessage = ApiMessage>(callback: MessageListener<M>): () => void;
+    /**
+     * Handles data received events for typing indicators.
+     *
+     * @private
+     */
+    private handleDataReceived;
+    /**
+     * Emits a typing indicator to all listeners.
+     *
+     * @private
+     * @param {TypingIndicator} indicator - Typing indicator data.
+     */
+    private emitTypingIndicator;
+    /**
+     * Sends a typing indicator to other participants.
+     *
+     * @async
+     * @param {boolean} isTyping - Whether the user is currently typing.
+     * @returns {Promise<void>}
+     */
+    sendTypingIndicator(isTyping: boolean): Promise<void>;
+    /**
+     * Subscribes to typing indicators from other participants.
+     *
+     * @param {TypingListener} listener - Typing indicator listener.
+     * @returns {() => void} Unsubscribe function.
+     */
+    subscribeTypingIndicators(listener: TypingListener): () => void;
+    /**
+     * Unsubscribes a typing indicator listener.
+     *
+     * @param {TypingListener} listener - Listener to remove.
+     */
+    unsubscribeTypingIndicators(listener: TypingListener): void;
+    /**
+     * Sends a contextual event to the room.
+     *
+     * @async
+     * @param {ContextualEvent} event - Event to send.
+     * @returns {Promise<void>}
+     */
+    sendContextualEvent(event: ContextualEvent): Promise<void>;
+    /**
+     * Requests a new room (call transfer).
+     *
+     * @async
+     * @param {RequestNewRoomOptions} options - Request options.
+     * @returns {Promise<RoomApiResponse>} New room details.
+     */
+    requestNewRoom(options: RequestNewRoomOptions): Promise<RoomApiResponse>;
+    /**
+     * Confirms an active room request.
+     *
+     * @async
+     * @param {string} roomId - Room identifier.
+     * @returns {Promise<{ success: boolean; message: string; roomId: string }>}
+     */
+    confirmRoomRequest(roomId: string): Promise<{
+        success: boolean;
+        message: string;
+        roomId: string;
+    }>;
+    /**
+     * Cancels an active room request.
+     *
+     * @async
+     * @param {string} roomId - Room identifier.
+     * @returns {Promise<{ success: boolean; message: string; roomId: string }>}
+     */
+    cancelRoomRequest(roomId: string): Promise<{
+        success: boolean;
+        message: string;
+        roomId: string;
+    }>;
+    /**
+     * Finishes an active call.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    finishCall(): Promise<void>;
+    /**
+     * Checks if Firebase is initialized.
+     *
+     * @returns {boolean} True if Firebase features are available.
+     */
+    isFirebaseEnabled(): boolean;
+    /**
+     * Gets Firebase API and paths, throwing if not initialized.
+     *
+     * @private
+     * @throws {Error} If Firebase is not initialized.
+     * @returns {{ api: FirebaseApi; presencePath: string; callsPath: string }}
+     */
+    private getFirebase;
+    /**
+     * Gets the presence path for an agent.
+     *
+     * @private
+     * @param {string} agentId - Agent identifier.
+     * @returns {string} Firebase path.
+     */
+    private buildAgentPresencePath;
+    /**
+     * Subscribes to presence changes for all agents.
+     *
+     * @param {(agentId: string, data: object | null) => void} callback - Change handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onPresenceChange(callback: (agentId: string, data: object | null) => void): () => void;
+    /**
+     * Subscribes to presence changes for a specific agent.
+     *
+     * @param {string} agentId - Agent identifier.
+     * @param {(agentId: string, data: object | null) => void} callback - Change handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onPresenceAgentChange(agentId: string, callback: (agentId: string, data: object | null) => void): () => void;
+    /**
+     * Creates a new call request via API.
+     *
+     * @async
+     * @param {Omit<CallRequest, "status" | "createdAt">} requestData - Request data.
+     * @returns {Promise<string>} Request identifier.
+     */
+    createCallRequest(requestData: Omit<CallRequest, "status" | "createdAt" | "id">): Promise<string>;
+    /**
+     * Subscribes to new call requests.
+     *
+     * @param {CallRequestListener} callback - Request handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onNewCallRequest(callback: CallRequestListener): () => void;
+    /**
+     * Subscribes to call request changes.
+     *
+     * @param {CallRequestListener} callback - Change handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onCallRequestChange(callback: CallRequestListener): () => void;
+    /**
+     * Subscribes to call request removals.
+     *
+     * @param {(id: string) => void} callback - Removal handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onCallRequestRemoved(callback: (id: string) => void): () => void;
+    /**
+     * Accepts a call request.
+     *
+     * @async
+     * @param {string} requestId - Request identifier.
+     * @returns {Promise<void>}
+     */
+    acceptCallRequest(requestId: string): Promise<void>;
+    /**
+     * Cancels a call request via API.
+     *
+     * @async
+     * @param {string} requestId - Request identifier.
+     * @returns {Promise<void>}
+     */
+    cancelCallRequest(requestId: string): Promise<void>;
+    /**
+     * Cancels onDisconnect behavior for a request.
+     *
+     * @async
+     * @param {string} requestId - Request identifier.
+     * @returns {Promise<void>}
+     */
+    cancelOnDisconnect(requestId: string): Promise<void>;
+    /**
+     * Subscribes to pending call requests with deduplication.
+     *
+     * @param {CallRequestListener} callback - Request handler.
+     * @param {{ resetSeen?: boolean }} [options] - Subscription options.
+     * @returns {() => void} Unsubscribe function.
+     */
+    subscribePendingRequests(callback: CallRequestListener, options?: {
+        resetSeen?: boolean;
+    }): () => void;
+    /**
+     * Subscribes to request changes with content deduplication.
+     *
+     * @param {CallRequestListener} callback - Change handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    subscribeRequestChanges(callback: CallRequestListener): () => void;
+    /**
+     * Attempts to safely accept a request if still pending.
+     *
+     * @async
+     * @param {string} requestId - Request identifier.
+     * @returns {Promise<boolean>} True if successfully accepted.
+     */
+    tryAcceptRequest(requestId: string): Promise<boolean>;
+    /**
+     * Subscribes to room sync notifications.
+     *
+     * @param {string} roomId - Room identifier.
+     * @param {(data: RoomSyncData | null) => void} callback - Sync handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onRoomSync(roomId: string, callback: (data: RoomSyncData | null) => void): () => void;
+    /**
+     * Clears the sync flag for a room.
+     *
+     * @async
+     * @param {string} roomId - Room identifier.
+     * @param {string} [reason] - Reason for clearing.
+     * @returns {Promise<void>}
+     */
+    clearRoomSync(roomId: string, reason?: string): Promise<void>;
+    /**
+     * Subscribes to new room request notifications.
+     *
+     * @param {string} roomId - Origin room identifier.
+     * @param {(data: NewRoomRequestData | null) => void} callback - Request handler.
+     * @returns {() => void} Unsubscribe function.
+     */
+    onNewRoomRequest(roomId: string, callback: (data: NewRoomRequestData | null) => void): () => void;
+    /**
+     * Removes all Firebase listeners.
+     */
+    unsubscribeAllFirebase(): void;
+    /**
+     * Cleans up all resources and connections.
+     *
+     * @async
+     * @returns {Promise<void>}
+     */
+    destroy(): Promise<void>;
+}
+
+export { ConversationService, Room };