@elqnt/chat 2.0.7 → 3.0.0

package/README.md

@@ -0,0 +1,386 @@
+# @elqnt/chat
+
+Platform-agnostic chat SDK for React and React Native. Uses POST + SSE (no WebSocket) for reliable real-time communication.
+
+## Installation
+
+```bash
+pnpm add @elqnt/chat
+```
+
+## Quick Start
+
+```tsx
+import { useChat } from "@elqnt/chat/hooks";
+
+function ChatComponent() {
+  const {
+    connect,
+    disconnect,
+    sendMessage,
+    messages,
+    isConnected,
+    startChat,
+  } = useChat({
+    baseUrl: "https://api.example.com/chat",
+    orgId: "org-123",
+    userId: "user-456",
+  });
+
+  useEffect(() => {
+    connect();
+    return () => disconnect();
+  }, []);
+
+  const handleSend = async (text: string) => {
+    await sendMessage(text);
+  };
+
+  return (
+    <div>
+      <ConnectionStatus connected={isConnected} />
+      <MessageList messages={messages} />
+      <MessageInput onSend={handleSend} />
+    </div>
+  );
+}
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Your App                              │
+├─────────────────────────────────────────────────────────────┤
+│                      useChat Hook                            │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   State     │  │   Events    │  │   Chat Operations   │  │
+│  │  messages   │  │  onMessage  │  │   sendMessage       │  │
+│  │  chatKey    │  │  on(type)   │  │   startChat         │  │
+│  │  isConnected│  │             │  │   loadChat          │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+├─────────────────────────────────────────────────────────────┤
+│                    Transport Layer                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
+│  │  SSE         │  │  SSE-Fetch   │  │  WhatsApp        │   │
+│  │  (Browser)   │  │  (React      │  │  (Backend        │   │
+│  │              │  │   Native)    │  │   Webhook)       │   │
+│  └──────────────┘  └──────────────┘  └──────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│                    Chat Server                               │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  POST /create, /send, /load, /end, /typing, /event   │   │
+│  │  GET  /stream (SSE)                                   │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Exports
+
+### `/hooks` - React Hooks
+
+```typescript
+import { useChat } from "@elqnt/chat/hooks";
+```
+
+**useChat Options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `baseUrl` | `string` | Yes | Chat server URL |
+| `orgId` | `string` | Yes | Organization ID |
+| `userId` | `string` | Yes | User ID |
+| `clientType` | `"customer" \| "humanAgent" \| "observer"` | No | Client type (default: "customer") |
+| `transport` | `ChatTransport \| "sse" \| "sse-fetch"` | No | Transport to use |
+| `onMessage` | `(event: ChatEvent) => void` | No | Event callback |
+| `onError` | `(error: TransportError) => void` | No | Error callback |
+| `autoConnect` | `boolean` | No | Connect on mount |
+| `debug` | `boolean` | No | Enable logging |
+
+**useChat Return:**
+
+```typescript
+interface UseChatReturn {
+  // Connection
+  connect: () => Promise<void>;
+  disconnect: () => void;
+  connectionState: TransportState;
+  isConnected: boolean;
+
+  // Chat Operations
+  startChat: (metadata?: Record<string, unknown>) => Promise<string>;
+  loadChat: (chatKey: string) => Promise<void>;
+  sendMessage: (content: string, attachments?: unknown[]) => Promise<void>;
+  endChat: (reason?: string) => Promise<void>;
+
+  // Typing Indicators
+  startTyping: () => void;
+  stopTyping: () => void;
+
+  // State
+  currentChat: Chat | null;
+  chatKey: string | null;
+  messages: ChatMessage[];
+  error: TransportError | null;
+  metrics: ConnectionMetrics;
+
+  // Events
+  on: (eventType: string, handler: (event: ChatEvent) => void) => () => void;
+  clearError: () => void;
+}
+```
+
+### `/api` - Low-Level API Functions
+
+```typescript
+import {
+  // Browser API (uses @elqnt/api-client)
+  getChatHistoryApi,
+  getChatApi,
+  updateChatApi,
+  deleteChatApi,
+  getActiveChatsApi,
+  getActiveChatsCountApi,
+
+  // Stream API (direct HTTP)
+  createChat,
+  sendChatMessage,
+  loadChat,
+  endChat,
+  sendTypingIndicator,
+  sendEvent,
+} from "@elqnt/chat/api";
+```
+
+### `/models` - TypeScript Types
+
+```typescript
+import type {
+  Chat,
+  ChatMessage,
+  ChatEvent,
+  ChatEventTypeTS,
+  ChatUser,
+  ChatStatusTS,
+  MessageStatusTS,
+  Attachment,
+} from "@elqnt/chat/models";
+```
+
+### `/transport` - Transport Adapters
+
+```typescript
+import {
+  createSSETransport,      // Browser EventSource
+  createFetchSSETransport, // React Native / Fetch-based
+  createWhatsAppTransport, // WhatsApp Business API (stub)
+} from "@elqnt/chat/transport";
+
+import type {
+  ChatTransport,
+  TransportConfig,
+  TransportState,
+  TransportError,
+  ConnectionMetrics,
+} from "@elqnt/chat/transport";
+```
+
+## Transport Options
+
+### Browser (Default)
+
+Uses native `EventSource` for SSE. This is the default and recommended transport for browser environments.
+
+```typescript
+const chat = useChat({
+  baseUrl: "...",
+  orgId: "...",
+  userId: "...",
+  // transport defaults to "sse"
+});
+```
+
+### React Native
+
+Uses `fetch` with `ReadableStream` for SSE. Required for React Native since it doesn't have native `EventSource`.
+
+```typescript
+import { createFetchSSETransport } from "@elqnt/chat/transport";
+
+const transport = createFetchSSETransport();
+
+const chat = useChat({
+  baseUrl: "...",
+  orgId: "...",
+  userId: "...",
+  transport,
+});
+```
+
+### Custom Transport
+
+Implement the `ChatTransport` interface for custom integrations:
+
+```typescript
+import type { ChatTransport } from "@elqnt/chat/transport";
+
+const customTransport: ChatTransport = {
+  async connect(config) { /* ... */ },
+  disconnect() { /* ... */ },
+  async send(event) { /* ... */ },
+  async sendMessage(message) { /* ... */ },
+  onMessage(handler) { /* ... */ },
+  on(eventType, handler) { /* ... */ },
+  getState() { /* ... */ },
+  getMetrics() { /* ... */ },
+  getError() { /* ... */ },
+  clearError() { /* ... */ },
+};
+```
+
+## Event Types
+
+Subscribe to specific events:
+
+```typescript
+const { on } = useChat({ ... });
+
+// Subscribe to typing events
+const unsubscribe = on("typing", (event) => {
+  console.log("User typing:", event.userId);
+});
+
+// Clean up
+unsubscribe();
+```
+
+Common event types:
+
+| Event | Description |
+|-------|-------------|
+| `message` | New message received |
+| `typing` | User started typing |
+| `stopped_typing` | User stopped typing |
+| `new_chat_created` | New chat session created |
+| `load_chat_response` | Chat loaded |
+| `chat_ended` | Chat session ended |
+| `human_agent_joined` | Human agent joined chat |
+| `human_agent_left` | Human agent left chat |
+| `agent_execution_started` | AI agent started processing |
+| `agent_execution_ended` | AI agent finished processing |
+
+## WhatsApp Integration
+
+WhatsApp Business API integration happens via backend webhooks. The `createWhatsAppTransport` is a stub that documents the integration pattern.
+
+### Backend Setup
+
+1. Create a Meta Business App with WhatsApp integration
+2. Configure webhook URL pointing to your chat service
+3. Implement webhook handlers:
+
+```go
+// Webhook verification
+func HandleWhatsAppWebhook(w http.ResponseWriter, r *http.Request) {
+    if r.Method == "GET" {
+        verifyToken := r.URL.Query().Get("hub.verify_token")
+        if verifyToken == os.Getenv("WHATSAPP_VERIFY_TOKEN") {
+            w.Write([]byte(r.URL.Query().Get("hub.challenge")))
+            return
+        }
+        http.Error(w, "Invalid verify token", 403)
+        return
+    }
+
+    // Handle incoming message
+    var payload WhatsAppPayload
+    json.NewDecoder(r.Body).Decode(&payload)
+
+    // Map to chat event and publish
+    chatEvent := mapWhatsAppToChatEvent(payload)
+    publishToChatService(chatEvent)
+}
+```
+
+### Helper Functions
+
+```typescript
+import { mapWhatsAppToChatEvent } from "@elqnt/chat/transport";
+
+// In your webhook handler
+const events = mapWhatsAppToChatEvent(webhookPayload, orgId);
+events.forEach(event => publishToChatService(event));
+```
+
+## Migration from v2
+
+### Breaking Changes
+
+1. **UI Components Removed** - Build your own UI
+2. **Contexts Removed** - Use `useChat` hook directly
+3. **WebSocket Removed** - SSE only (more reliable)
+4. **Redux Integration Removed** - Use hook state
+
+### Migration Steps
+
+```tsx
+// Before (v2)
+import { WebSocketChatCustomerProvider, useWebSocketChatCustomer } from "@elqnt/chat";
+
+function App() {
+  return (
+    <WebSocketChatCustomerProvider config={...}>
+      <ChatComponent />
+    </WebSocketChatCustomerProvider>
+  );
+}
+
+function ChatComponent() {
+  const { messages, sendMessage } = useWebSocketChatCustomer();
+  return <ChatUI messages={messages} onSend={sendMessage} />;
+}
+
+// After (v3)
+import { useChat } from "@elqnt/chat/hooks";
+
+function ChatComponent() {
+  const { messages, sendMessage, connect, disconnect } = useChat({
+    baseUrl: "...",
+    orgId: "...",
+    userId: "...",
+  });
+
+  useEffect(() => {
+    connect();
+    return () => disconnect();
+  }, []);
+
+  return <ChatUI messages={messages} onSend={sendMessage} />;
+}
+```
+
+### Removed Exports
+
+- `WebSocketChatCustomerProvider`
+- `WebSocketChatAdminProvider`
+- `useWebSocketChatCustomer`
+- `useWebSocketChatAdmin`
+- `useWebSocketChatBase`
+- All UI components (`ChatMessages`, `ChatInput`, etc.)
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Type check
+pnpm typecheck
+
+# Watch mode
+pnpm dev
+```
+
+## License
+
+MIT

package/dist/api/index.d.mts

@@ -0,0 +1,308 @@
+import { ApiClientOptions, ApiResponse } from '@elqnt/api-client';
+import { ResponseMetadata } from '@elqnt/types';
+import { Chat, ChatSummary } from '../models/index.mjs';
+
+/**
+ * Stream API
+ *
+ * Low-level functions for chat streaming operations.
+ * These are used internally by the transport layer but can also
+ * be used directly for custom implementations.
+ *
+ * @example
+ * ```typescript
+ * import { createChat, sendChatMessage, loadChat } from "@elqnt/chat/api";
+ *
+ * // Create a new chat
+ * const chatKey = await createChat({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   userId: "user-456",
+ * });
+ *
+ * // Send a message
+ * await sendChatMessage({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey,
+ *   userId: "user-456",
+ *   content: "Hello!",
+ * });
+ * ```
+ */
+
+/**
+ * Base options for all stream API calls
+ */
+interface StreamApiOptions {
+    /** Base URL for the chat server */
+    baseUrl: string;
+    /** Organization ID */
+    orgId: string;
+    /** User ID */
+    userId: string;
+}
+/**
+ * Response from stream API calls
+ */
+interface StreamApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * Create chat options
+ */
+interface CreateChatApiOptions extends StreamApiOptions {
+    /** Optional metadata for the new chat */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create chat response data
+ */
+interface CreateChatResponseData {
+    chatKey: string;
+}
+/**
+ * Send message options
+ */
+interface SendMessageApiOptions extends StreamApiOptions {
+    /** Chat key */
+    chatKey: string;
+    /** Message content */
+    content: string;
+    /** Optional attachments */
+    attachments?: unknown[];
+    /** Optional message metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Load chat options
+ */
+interface LoadChatApiOptions extends StreamApiOptions {
+    /** Chat key to load */
+    chatKey: string;
+}
+/**
+ * Load chat response data
+ */
+interface LoadChatResponseData {
+    chat: Chat;
+}
+/**
+ * End chat options
+ */
+interface EndChatApiOptions extends StreamApiOptions {
+    /** Chat key to end */
+    chatKey: string;
+    /** Optional end reason */
+    reason?: string;
+}
+/**
+ * Typing indicator options
+ */
+interface TypingApiOptions extends StreamApiOptions {
+    /** Chat key */
+    chatKey: string;
+    /** Whether user is typing */
+    typing: boolean;
+}
+/**
+ * Generic event options
+ */
+interface SendEventApiOptions extends StreamApiOptions {
+    /** Chat key */
+    chatKey: string;
+    /** Event type */
+    type: string;
+    /** Event data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Create a new chat session
+ *
+ * @param options - Create chat options
+ * @returns Chat key of the created chat
+ *
+ * @example
+ * ```typescript
+ * const chatKey = await createChat({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   userId: "user-456",
+ *   metadata: { source: "website" },
+ * });
+ * ```
+ */
+declare function createChat(options: CreateChatApiOptions): Promise<string>;
+/**
+ * Send a message in a chat
+ *
+ * @param options - Send message options
+ *
+ * @example
+ * ```typescript
+ * await sendChatMessage({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ *   content: "Hello!",
+ * });
+ * ```
+ */
+declare function sendChatMessage(options: SendMessageApiOptions): Promise<void>;
+/**
+ * Load an existing chat
+ *
+ * @param options - Load chat options
+ * @returns The loaded chat object
+ *
+ * @example
+ * ```typescript
+ * const chat = await loadChat({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ * });
+ * ```
+ */
+declare function loadChat(options: LoadChatApiOptions): Promise<Chat>;
+/**
+ * End a chat session
+ *
+ * @param options - End chat options
+ *
+ * @example
+ * ```typescript
+ * await endChat({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ *   reason: "User closed chat",
+ * });
+ * ```
+ */
+declare function endChat(options: EndChatApiOptions): Promise<void>;
+/**
+ * Send typing indicator
+ *
+ * @param options - Typing indicator options
+ *
+ * @example
+ * ```typescript
+ * // User started typing
+ * await sendTypingIndicator({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ *   typing: true,
+ * });
+ *
+ * // User stopped typing
+ * await sendTypingIndicator({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ *   typing: false,
+ * });
+ * ```
+ */
+declare function sendTypingIndicator(options: TypingApiOptions): Promise<void>;
+/**
+ * Send a generic event
+ *
+ * @param options - Event options
+ *
+ * @example
+ * ```typescript
+ * await sendEvent({
+ *   baseUrl: "https://api.example.com/chat",
+ *   orgId: "org-123",
+ *   chatKey: "chat-789",
+ *   userId: "user-456",
+ *   type: "skill_activate",
+ *   data: { skillId: "research" },
+ * });
+ * ```
+ */
+declare function sendEvent(options: SendEventApiOptions): Promise<void>;
+
+/**
+ * Chat API
+ *
+ * API functions for chat operations.
+ *
+ * ## Browser API (uses @elqnt/api-client)
+ * ```typescript
+ * import { getChatHistoryApi, getChatApi } from "@elqnt/chat/api";
+ *
+ * const history = await getChatHistoryApi({ baseUrl, orgId, limit: 10 });
+ * const chat = await getChatApi(chatKey, { baseUrl, orgId });
+ * ```
+ *
+ * ## Stream API (direct HTTP calls)
+ * ```typescript
+ * import { createChat, sendChatMessage, loadChat } from "@elqnt/chat/api";
+ *
+ * const chatKey = await createChat({ baseUrl, orgId, userId });
+ * await sendChatMessage({ baseUrl, orgId, chatKey, userId, content: "Hello!" });
+ * ```
+ */
+
+interface ChatHistoryResponse {
+    chats: ChatSummary[];
+    total: number;
+    hasMore: boolean;
+    metadata: ResponseMetadata;
+}
+interface ChatResponse {
+    chat: ChatSummary;
+    metadata: ResponseMetadata;
+}
+interface UpdateChatResponse {
+    chatKey: string;
+    title: string;
+    pinned: boolean;
+    metadata: ResponseMetadata;
+}
+interface ActiveChatsResponse {
+    chats: ChatSummary[];
+    metadata: ResponseMetadata;
+}
+interface ActiveChatsCountResponse {
+    count: number;
+    metadata: ResponseMetadata;
+}
+declare function getChatHistoryApi(options: ApiClientOptions & {
+    limit?: number;
+    offset?: number;
+    skipCache?: boolean;
+}): Promise<ApiResponse<ChatHistoryResponse>>;
+declare function getChatApi(chatKey: string, options: ApiClientOptions): Promise<ApiResponse<ChatResponse>>;
+declare function updateChatApi(chatKey: string, updates: {
+    title?: string;
+    pinned?: boolean;
+}, options: ApiClientOptions): Promise<ApiResponse<UpdateChatResponse>>;
+declare function deleteChatApi(chatKey: string, options: ApiClientOptions): Promise<ApiResponse<{
+    success: boolean;
+    metadata: ResponseMetadata;
+}>>;
+declare function getActiveChatsCountApi(options: ApiClientOptions): Promise<ApiResponse<ActiveChatsCountResponse>>;
+declare function getActiveChatsApi(options: ApiClientOptions & {
+    pastHours?: number;
+}): Promise<ApiResponse<ActiveChatsResponse>>;
+declare function updateProjectChatTitleApi(projectId: string, chatKey: string, title: string, options: ApiClientOptions): Promise<ApiResponse<{
+    success: boolean;
+    metadata: ResponseMetadata;
+}>>;
+declare function addChatToProjectApi(projectId: string, chatKey: string, options: ApiClientOptions): Promise<ApiResponse<{
+    success: boolean;
+    metadata: ResponseMetadata;
+}>>;
+
+export { type ActiveChatsCountResponse, type ActiveChatsResponse, Chat, type ChatHistoryResponse, type ChatResponse, ChatSummary, type CreateChatApiOptions, type CreateChatResponseData, type EndChatApiOptions, type LoadChatApiOptions, type LoadChatResponseData, type SendEventApiOptions, type SendMessageApiOptions, type StreamApiOptions, type StreamApiResponse, type TypingApiOptions, type UpdateChatResponse, addChatToProjectApi, createChat, deleteChatApi, endChat, getActiveChatsApi, getActiveChatsCountApi, getChatApi, getChatHistoryApi, loadChat, sendChatMessage, sendEvent, sendTypingIndicator, updateChatApi, updateProjectChatTitleApi };