@elqnt/chat 2.0.8 → 3.0.1

package/README.md

@@ -0,0 +1,433 @@
+# @elqnt/chat
+
+Platform-agnostic chat SDK for React and React Native. Uses HTTP + SSE for reliable real-time communication.
+
+**Key Features:**
+- **Mutations via HTTP** - `startChat()`, `loadChat()` return data directly (no waiting for SSE events)
+- **Events via SSE** - Real-time messages, typing indicators, agent updates
+- **Multi-transport** - Browser EventSource, React Native fetch-based SSE, WhatsApp webhooks
+- **TypeScript-first** - Full type definitions for all models and events
+
+## Installation
+
+```bash
+pnpm add @elqnt/chat
+```
+
+## Quick Start
+
+```tsx
+import { useChat } from "@elqnt/chat/hooks";
+
+function ChatComponent() {
+  const {
+    connect,
+    disconnect,
+    sendMessage,
+    startChat,
+    loadChat,
+    messages,
+    isConnected,
+    currentChat,
+  } = useChat({
+    baseUrl: "https://api.example.com/chat",
+    orgId: "org-123",
+    userId: "user-456",
+  });
+
+  useEffect(() => {
+    connect();
+    return () => disconnect();
+  }, []);
+
+  // Start a new chat - returns chatKey immediately
+  const handleNewChat = async () => {
+    const chatKey = await startChat({ agentId: "support-agent" });
+    console.log("Created chat:", chatKey);
+  };
+
+  // Load existing chat - returns Chat immediately
+  const handleLoadChat = async (chatKey: string) => {
+    const chat = await loadChat(chatKey);
+    console.log("Loaded chat with", chat.messages.length, "messages");
+  };
+
+  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 (return data directly via HTTP)
+  startChat: (metadata?: Record<string, unknown>) => Promise<string>;  // Returns chatKey
+  loadChat: (chatKey: string) => Promise<Chat>;                        // Returns loaded Chat
+  sendMessage: (content: string, attachments?: unknown[]) => Promise<void>;
+  sendEvent: (event: Omit<ChatEvent, "timestamp">) => Promise<void>;
+  endChat: (reason?: string) => Promise<void>;
+
+  // Typing Indicators
+  startTyping: () => void;
+  stopTyping: () => void;
+
+  // State (auto-updated by hook)
+  currentChat: Chat | null;
+  chatKey: string | null;
+  messages: ChatMessage[];
+  error: TransportError | null;
+  metrics: ConnectionMetrics;
+
+  // Events (SSE push events)
+  on: (eventType: string, handler: (event: ChatEvent) => void) => () => void;
+  clearError: () => void;
+}
+```
+
+> **Note:** `startChat()` and `loadChat()` use direct HTTP calls and return data immediately.
+> You don't need to listen for `new_chat_created` or `load_chat_response` events - those are
+> only broadcast for multi-tab synchronization.
+
+### `/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,
+  CreateChatOptions,
+  CreateChatResponse,
+  LoadChatOptions,
+  LoadChatResponse,
+} 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 = {
+  // Connection
+  async connect(config) { /* ... */ },
+  disconnect() { /* ... */ },
+
+  // Mutations (return data directly)
+  async createChat(options) { /* returns { chatKey } */ },
+  async loadChatData(options) { /* returns { chat, agentId? } */ },
+
+  // Fire-and-forget operations
+  async send(event) { /* ... */ },
+  async sendMessage(message) { /* ... */ },
+
+  // Event subscriptions
+  onMessage(handler) { /* returns unsubscribe */ },
+  on(eventType, handler) { /* returns unsubscribe */ },
+
+  // State
+  getState() { /* returns TransportState */ },
+  getMetrics() { /* returns ConnectionMetrics */ },
+  getError() { /* returns TransportError | undefined */ },
+  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 in v3.0
+
+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
+
+### Changes in v3.0.1
+
+1. **`loadChat()` returns `Promise<Chat>`** - Previously returned `Promise<void>`, now returns the loaded chat directly
+2. **`startChat()` returns immediately** - No longer waits for SSE event, returns chatKey from HTTP response
+3. **Transport interface extended** - Added `createChat()` and `loadChatData()` methods for direct HTTP responses
+4. **Event handlers simplified** - `new_chat_created` and `load_chat_response` events are now only for multi-tab sync
+
+### 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

@@ -1,15 +1,257 @@
 import { ApiClientOptions, ApiResponse } from '@elqnt/api-client';
 import { ResponseMetadata } from '@elqnt/types';
-import { ChatSummary } from '../models/index.mjs';
-export { Chat } from '../models/index.mjs';
-import '@elqnt/kg';
-import '@elqnt/docs';
+import { Chat, ChatSummary } from '../models/index.mjs';
 
 /**
- * Chat API functions
+ * Stream API
  *
- * Browser-side API client for chat operations.
- * Uses @elqnt/api-client for HTTP requests with automatic token management.
+ * 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 {
@@ -63,4 +305,4 @@ declare function addChatToProjectApi(projectId: string, chatKey: string, options
     metadata: ResponseMetadata;
 }>>;
 
-export { type ActiveChatsCountResponse, type ActiveChatsResponse, type ChatHistoryResponse, type ChatResponse, ChatSummary, type UpdateChatResponse, addChatToProjectApi, deleteChatApi, getActiveChatsApi, getActiveChatsCountApi, getChatApi, getChatHistoryApi, updateChatApi, updateProjectChatTitleApi };
+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 };