@xcelsior/ui-chat 1.0.8 → 2.0.1

package/dist/index.d.mts

@@ -13,14 +13,16 @@ interface IMessage {
     id: string;
     conversationId: string;
     senderId: string;
-    senderType: 'customer' | 'agent' | 'system';
+    senderType: 'customer' | 'agent' | 'bot' | 'system';
     content: string;
     messageType: MessageType;
     createdAt: string;
     status: MessageStatus;
+    feedback?: 'good' | 'wrong' | 'corrected' | null;
+    confidence?: number | null;
     metadata?: Record<string, unknown>;
 }
-type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived';
+type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived' | 'bot_handling' | 'pending_agent' | 'agent_active';
 type ConversationPriority = 'low' | 'medium' | 'high' | 'urgent';
 type ConversationChannel = 'web' | 'mobile' | 'email';
 interface IConversation {
@@ -42,7 +44,7 @@ interface IConversation {
     metadata?: Record<string, unknown>;
 }
 interface IWebSocketMessage {
-    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system';
+    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system' | 'escalation_requested' | 'bot_response' | 'conversation_updated';
     data: any;
 }
 interface ISendMessageData {
@@ -71,11 +73,25 @@ interface IUploadedFile {
     type: string;
     markdown?: string;
 }
+interface IChatTheme {
+    primary?: string;
+    primaryStrong?: string;
+    background?: string;
+    backgroundAlt?: string;
+    text?: string;
+    textMuted?: string;
+    statusPositive?: string;
+    statusCaution?: string;
+    statusNegative?: string;
+    borderColor?: string;
+}
+type WidgetPosition = 'left' | 'right' | 'auto';
+type IdentityCollectionMode = 'progressive' | 'form' | 'none';
 interface IChatConfig {
     websocketUrl: string;
     conversationId?: string;
     apiKey: string;
-    currentUser: IUser;
+    currentUser?: IUser;
     fileUpload?: IFileUploadConfig;
     httpApiUrl?: string;
     headers?: Record<string, string>;
@@ -89,17 +105,33 @@ interface IChatConfig {
      * @default false
      */
     disableWebSocket?: boolean;
+    theme?: IChatTheme;
+    position?: WidgetPosition;
+    identityCollection?: IdentityCollectionMode;
     onMessageSent?: (message: IMessage) => void;
     onMessageReceived?: (message: IMessage) => void;
     onConversationChange?: (conversation: IConversation) => void;
     onConnectionChange?: (connected: boolean) => void;
     onError?: (error: Error) => void;
+    onConversationRated?: (rating: 'positive' | 'negative') => void;
     toast?: {
         success: (message: string) => void;
         error: (message: string) => void;
         info: (message: string) => void;
     };
 }
+interface UseMessagesReturn {
+    messages: IMessage[];
+    addMessage: (message: IMessage) => void;
+    updateMessageStatus: (messageId: string, status: IMessage['status']) => void;
+    clearMessages: () => void;
+    isLoading: boolean;
+    error: Error | null;
+    loadMore: () => Promise<void>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    isBotThinking: boolean;
+}
 interface IApiResponse<T> {
     success: boolean;
     data?: T;
@@ -115,26 +147,14 @@ interface IApiResponse<T> {
 interface ChatWidgetProps {
     config: IChatConfig;
     className?: string;
-    /**
-     * Variant of the chat widget:
-     * - 'popover': Fixed positioned floating widget (default)
-     * - 'fullPage': Full page layout that fills the container
-     */
     variant?: 'popover' | 'fullPage';
-    /**
-     * External WebSocket connection (for agents with global connection)
-     */
     externalWebSocket?: WebSocket | null;
-    /**
-     * Callback when user wants to minimize the widget
-     */
     onMinimize?: () => void;
-    /**
-     * Callback when user wants to close the widget
-     */
     onClose?: () => void;
+    /** Resolved position (left or right) from the parent Chat component */
+    resolvedPosition?: 'left' | 'right';
 }
-declare function ChatWidget({ config, className, variant, externalWebSocket, onMinimize, onClose, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ config, className, variant, externalWebSocket, onMinimize, onClose, resolvedPosition, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 type ChatWidgetState = 'open' | 'minimized' | 'closed' | 'undefined';
 interface UseChatWidgetStateOptions {
@@ -173,57 +193,25 @@ interface UseChatWidgetStateReturn {
 declare function useChatWidgetState({ state: controlledState, defaultState, onStateChange, }: UseChatWidgetStateOptions): UseChatWidgetStateReturn;
 
 interface ChatWidgetWrapperProps {
-    /**
-     * Base configuration for the chat widget (without user info and conversationId)
-     */
-    config: Omit<IChatConfig, 'currentUser' | 'conversationId' | 'userId'> & {
-        currentUser?: Partial<IUser>;
+    config: Omit<IChatConfig, 'conversationId'> & {
         conversationId?: string;
     };
-    /**
-     * Custom className for the wrapper
-     */
     className?: string;
-    /**
-     * Storage key prefix for persisting user data
-     * Defaults to 'xcelsior_chat'
-     */
     storageKeyPrefix?: string;
-    /**
-     * Callback when user submits the pre-chat form
-     */
     onPreChatSubmit?: (user: IUser) => void;
-    /**
-     * Controlled state. When provided, the component is controlled.
-     * - 'open': Fully open with chat interface
-     * - 'minimized': Show bubble button only
-     * - 'closed': Fully hidden
-     */
     state?: ChatWidgetState;
-    /**
-     * Default state for uncontrolled mode
-     * @default 'minimized'
-     */
     defaultState?: ChatWidgetState;
-    /**
-     * Callback when state changes
-     */
     onStateChange?: (state: ChatWidgetState) => void;
 }
-/**
- * Chat component that handles:
- * - Automatic conversation ID generation
- * - Pre-chat form for collecting user information
- * - Session persistence in localStorage
- */
 declare function Chat({ config, className, storageKeyPrefix, onPreChatSubmit, state, defaultState, onStateChange, }: ChatWidgetWrapperProps): react_jsx_runtime.JSX.Element | null;
 
 interface ChatHeaderProps {
     agent?: IUser;
     onClose?: () => void;
     onMinimize?: () => void;
+    theme?: IChatTheme;
 }
-declare function ChatHeader({ agent, onClose, onMinimize }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
+declare function ChatHeader({ agent, onClose, onMinimize, theme }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
 
 interface UseFileUploadReturn {
     uploadFile: (file: File) => Promise<IUploadedFile | null>;
@@ -243,13 +231,30 @@ interface ChatInputProps {
 }
 declare function ChatInput({ onSend, onTyping, config, fileUpload, disabled, }: ChatInputProps): react_jsx_runtime.JSX.Element;
 
+interface MarkdownMessageProps {
+    content: string;
+    theme?: IChatTheme;
+}
+declare function MarkdownMessage({ content, theme }: MarkdownMessageProps): react_jsx_runtime.JSX.Element;
+
 interface MessageItemProps {
     message: IMessage;
     currentUser: IUser;
     showAvatar?: boolean;
     showTimestamp?: boolean;
+    theme?: IChatTheme;
 }
-declare function MessageItem({ message, currentUser, showAvatar, showTimestamp, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+declare function MessageItem({ message, currentUser, showAvatar, showTimestamp, theme, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+
+interface ThinkingIndicatorProps {
+    /** Last message the user sent — used to pick contextual phrases */
+    lastUserMessage?: string;
+    /** Chat theme for color matching */
+    theme?: IChatTheme;
+    /** Show avatar next to the indicator */
+    showAvatar?: boolean;
+}
+declare function ThinkingIndicator({ lastUserMessage, theme, showAvatar, }: ThinkingIndicatorProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListProps {
     messages: IMessage[];
@@ -261,8 +266,13 @@ interface MessageListProps {
     onLoadMore?: () => void;
     hasMore?: boolean;
     isLoadingMore?: boolean;
+    theme?: IChatTheme;
+    /** Called when a quick-start action button is clicked — sends the text as a message */
+    onQuickAction?: (text: string) => void;
+    /** True when user sent a message and bot response hasn't arrived yet */
+    isBotThinking?: boolean;
 }
-declare function MessageList({ messages, currentUser, isLoading, isTyping, typingUser, autoScroll, onLoadMore, hasMore, isLoadingMore, }: MessageListProps): react_jsx_runtime.JSX.Element;
+declare function MessageList({ messages, currentUser, isLoading, isTyping, typingUser, autoScroll, onLoadMore, hasMore, isLoadingMore, theme, onQuickAction, isBotThinking, }: MessageListProps): react_jsx_runtime.JSX.Element;
 
 interface TypingIndicatorProps {
     isTyping: boolean;
@@ -285,7 +295,8 @@ interface PreChatFormProps {
     onClose: () => void;
 }
 /**
- * PreChatForm component for collecting user information before starting chat
+ * PreChatForm component for collecting user information before starting chat.
+ * Styled to match the Xcelsior website design system.
  */
 declare function PreChatForm({ onSubmit, className, initialName, initialEmail, onMinimize, onClose, }: PreChatFormProps): react_jsx_runtime.JSX.Element;
 
@@ -302,17 +313,6 @@ interface UseWebSocketReturn {
  */
 declare function useWebSocket(config: IChatConfig, externalWebSocket?: WebSocket | null): UseWebSocketReturn;
 
-interface UseMessagesReturn {
-    messages: IMessage[];
-    addMessage: (message: IMessage) => void;
-    updateMessageStatus: (messageId: string, status: IMessage['status']) => void;
-    clearMessages: () => void;
-    isLoading: boolean;
-    error: Error | null;
-    loadMore: () => Promise<void>;
-    hasMore: boolean;
-    isLoadingMore: boolean;
-}
 declare function useMessages(websocket: UseWebSocketReturn, config: IChatConfig): UseMessagesReturn;
 
 interface UseTypingIndicatorReturn {
@@ -334,4 +334,4 @@ declare function fetchMessages(baseUrl: string, params: FetchMessagesParams, hea
     nextPageToken: string | undefined;
 }>;
 
-export { Chat, ChatHeader, ChatInput, ChatWidget, type ChatWidgetProps, type ChatWidgetState, type ConversationChannel, type ConversationPriority, type ConversationStatus, type IApiResponse, type IChatConfig, type IConversation, type IFileUploadConfig, type IMessage, type IReadMessageData, type ISendMessageData, type ITypingData, type IUploadedFile, type IUser, type IWebSocketMessage, MessageItem, MessageList, type MessageStatus, type MessageType, PreChatForm, TypingIndicator, type UseChatWidgetStateOptions, type UseChatWidgetStateReturn, fetchMessages, useChatWidgetState, useFileUpload, useMessages, useTypingIndicator, useWebSocket };
+export { Chat, ChatHeader, ChatInput, ChatWidget, type ChatWidgetProps, type ChatWidgetState, type ConversationChannel, type ConversationPriority, type ConversationStatus, type IApiResponse, type IChatConfig, type IConversation, type IFileUploadConfig, type IMessage, type IReadMessageData, type ISendMessageData, type ITypingData, type IUploadedFile, type IUser, type IWebSocketMessage, MarkdownMessage, MessageItem, MessageList, type MessageStatus, type MessageType, PreChatForm, ThinkingIndicator, type ThinkingIndicatorProps, TypingIndicator, type UseChatWidgetStateOptions, type UseChatWidgetStateReturn, type UseMessagesReturn, fetchMessages, useChatWidgetState, useFileUpload, useMessages, useTypingIndicator, useWebSocket };

package/dist/index.d.ts

@@ -13,14 +13,16 @@ interface IMessage {
     id: string;
     conversationId: string;
     senderId: string;
-    senderType: 'customer' | 'agent' | 'system';
+    senderType: 'customer' | 'agent' | 'bot' | 'system';
     content: string;
     messageType: MessageType;
     createdAt: string;
     status: MessageStatus;
+    feedback?: 'good' | 'wrong' | 'corrected' | null;
+    confidence?: number | null;
     metadata?: Record<string, unknown>;
 }
-type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived';
+type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived' | 'bot_handling' | 'pending_agent' | 'agent_active';
 type ConversationPriority = 'low' | 'medium' | 'high' | 'urgent';
 type ConversationChannel = 'web' | 'mobile' | 'email';
 interface IConversation {
@@ -42,7 +44,7 @@ interface IConversation {
     metadata?: Record<string, unknown>;
 }
 interface IWebSocketMessage {
-    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system';
+    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system' | 'escalation_requested' | 'bot_response' | 'conversation_updated';
     data: any;
 }
 interface ISendMessageData {
@@ -71,11 +73,25 @@ interface IUploadedFile {
     type: string;
     markdown?: string;
 }
+interface IChatTheme {
+    primary?: string;
+    primaryStrong?: string;
+    background?: string;
+    backgroundAlt?: string;
+    text?: string;
+    textMuted?: string;
+    statusPositive?: string;
+    statusCaution?: string;
+    statusNegative?: string;
+    borderColor?: string;
+}
+type WidgetPosition = 'left' | 'right' | 'auto';
+type IdentityCollectionMode = 'progressive' | 'form' | 'none';
 interface IChatConfig {
     websocketUrl: string;
     conversationId?: string;
     apiKey: string;
-    currentUser: IUser;
+    currentUser?: IUser;
     fileUpload?: IFileUploadConfig;
     httpApiUrl?: string;
     headers?: Record<string, string>;
@@ -89,17 +105,33 @@ interface IChatConfig {
      * @default false
      */
     disableWebSocket?: boolean;
+    theme?: IChatTheme;
+    position?: WidgetPosition;
+    identityCollection?: IdentityCollectionMode;
     onMessageSent?: (message: IMessage) => void;
     onMessageReceived?: (message: IMessage) => void;
     onConversationChange?: (conversation: IConversation) => void;
     onConnectionChange?: (connected: boolean) => void;
     onError?: (error: Error) => void;
+    onConversationRated?: (rating: 'positive' | 'negative') => void;
     toast?: {
         success: (message: string) => void;
         error: (message: string) => void;
         info: (message: string) => void;
     };
 }
+interface UseMessagesReturn {
+    messages: IMessage[];
+    addMessage: (message: IMessage) => void;
+    updateMessageStatus: (messageId: string, status: IMessage['status']) => void;
+    clearMessages: () => void;
+    isLoading: boolean;
+    error: Error | null;
+    loadMore: () => Promise<void>;
+    hasMore: boolean;
+    isLoadingMore: boolean;
+    isBotThinking: boolean;
+}
 interface IApiResponse<T> {
     success: boolean;
     data?: T;
@@ -115,26 +147,14 @@ interface IApiResponse<T> {
 interface ChatWidgetProps {
     config: IChatConfig;
     className?: string;
-    /**
-     * Variant of the chat widget:
-     * - 'popover': Fixed positioned floating widget (default)
-     * - 'fullPage': Full page layout that fills the container
-     */
     variant?: 'popover' | 'fullPage';
-    /**
-     * External WebSocket connection (for agents with global connection)
-     */
     externalWebSocket?: WebSocket | null;
-    /**
-     * Callback when user wants to minimize the widget
-     */
     onMinimize?: () => void;
-    /**
-     * Callback when user wants to close the widget
-     */
     onClose?: () => void;
+    /** Resolved position (left or right) from the parent Chat component */
+    resolvedPosition?: 'left' | 'right';
 }
-declare function ChatWidget({ config, className, variant, externalWebSocket, onMinimize, onClose, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
+declare function ChatWidget({ config, className, variant, externalWebSocket, onMinimize, onClose, resolvedPosition, }: ChatWidgetProps): react_jsx_runtime.JSX.Element;
 
 type ChatWidgetState = 'open' | 'minimized' | 'closed' | 'undefined';
 interface UseChatWidgetStateOptions {
@@ -173,57 +193,25 @@ interface UseChatWidgetStateReturn {
 declare function useChatWidgetState({ state: controlledState, defaultState, onStateChange, }: UseChatWidgetStateOptions): UseChatWidgetStateReturn;
 
 interface ChatWidgetWrapperProps {
-    /**
-     * Base configuration for the chat widget (without user info and conversationId)
-     */
-    config: Omit<IChatConfig, 'currentUser' | 'conversationId' | 'userId'> & {
-        currentUser?: Partial<IUser>;
+    config: Omit<IChatConfig, 'conversationId'> & {
         conversationId?: string;
     };
-    /**
-     * Custom className for the wrapper
-     */
     className?: string;
-    /**
-     * Storage key prefix for persisting user data
-     * Defaults to 'xcelsior_chat'
-     */
     storageKeyPrefix?: string;
-    /**
-     * Callback when user submits the pre-chat form
-     */
     onPreChatSubmit?: (user: IUser) => void;
-    /**
-     * Controlled state. When provided, the component is controlled.
-     * - 'open': Fully open with chat interface
-     * - 'minimized': Show bubble button only
-     * - 'closed': Fully hidden
-     */
     state?: ChatWidgetState;
-    /**
-     * Default state for uncontrolled mode
-     * @default 'minimized'
-     */
     defaultState?: ChatWidgetState;
-    /**
-     * Callback when state changes
-     */
     onStateChange?: (state: ChatWidgetState) => void;
 }
-/**
- * Chat component that handles:
- * - Automatic conversation ID generation
- * - Pre-chat form for collecting user information
- * - Session persistence in localStorage
- */
 declare function Chat({ config, className, storageKeyPrefix, onPreChatSubmit, state, defaultState, onStateChange, }: ChatWidgetWrapperProps): react_jsx_runtime.JSX.Element | null;
 
 interface ChatHeaderProps {
     agent?: IUser;
     onClose?: () => void;
     onMinimize?: () => void;
+    theme?: IChatTheme;
 }
-declare function ChatHeader({ agent, onClose, onMinimize }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
+declare function ChatHeader({ agent, onClose, onMinimize, theme }: ChatHeaderProps): react_jsx_runtime.JSX.Element;
 
 interface UseFileUploadReturn {
     uploadFile: (file: File) => Promise<IUploadedFile | null>;
@@ -243,13 +231,30 @@ interface ChatInputProps {
 }
 declare function ChatInput({ onSend, onTyping, config, fileUpload, disabled, }: ChatInputProps): react_jsx_runtime.JSX.Element;
 
+interface MarkdownMessageProps {
+    content: string;
+    theme?: IChatTheme;
+}
+declare function MarkdownMessage({ content, theme }: MarkdownMessageProps): react_jsx_runtime.JSX.Element;
+
 interface MessageItemProps {
     message: IMessage;
     currentUser: IUser;
     showAvatar?: boolean;
     showTimestamp?: boolean;
+    theme?: IChatTheme;
 }
-declare function MessageItem({ message, currentUser, showAvatar, showTimestamp, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+declare function MessageItem({ message, currentUser, showAvatar, showTimestamp, theme, }: MessageItemProps): react_jsx_runtime.JSX.Element;
+
+interface ThinkingIndicatorProps {
+    /** Last message the user sent — used to pick contextual phrases */
+    lastUserMessage?: string;
+    /** Chat theme for color matching */
+    theme?: IChatTheme;
+    /** Show avatar next to the indicator */
+    showAvatar?: boolean;
+}
+declare function ThinkingIndicator({ lastUserMessage, theme, showAvatar, }: ThinkingIndicatorProps): react_jsx_runtime.JSX.Element;
 
 interface MessageListProps {
     messages: IMessage[];
@@ -261,8 +266,13 @@ interface MessageListProps {
     onLoadMore?: () => void;
     hasMore?: boolean;
     isLoadingMore?: boolean;
+    theme?: IChatTheme;
+    /** Called when a quick-start action button is clicked — sends the text as a message */
+    onQuickAction?: (text: string) => void;
+    /** True when user sent a message and bot response hasn't arrived yet */
+    isBotThinking?: boolean;
 }
-declare function MessageList({ messages, currentUser, isLoading, isTyping, typingUser, autoScroll, onLoadMore, hasMore, isLoadingMore, }: MessageListProps): react_jsx_runtime.JSX.Element;
+declare function MessageList({ messages, currentUser, isLoading, isTyping, typingUser, autoScroll, onLoadMore, hasMore, isLoadingMore, theme, onQuickAction, isBotThinking, }: MessageListProps): react_jsx_runtime.JSX.Element;
 
 interface TypingIndicatorProps {
     isTyping: boolean;
@@ -285,7 +295,8 @@ interface PreChatFormProps {
     onClose: () => void;
 }
 /**
- * PreChatForm component for collecting user information before starting chat
+ * PreChatForm component for collecting user information before starting chat.
+ * Styled to match the Xcelsior website design system.
  */
 declare function PreChatForm({ onSubmit, className, initialName, initialEmail, onMinimize, onClose, }: PreChatFormProps): react_jsx_runtime.JSX.Element;
 
@@ -302,17 +313,6 @@ interface UseWebSocketReturn {
  */
 declare function useWebSocket(config: IChatConfig, externalWebSocket?: WebSocket | null): UseWebSocketReturn;
 
-interface UseMessagesReturn {
-    messages: IMessage[];
-    addMessage: (message: IMessage) => void;
-    updateMessageStatus: (messageId: string, status: IMessage['status']) => void;
-    clearMessages: () => void;
-    isLoading: boolean;
-    error: Error | null;
-    loadMore: () => Promise<void>;
-    hasMore: boolean;
-    isLoadingMore: boolean;
-}
 declare function useMessages(websocket: UseWebSocketReturn, config: IChatConfig): UseMessagesReturn;
 
 interface UseTypingIndicatorReturn {
@@ -334,4 +334,4 @@ declare function fetchMessages(baseUrl: string, params: FetchMessagesParams, hea
     nextPageToken: string | undefined;
 }>;
 
-export { Chat, ChatHeader, ChatInput, ChatWidget, type ChatWidgetProps, type ChatWidgetState, type ConversationChannel, type ConversationPriority, type ConversationStatus, type IApiResponse, type IChatConfig, type IConversation, type IFileUploadConfig, type IMessage, type IReadMessageData, type ISendMessageData, type ITypingData, type IUploadedFile, type IUser, type IWebSocketMessage, MessageItem, MessageList, type MessageStatus, type MessageType, PreChatForm, TypingIndicator, type UseChatWidgetStateOptions, type UseChatWidgetStateReturn, fetchMessages, useChatWidgetState, useFileUpload, useMessages, useTypingIndicator, useWebSocket };
+export { Chat, ChatHeader, ChatInput, ChatWidget, type ChatWidgetProps, type ChatWidgetState, type ConversationChannel, type ConversationPriority, type ConversationStatus, type IApiResponse, type IChatConfig, type IConversation, type IFileUploadConfig, type IMessage, type IReadMessageData, type ISendMessageData, type ITypingData, type IUploadedFile, type IUser, type IWebSocketMessage, MarkdownMessage, MessageItem, MessageList, type MessageStatus, type MessageType, PreChatForm, ThinkingIndicator, type ThinkingIndicatorProps, TypingIndicator, type UseChatWidgetStateOptions, type UseChatWidgetStateReturn, type UseMessagesReturn, fetchMessages, useChatWidgetState, useFileUpload, useMessages, useTypingIndicator, useWebSocket };