@onlive.ai/common-121 0.2.66 → 0.2.163

package/services/conversation/conversation.types.d.cts

@@ -0,0 +1,519 @@
+/*! @onlive.ai/common-121 v0.2.163 | © 2026 Onlive.ai */
+import { ReceivedChatMessage } from '@livekit/components-core';
+import { Participant, RoomOptions as RoomOptions$1, Room } from 'livekit-client';
+import { FirebaseConfig } from '../firebase/firebase-api.cjs';
+import 'firebase/database';
+
+/**
+ * Extended Room options that wrap LiveKit's room configuration.
+ *
+ * @property {boolean} [adaptiveStream] - Enable adaptive streaming for video tracks.
+ * @property {boolean} [dynacast] - Enable dynamic broadcasting optimization.
+ */
+interface RoomOptions extends Partial<RoomOptions$1> {
+}
+/**
+ * Extended Room class with additional metadata properties.
+ *
+ * @property {string} id - Unique identifier of the room.
+ * @property {string} groupId - Group identifier for room categorization.
+ * @property {string} createdAt - ISO timestamp when the room was created.
+ * @property {string} connectedAt - ISO timestamp when the user connected to the room.
+ */
+interface ExtendedRoom extends Room {
+    id: string;
+    groupId: string;
+    createdAt: string;
+    connectedAt: string;
+}
+/**
+ * Room API response structure from the backend.
+ *
+ * @property {string} id - Room unique identifier.
+ * @property {string} groupId - Group identifier for room categorization.
+ * @property {string} token - Authentication token for room access.
+ * @property {string} wsURL - WebSocket URL for real-time connection.
+ * @property {string} createdAt - ISO timestamp of room creation.
+ */
+type RoomApiResponse = {
+    id: string;
+    groupId: string;
+    token: string;
+    wsURL: string;
+    createdAt: string;
+};
+/**
+ * Room list item structure for room listings.
+ *
+ * @property {string} id - Room unique identifier.
+ * @property {string} [name] - Optional room display name.
+ * @property {string} [groupId] - Group identifier.
+ * @property {string} [organizationId] - Organization that owns the room.
+ * @property {string | null} [endedAt] - Timestamp when room ended, null if active.
+ * @property {string} createdAt - Room creation timestamp.
+ * @property {string} updatedAt - Last update timestamp.
+ * @property {ApiMessage[]} [messages] - Array of messages in the room.
+ * @property {Record<string, unknown>} [metadata] - Additional room metadata.
+ * @property {"active" | "ended" | "pending"} [status] - Current room status.
+ * @property {number} [messageCount] - Total number of messages.
+ * @property {Array<ParticipantInfo>} participants - Room participants.
+ * @property {Array<EvaluationInfo>} evaluations - Room evaluations/ratings.
+ * @property {number} [participantCount] - Total participant count.
+ * @property {number} [evaluationCount] - Total evaluation count.
+ * @property {CountInfo} [_count] - Aggregated counts.
+ */
+type RoomListItem = {
+    id: string;
+    name?: string;
+    groupId?: string;
+    organizationId?: string;
+    endedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    messages?: ApiMessage[];
+    metadata?: Record<string, unknown>;
+    status?: "active" | "ended" | "pending";
+    messageCount?: number;
+    participants: Array<{
+        id: string;
+        name: string;
+        role: "user" | "agent" | "assistant";
+        externalId?: string;
+        image?: string;
+        isAgent?: boolean;
+        isLocal?: boolean;
+    }>;
+    evaluations: Array<{
+        id: string;
+        rating: number;
+        comment?: string;
+        createdAt: string;
+    }>;
+    participantCount?: number;
+    evaluationCount?: number;
+    _count?: {
+        messages?: number;
+        participants?: number;
+        evaluations?: number;
+    };
+};
+/**
+ * Paginated response for room listings.
+ *
+ * @property {RoomListItem[]} items - Array of room items.
+ * @property {number} count - Total number of items.
+ * @property {number} limit - Maximum items per page.
+ * @property {number} offset - Current page offset.
+ */
+type RoomsApiResponse = {
+    items: RoomListItem[];
+    count: number;
+    limit: number;
+    offset: number;
+};
+/**
+ * Participant information with extended user details.
+ *
+ * @property {string} id - User unique identifier.
+ * @property {"user" | "agent" | "assistant"} role - User's role in the conversation.
+ * @property {string} [avatar] - URL to user's avatar image.
+ * @property {string} [name] - Display name of the user.
+ */
+interface UserFrom extends Participant {
+    id: string;
+    role: "user" | "agent" | "assistant";
+    avatar?: string;
+    name?: string;
+}
+/**
+ * User API response after registration.
+ *
+ * @property {string} id - User unique identifier.
+ * @property {string} externalId - External system identifier.
+ * @property {string} organizationId - Associated organization ID.
+ * @property {string} role - User's assigned role.
+ * @property {string} token - Authentication token.
+ */
+type UserApiResponse = {
+    id: string;
+    externalId: string;
+    organizationId: string;
+    role: string;
+    token: string;
+};
+/**
+ * Agent data for registration.
+ *
+ * @property {string} name - Agent display name.
+ * @property {string} [avatar] - URL to agent's avatar.
+ * @property {string} [email] - Agent email address.
+ */
+interface AgentData {
+    name: string;
+    avatar?: string;
+    email?: string;
+}
+/**
+ * Asset attached to a message.
+ *
+ * @property {string} assetType - Type of asset (product, multimedia, faq, file).
+ * @property {string} assetExternalId - External identifier for the asset.
+ */
+interface Assets {
+    assetType: string;
+    assetExternalId: string;
+}
+/**
+ * Media attachment structure.
+ *
+ * @property {string} url - URL of the media file.
+ * @property {string} ext - File extension.
+ * @property {string} [name] - Optional name of the file.
+ * @property {string} [type] - Optional media type.
+ */
+interface MediaAttachment {
+    name?: string;
+    url: string;
+    ext: string;
+    type?: string;
+}
+/**
+ * Report information for a message.
+ *
+ * @property {string} id - Unique identifier of the report.
+ * @property {string} createdAt - ISO timestamp of report creation.
+ */
+interface ReportInfo {
+    id: string;
+    createdAt: string;
+}
+/**
+ * API message structure extending LiveKit's received chat message.
+ *
+ * @property {"standard" | "system"} [type] - Message type classification.
+ * @property {string} content - Text content of the message.
+ * @property {string} createdAt - ISO timestamp of message creation.
+ * @property {UserFrom} [from] - Sender information.
+ * @property {Array<MediaAttachment>} [media] - Attached media files.
+ * @property {Array<Assets>} [assets] - Attached assets.
+ * @property {Array<ReportInfo>} [reports] - Message reports/flags.
+ */
+type ApiMessage = Omit<ReceivedChatMessage, "type"> & {
+    type?: "standard" | "system";
+    content: string;
+    createdAt: string;
+    from?: UserFrom;
+    media?: MediaAttachment[];
+    assets?: Assets[];
+    reports?: ReportInfo[];
+};
+/**
+ * Paginated response for messages.
+ *
+ * @property {ApiMessage[]} items - Array of messages.
+ * @property {number} count - Total message count.
+ * @property {number} limit - Maximum items per page.
+ * @property {number} offset - Current page offset.
+ */
+type MessagesApiResponse = {
+    items: ApiMessage[];
+    count: number;
+    limit: number;
+    offset: number;
+};
+/**
+ * Typing indicator event structure.
+ *
+ * @property {"typing"} type - Event type identifier.
+ * @property {boolean} isTyping - Whether the participant is currently typing.
+ * @property {number} timestamp - Unix timestamp of the event.
+ * @property {string} participantId - Identifier of the typing participant.
+ */
+interface TypingIndicator {
+    type: "typing";
+    isTyping: boolean;
+    timestamp: number;
+    participantId: string;
+}
+/**
+ * Available contextual event names.
+ */
+type ContextualEventNames = "call_ended" | "interrupt";
+/**
+ * Contextual event structure for signaling state changes.
+ *
+ * @property {ContextualEventNames} eventName - Name of the event.
+ * @property {Record<string, unknown>} [eventData] - Additional event data.
+ * @property {boolean} [generateResponse] - Whether to trigger AI response.
+ */
+interface ContextualEvent {
+    eventName: ContextualEventNames;
+    eventData?: Record<string, unknown>;
+    generateResponse?: boolean;
+}
+/**
+ * Call request structure stored in Firebase.
+ *
+ * @property {string} guestId - Identifier of the guest requesting the call.
+ * @property {string} agentId - Identifier of the assigned agent.
+ * @property {string} roomName - Name of the room for the call.
+ * @property {string} startedAt - ISO timestamp when call started.
+ * @property {string | null} endedAt - ISO timestamp when call ended, null if active.
+ */
+interface Call {
+    guestId: string;
+    agentId: string;
+    roomName: string;
+    startedAt: string;
+    endedAt: string | null;
+}
+/**
+ * Request status for call/room requests.
+ */
+type RequestStatus = "pending" | "accepted" | "cancelled" | "not_response" | "disconnected";
+/**
+ * Call request structure for real-time request handling.
+ *
+ * @property {string} guestId - Identifier of the requesting guest.
+ * @property {string} [name] - Display name of the guest.
+ * @property {string} createdAt - ISO timestamp of request creation.
+ * @property {string} [roomId] - Associated room identifier.
+ * @property {RequestStatus} status - Current request status.
+ * @property {string | null} assignedAgentId - ID of assigned agent, null if unassigned.
+ * @property {string} id - Unique request identifier.
+ */
+interface CallRequest {
+    guestId: string;
+    name?: string;
+    createdAt: string;
+    roomId?: string;
+    status: RequestStatus;
+    assignedAgentId?: string;
+    id: string;
+    userGroupId?: string;
+}
+/**
+ * Room sync notification data structure.
+ *
+ * @property {boolean} needsSync - Whether the room needs synchronization.
+ * @property {string} [reason] - Reason for the sync request.
+ * @property {number} [timestamp] - Unix timestamp of the sync event.
+ */
+interface RoomSyncData {
+    needsSync: boolean;
+    reason?: string;
+    timestamp?: number;
+}
+/**
+ * New room request notification data.
+ *
+ * @property {Object} requestingUser - Information about the requesting user.
+ * @property {string} requestingUser.id - User identifier.
+ * @property {string} requestingUser.name - User display name.
+ * @property {string} requestingUser.role - User role.
+ * @property {number} timestamp - Request timestamp.
+ * @property {string} [status] - Current request status.
+ */
+interface NewRoomRequestData {
+    requestingUser: {
+        id: string;
+        name: string;
+        role: string;
+    };
+    timestamp: number;
+    status?: string;
+}
+/**
+ * Options for creating a new room.
+ *
+ * @property {string} language - Preferred language code (e.g., "en", "es").
+ * @property {string} timezone - IANA timezone identifier.
+ * @property {Record<string, unknown>} [affinity] - Agent affinity preferences.
+ * @property {boolean} [disablePersistence] - Disable message persistence.
+ * @property {Record<string, unknown>} [metadata] - Additional room metadata.
+ * @property {ContextualEvent[]} [contextualEvents] - Initial contextual events.
+ */
+type CreateRoomOptions = {
+    language: string;
+    timezone: string;
+    affinity?: Record<string, unknown>;
+    disablePersistence?: boolean;
+    metadata?: Record<string, unknown>;
+    contextualEvents?: ContextualEvent[];
+    userGroupId?: string;
+};
+/**
+ * Options for fetching messages.
+ *
+ * @property {string} [roomId] - Filter by room ID.
+ * @property {number} [limit] - Maximum messages to return.
+ * @property {string} [orderBy] - Field to order by.
+ * @property {"asc" | "desc"} [orderDir] - Sort direction.
+ * @property {string} [groupId] - Filter by group ID.
+ * @property {Object} [affinity] - Agent affinity filters.
+ * @property {string[]} [with] - Related entities to include.
+ * @property {boolean} [impersonate] - Enable impersonation mode.
+ */
+type GetMessagesOptions = {
+    roomId?: string;
+    limit?: number;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    groupId?: string;
+    affinity?: {
+        agentId?: string;
+        agentType?: string;
+    };
+    with?: string[];
+    impersonate?: boolean;
+};
+/**
+ * Options for persisting a message.
+ *
+ * @property {string} [externalId] - External message identifier.
+ * @property {string} roomId - Room to persist message in.
+ * @property {string} content - Message content.
+ * @property {string} [identity] - Sender identity.
+ * @property {number} [kind] - Participant kind.
+ */
+type PersistMessageOptions = {
+    externalId?: string;
+    roomId: string;
+    content: string;
+    identity?: string;
+    kind?: number;
+};
+/**
+ * Options for room evaluation/rating.
+ *
+ * @property {number} rating - Numeric rating value.
+ * @property {string} [comment] - Optional feedback comment.
+ * @property {string} [roomId] - Optional room identifier.
+ */
+type EvaluateRoomOptions = {
+    rating: number;
+    comment?: string;
+    roomId?: string;
+};
+/**
+ * Options for message reporting.
+ *
+ * @property {string} messageId - ID of message to report.
+ */
+type MessageReportOptions = {
+    messageId: string;
+};
+/**
+ * Options for updating message reactions.
+ *
+ * @property {string} messageId - ID of message to update.
+ * @property {string[]} [add] - Reactions to add.
+ * @property {string[]} [remove] - Reactions to remove.
+ */
+type MessageReactionOptions = {
+    messageId: string;
+    add?: string[];
+    remove?: string[];
+};
+/**
+ * Options for fetching room listings.
+ *
+ * @property {number} [limit] - Maximum rooms per page.
+ * @property {number} [page] - Page number (1-indexed).
+ * @property {number} [offset] - Offset for pagination.
+ * @property {"createdAt" | "updatedAt" | "lastMessageAt"} [orderBy] - Sort field.
+ * @property {"asc" | "desc"} [orderDir] - Sort direction.
+ * @property {string[]} [ids] - Filter by specific room IDs.
+ * @property {string[]} [with] - Related entities to include.
+ * @property {string[]} [count] - Fields to count.
+ * @property {string[]} [participantIds] - Filter by participant IDs.
+ * @property {string[]} [participantExternalIds] - Filter by external participant IDs.
+ * @property {string} [groupId] - Filter by group ID.
+ * @property {boolean} [hasMessages] - Filter rooms with messages.
+ * @property {boolean} [latestOnly] - Return only latest room per group.
+ * @property {boolean} [includeUnread] - Include unread message count.
+ * @property {"active" | "closed"} [roomStatus] - Filter by room status.
+ * @property {boolean} [archived] - Include archived rooms.
+ */
+type GetRoomsOptions = {
+    limit?: number;
+    page?: number;
+    offset?: number;
+    orderBy?: "createdAt" | "updatedAt" | "lastMessageAt";
+    orderDir?: "asc" | "desc";
+    ids?: string[];
+    with?: string[];
+    count?: string[];
+    participantIds?: string[];
+    participantExternalIds?: string[];
+    groupId?: string;
+    hasMessages?: boolean;
+    latestOnly?: boolean;
+    includeUnread?: boolean;
+    roomStatus?: "active" | "closed";
+    archived?: boolean;
+};
+/**
+ * Options for requesting a new room (call transfer).
+ *
+ * @property {string} originRoom - Source room ID.
+ * @property {string} language - Preferred language.
+ * @property {string} timezone - User's timezone.
+ * @property {Object} [affinity] - Agent preferences.
+ * @property {string} [name] - Display name.
+ */
+type RequestNewRoomOptions = {
+    originRoom: string;
+    language: string;
+    timezone: string;
+    affinity?: {
+        agentType?: string;
+        target?: string;
+    };
+    name?: string;
+    userGroupId?: string;
+};
+/**
+ * Configuration options for the ConversationService.
+ *
+ * @property {string} organizationId - Organization identifier.
+ * @property {string} apiUrl - Base URL for the conversation API.
+ * @property {string} [authUrl] - Optional separate auth service URL.
+ * @property {string} [channelTopic] - Custom LiveKit chat topic.
+ * @property {string} [transcriptionTopic] - Custom transcription topic.
+ * @property {string} [eventsTopic] - Custom events topic.
+ * @property {"disabled" | "server" | "client"} [messagePersistence] - Message persistence mode.
+ * @property {FirebaseConfig} [firebaseConfig] - Optional Firebase configuration for real-time features.
+ */
+type ConversationServiceOptions = {
+    organizationId: string;
+    apiUrl: string;
+    authUrl?: string;
+    channelTopic?: string;
+    transcriptionTopic?: string;
+    eventsTopic?: string;
+    messagePersistence?: "disabled" | "server" | "client";
+    firebaseConfig?: FirebaseConfig;
+};
+/**
+ * Callback type for message listeners.
+ */
+type MessageListener<M = ApiMessage> = (messages: M[]) => void;
+/**
+ * Callback type for typing indicator listeners.
+ */
+type TypingListener = (indicator: TypingIndicator) => void;
+/**
+ * Callback type for call request listeners.
+ */
+type CallRequestListener = (id: string, request: CallRequest) => void;
+/** Default LiveKit chat topic */
+declare const CHAT_TOPIC: "lk.chat";
+/** Default LiveKit transcription topic */
+declare const TRANSCRIPTION_TOPIC: "lk.transcription";
+/** Default LiveKit events topic */
+declare const EVENTS_TOPIC: "lk.events";
+/** Topic for typing indicator messages */
+declare const TYPING_INDICATOR_TOPIC: "typing-indicator";
+
+export { type AgentData, type ApiMessage, type Assets, CHAT_TOPIC, type Call, type CallRequest, type CallRequestListener, type ContextualEvent, type ContextualEventNames, type ConversationServiceOptions, type CreateRoomOptions, EVENTS_TOPIC, type EvaluateRoomOptions, type ExtendedRoom, type GetMessagesOptions, type GetRoomsOptions, type MediaAttachment, type MessageListener, type MessageReactionOptions, type MessageReportOptions, type MessagesApiResponse, type NewRoomRequestData, type PersistMessageOptions, type ReportInfo, type RequestNewRoomOptions, type RequestStatus, type RoomApiResponse, type RoomListItem, type RoomOptions, type RoomSyncData, type RoomsApiResponse, TRANSCRIPTION_TOPIC, TYPING_INDICATOR_TOPIC, type TypingIndicator, type TypingListener, type UserApiResponse, type UserFrom };