@xcelsior/ui-chat 1.0.1

package/src/hooks/useWebSocket.ts

@@ -0,0 +1,209 @@
+import { useEffect, useRef, useState, useCallback } from 'react';
+import type { IChatConfig, IWebSocketMessage } from '../types';
+
+export interface UseWebSocketReturn {
+    isConnected: boolean;
+    sendMessage: (action: string, data: any) => void;
+    lastMessage: IWebSocketMessage | null;
+    error: Error | null;
+    reconnect: () => void;
+}
+
+/**
+ * Hook for WebSocket connection in chat widget.
+ * Can use an external WebSocket connection (for agents) via the externalWebSocket prop.
+ */
+export function useWebSocket(
+    config: IChatConfig,
+    externalWebSocket?: WebSocket | null
+): UseWebSocketReturn {
+    const [isConnected, setIsConnected] = useState(false);
+    const [lastMessage, setLastMessage] = useState<IWebSocketMessage | null>(null);
+    const [error, setError] = useState<Error | null>(null);
+    const wsRef = useRef<WebSocket | null>(null);
+    const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+    const reconnectAttemptsRef = useRef(0);
+    const messageHandlerRef = useRef<((event: MessageEvent) => void) | null>(null);
+    const maxReconnectAttempts = 5;
+    const reconnectDelay = 3000;
+
+    // Use external WebSocket if provided (for agents)
+    const isUsingExternalWs = !!externalWebSocket;
+
+    // biome-ignore lint/correctness/useExhaustiveDependencies: dependencies managed manually
+    const subscribeToMessage = useCallback((webSocket: WebSocket) => {
+        // Remove previous listener if it exists
+        if (messageHandlerRef.current) {
+            webSocket.removeEventListener('message', messageHandlerRef.current);
+        }
+
+        // Create new message handler
+        const handler = (event: MessageEvent) => {
+            try {
+                const message: IWebSocketMessage = JSON.parse(event.data);
+                setLastMessage(message);
+
+                // Handle different message types
+                if (message.type === 'message' && message.data) {
+                    config.onMessageReceived?.(message.data);
+                } else if (message.type === 'error') {
+                    const err = new Error(message.data?.message || 'WebSocket error');
+                    setError(err);
+                    config.onError?.(err);
+                }
+            } catch (err) {
+                console.error('Failed to parse WebSocket message:', err);
+            }
+        };
+
+        // Add the new listener
+        webSocket.addEventListener('message', handler);
+        messageHandlerRef.current = handler;
+
+        // Return cleanup function
+        return () => {
+            webSocket.removeEventListener('message', handler);
+            if (messageHandlerRef.current === handler) {
+                messageHandlerRef.current = null;
+            }
+        };
+    }, []);
+
+    // biome-ignore lint/correctness/useExhaustiveDependencies: dependencies managed manually
+    const connect = useCallback(() => {
+        console.log('connecting to WebSocket...', config.currentUser, config.conversationId);
+        try {
+            // Clean up existing connection
+            if (wsRef.current) {
+                // Remove message listener before closing
+                if (messageHandlerRef.current) {
+                    wsRef.current.removeEventListener('message', messageHandlerRef.current);
+                    messageHandlerRef.current = null;
+                }
+                wsRef.current.close();
+            }
+
+            // Build WebSocket URL with query parameters
+            const url = new URL(config.websocketUrl);
+            url.searchParams.set('user', JSON.stringify(config.currentUser));
+            if (config.conversationId) {
+                url.searchParams.set('conversationId', config.conversationId);
+            }
+            if (config.apiKey) {
+                url.searchParams.set('apiKey', config.apiKey);
+            }
+
+            const ws = new WebSocket(url.toString());
+
+            ws.onopen = () => {
+                console.log('WebSocket connected');
+                setIsConnected(true);
+                setError(null);
+                reconnectAttemptsRef.current = 0;
+                config.onConnectionChange?.(true);
+            };
+
+            ws.onerror = (event) => {
+                console.error('WebSocket error:', event);
+                const err = new Error('WebSocket connection error');
+                setError(err);
+                config.onError?.(err);
+            };
+
+            ws.onclose = (event) => {
+                console.log('WebSocket closed:', event.code, event.reason);
+                setIsConnected(false);
+                config.onConnectionChange?.(false);
+                wsRef.current = null;
+
+                // Attempt to reconnect if not a normal closure
+                if (event.code !== 1000 && reconnectAttemptsRef.current < maxReconnectAttempts) {
+                    reconnectAttemptsRef.current += 1;
+                    console.log(
+                        `Reconnecting... (${reconnectAttemptsRef.current}/${maxReconnectAttempts})`
+                    );
+                    reconnectTimeoutRef.current = setTimeout(() => {
+                        connect();
+                    }, reconnectDelay);
+                }
+            };
+
+            subscribeToMessage(ws);
+            wsRef.current = ws ?? null;
+        } catch (err) {
+            console.error('Failed to create WebSocket connection:', err);
+            const error = err instanceof Error ? err : new Error('Failed to connect');
+            setError(error);
+            config.onError?.(error);
+        }
+    }, [JSON.stringify([config.currentUser, config.conversationId])]);
+
+    const sendMessage = useCallback(
+        (action: string, data: any) => {
+            if (!wsRef.current || wsRef.current.readyState !== WebSocket.OPEN) {
+                console.error('WebSocket is not connected');
+                config.toast?.error('Not connected to chat server');
+                return;
+            }
+
+            try {
+                wsRef.current.send(
+                    JSON.stringify({
+                        action,
+                        data,
+                    })
+                );
+            } catch (err) {
+                console.error('Failed to send message:', err);
+                const error = err instanceof Error ? err : new Error('Failed to send message');
+                setError(error);
+                config.onError?.(error);
+            }
+        },
+        [config]
+    );
+
+    const reconnect = useCallback(() => {
+        reconnectAttemptsRef.current = 0;
+        connect();
+    }, [connect]);
+
+    useEffect(() => {
+        if (isUsingExternalWs) {
+            setIsConnected(externalWebSocket?.readyState === WebSocket.OPEN || false);
+            wsRef.current = externalWebSocket;
+            const cleanup = subscribeToMessage(externalWebSocket);
+            return cleanup;
+        }
+
+        connect();
+
+        // Cleanup on unmount
+        return () => {
+            if (reconnectTimeoutRef.current) {
+                clearTimeout(reconnectTimeoutRef.current);
+            }
+            if (wsRef.current) {
+                // Remove message listener before closing
+                if (messageHandlerRef.current) {
+                    wsRef.current.removeEventListener('message', messageHandlerRef.current);
+                    messageHandlerRef.current = null;
+                }
+                wsRef.current.close(1000, 'Component unmounted');
+            }
+        };
+    }, [connect, isUsingExternalWs, externalWebSocket, subscribeToMessage]);
+
+    // Use external connection state if available
+    const effectiveIsConnected = isUsingExternalWs
+        ? externalWebSocket?.readyState === WebSocket.OPEN || false
+        : isConnected;
+
+    return {
+        isConnected: effectiveIsConnected,
+        sendMessage,
+        lastMessage,
+        error,
+        reconnect,
+    };
+}

package/src/index.tsx

@@ -0,0 +1,46 @@
+// Main components
+export { ChatWidget } from './components/ChatWidget';
+export type { ChatWidgetProps } from './components/ChatWidget';
+export { Chat } from './components/Chat';
+
+// Individual components (for custom implementations)
+export { ChatHeader } from './components/ChatHeader';
+export { ChatInput } from './components/ChatInput';
+export { MessageItem } from './components/MessageItem';
+export { MessageList } from './components/MessageList';
+export { TypingIndicator } from './components/TypingIndicator';
+export { PreChatForm } from './components/PreChatForm';
+
+// Hooks
+export { useWebSocket } from './hooks/useWebSocket';
+export type { UseWebSocketReturn } from './hooks/useWebSocket';
+export { useMessages } from './hooks/useMessages';
+export type { UseMessagesReturn } from './hooks/useMessages';
+export { useFileUpload } from './hooks/useFileUpload';
+export type { UseFileUploadReturn } from './hooks/useFileUpload';
+export { useTypingIndicator } from './hooks/useTypingIndicator';
+export type { UseTypingIndicatorReturn } from './hooks/useTypingIndicator';
+
+// Utilities
+export { fetchMessages } from './utils/api';
+export type { FetchMessagesParams } from './utils/api';
+
+// Types
+export type {
+    IUser,
+    IMessage,
+    IConversation,
+    IChatConfig,
+    IWebSocketMessage,
+    ISendMessageData,
+    ITypingData,
+    IReadMessageData,
+    IFileUploadConfig,
+    IUploadedFile,
+    IApiResponse,
+    MessageType,
+    MessageStatus,
+    ConversationStatus,
+    ConversationPriority,
+    ConversationChannel,
+} from './types';

package/src/types.ts

@@ -0,0 +1,145 @@
+// User types
+export interface IUser {
+    name: string;
+    email: string;
+    avatar?: string;
+    type: 'customer' | 'agent';
+    status?: 'online' | 'offline' | 'away' | 'busy';
+}
+
+// Message types
+export type MessageType = 'text' | 'image' | 'file' | 'system';
+export type MessageStatus = 'sent' | 'delivered' | 'read';
+
+export interface IMessage {
+    id: string;
+    conversationId: string;
+    senderId: string;
+    senderType: 'customer' | 'agent' | 'system';
+    content: string;
+    messageType: MessageType;
+    createdAt: string;
+    status: MessageStatus;
+    metadata?: Record<string, unknown>;
+}
+
+// Conversation types
+export type ConversationStatus = 'open' | 'pending' | 'closed' | 'archived';
+export type ConversationPriority = 'low' | 'medium' | 'high' | 'urgent';
+export type ConversationChannel = 'web' | 'mobile' | 'email';
+
+export interface IConversation {
+    id: string;
+    customerId: string;
+    assignedAgentId?: string;
+    status: ConversationStatus;
+    priority: ConversationPriority;
+    subject?: string;
+    channel: ConversationChannel;
+    tags?: string[];
+    createdAt: string;
+    updatedAt: string;
+    closedAt?: string;
+    lastMessageAt?: string;
+    messageCount?: number;
+    unreadCount?: number;
+    satisfaction?: 1 | 2 | 3 | 4 | 5;
+    metadata?: Record<string, unknown>;
+}
+
+// WebSocket message types
+export interface IWebSocketMessage {
+    type: 'message' | 'typing' | 'read' | 'connected' | 'error' | 'system';
+    data: any;
+}
+
+export interface ISendMessageData {
+    conversationId: string;
+    content: string;
+    messageType?: MessageType;
+}
+
+export interface ITypingData {
+    conversationId: string;
+    isTyping: boolean;
+}
+
+export interface IReadMessageData {
+    messageId: string;
+    conversationId: string;
+}
+
+// File upload types
+export interface IFileUploadConfig {
+    uploadUrl: string;
+    maxFileSize?: number; // in bytes, default 5MB
+    allowedTypes?: string[]; // default ['image/*', 'application/pdf', etc.]
+    headers?: Record<string, string>; // additional headers for upload request
+}
+
+export interface IUploadedFile {
+    url: string;
+    name: string;
+    size: number;
+    type: string;
+    markdown?: string;
+}
+
+// Chat widget configuration
+export interface IChatConfig {
+    // WebSocket connection
+    websocketUrl: string;
+    conversationId?: string;
+    apiKey: string;
+
+    // User information
+    currentUser: IUser;
+
+    // File upload
+    fileUpload?: IFileUploadConfig;
+
+    // REST API for fetching data
+    httpApiUrl?: string;
+    headers?: Record<string, string>;
+
+    // Features
+    enableEmoji?: boolean;
+    enableFileUpload?: boolean;
+    enableTypingIndicator?: boolean;
+    enableReadReceipts?: boolean;
+
+    // WebSocket management
+    /**
+     * For agents, set this to true to disable creating a WebSocket connection in the chat widget.
+     * Agents should have a global WebSocket connection instead.
+     * @default false
+     */
+    disableWebSocket?: boolean;
+
+    // Callbacks
+    onMessageSent?: (message: IMessage) => void;
+    onMessageReceived?: (message: IMessage) => void;
+    onConversationChange?: (conversation: IConversation) => void;
+    onConnectionChange?: (connected: boolean) => void;
+    onError?: (error: Error) => void;
+
+    // Toast notifications
+    toast?: {
+        success: (message: string) => void;
+        error: (message: string) => void;
+        info: (message: string) => void;
+    };
+}
+
+// API Response types
+export interface IApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+    pagination?: {
+        nextPageToken?: string;
+    };
+}

package/src/utils/api.ts

@@ -0,0 +1,43 @@
+import axios from 'axios';
+import type { IMessage, IApiResponse } from '../types';
+
+export interface FetchMessagesParams {
+    conversationId: string;
+    limit?: number;
+    pageToken?: string;
+}
+
+/**
+ * Fetch messages for a conversation from the REST API
+ */
+export async function fetchMessages(
+    baseUrl: string,
+    params: FetchMessagesParams,
+    headers?: Record<string, string>
+) {
+    try {
+        const response = await axios.get<IApiResponse<IMessage[]>>(`${baseUrl}/messages`, {
+            params: {
+                conversationId: params.conversationId,
+                limit: params.limit || 50,
+                pageToken: params.pageToken,
+            },
+            headers: {
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+        });
+
+        return {
+            data: response.data.data ?? [],
+            nextPageToken: response.data.pagination?.nextPageToken,
+        };
+    } catch (error) {
+        if (axios.isAxiosError(error)) {
+            throw new Error(
+                error.response?.data?.error?.message || error.message || 'Failed to fetch messages'
+            );
+        }
+        throw error;
+    }
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+    "extends": "../../config/typescript/react.json",
+    "include": ["."],
+    "exclude": ["dist", "build", "node_modules"]
+}

package/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['cjs', 'esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+    external: ['react', 'react-dom', '@xcelsior/design-system'],
+    outDir: 'dist',
+});