@yellowdotai/yellow-chat-sdk 1.0.0

package/README.md

@@ -0,0 +1,462 @@
+# Yellow Chat SDK
+
+A TypeScript SDK for integrating Yellow.ai chat functionality into web applications. This SDK provides event-based communication for a clean separation between the data layer and UI layer.
+
+## Installation
+
+```bash
+npm install @yellowdotai/yellow-chat-sdk
+```
+
+## Quick Start
+
+```typescript
+import { YellowChat } from '@yellowdotai/yellow-chat-sdk';
+
+// Create SDK instance
+const sdk = new YellowChat();
+
+// Subscribe to events BEFORE connecting
+sdk.on('connection:connected', ({ userId }) => {
+  console.log('Connected as:', userId);
+});
+
+sdk.on('message:received', (message) => {
+  console.log('New message:', message);
+  // message.type = 'text' | 'image' | 'video' | 'audio' | 'file' | 'location' | 'system'
+  // message.content = { message: "..." } for text, { url: "..." } for media
+  // Render message in your UI based on type
+});
+
+sdk.on('agent:assigned', (agentProfile) => {
+  // Update UI to show agent info
+  console.log('Agent joined:', agentProfile.name);
+});
+
+sdk.on('agent:left', () => {
+  // Agent has left the conversation
+  console.log('Agent left the conversation');
+});
+
+// Initialize and connect
+await sdk.init({
+  bot: 'your-bot-id',
+  host: 'https://cloud.yellow.ai'
+});
+
+await sdk.connect();
+
+// Send messages
+await sdk.sendMessage('Hello!');
+```
+
+## Configuration
+
+```typescript
+interface SDKConfig {
+  // Required
+  bot: string;                    // Your bot ID
+
+  // Server
+  host?: string;                  // API host URL (default: 'https://cloud.yellow.ai')
+
+  // Message Source (IMPORTANT for live agent integrations)
+  source?: string;                // 'yellowmessenger' (default) or 'syncApi'
+
+  // User
+  userId?: string;                // User ID (auto-generated if not provided)
+  name?: string;                  // User display name
+
+  // Authentication
+  ymAuthenticationToken?: string; // Auth token (if required by your bot)
+
+  // Custom Payload
+  payload?: Record<string, unknown>;
+
+  // Journey Triggers
+  triggerJourney?: string;
+
+  // UTM Parameters
+  utmSource?: string;
+  utmCampaign?: string;
+  utmMedium?: string;
+
+  // Debug
+  debug?: boolean;                // Enable debug logging
+}
+```
+
+### Source Configuration
+
+The `source` parameter is critical when integrating with live agent functionality:
+
+| Source | Use Case | Description |
+|--------|----------|-------------|
+| `yellowmessenger` | **Fully Headless** | Default. Use when SDK is your only communication channel. All messages sent/received via WebSocket. |
+| `syncApi` | **Hybrid Mode (REST + SDK)** | Use when integrating with `/integrations/sync/v1/message` REST API. Required for hybrid architectures. |
+
+#### When to use `yellowmessenger` (default)
+
+Use this for a **fully headless** approach where the SDK handles all communication:
+
+```typescript
+await sdk.init({
+  bot: 'your-bot-id',
+  source: 'yellowmessenger'  // or omit - this is the default
+});
+
+await sdk.connect(userId);
+
+// All communication via SDK
+await sdk.sendMessage('Hello');
+```
+
+#### When to use `syncApi`
+
+Use this for a **hybrid approach** where you:
+1. Start with REST API calls to `/integrations/sync/v1/message` for bot interactions
+2. Switch to SDK WebSocket connection when a live agent connects
+3. Continue using SDK for real-time agent communication
+
+```typescript
+// Step 1: Initially use REST API for bot messages
+const response = await fetch('/integrations/sync/v1/message', {
+  method: 'POST',
+  body: JSON.stringify({
+    botId: 'your-bot-id',
+    sender: senderId,
+    data: { message: 'Hello' }
+  })
+});
+
+// Step 2: When live agent connects, switch to SDK with syncApi source
+if (response.data.includes('live agent connected')) {
+  await sdk.init({
+    bot: 'your-bot-id',
+    source: 'syncApi'  // IMPORTANT: Must match REST API source for ticket consistency
+  });
+  
+  await sdk.connect(senderId);  // Use same senderId from REST API
+  
+  // Now receive agent messages via SDK events
+  sdk.on('message:received', (msg) => console.log('Agent:', msg));
+}
+```
+
+> **Important:** When using hybrid mode, the `source` must be set to `syncApi` to maintain ticket consistency between REST API and WebSocket channels. Using mismatched sources will cause live agent tickets to close unexpectedly.
+
+## API
+
+### Lifecycle
+
+```typescript
+// Initialize
+await sdk.init(config);
+
+// Connect (optionally with a specific user ID)
+await sdk.connect(userId?);
+
+// Disconnect
+sdk.disconnect();
+```
+
+### Messaging
+
+```typescript
+// Send text message
+await sdk.sendMessage('Hello!');
+
+// Send file
+await sdk.sendFile(file);
+```
+
+> **Note:** Message history is **automatically fetched** when you call `connect()`. Listen to the `history:previousMessages` event to receive it.
+
+### State
+
+```typescript
+// Check connection
+const connected = sdk.isConnected();
+
+// Get user ID
+const userId = sdk.getUserId();
+
+// Get bot info
+const botInfo = sdk.getBotInfo();
+```
+
+### Events
+
+```typescript
+// Subscribe to events (returns unsubscribe function)
+const unsubscribe = sdk.on('message:received', (message) => {
+  console.log(message);
+});
+
+// Unsubscribe later
+unsubscribe();
+
+// Or use off()
+sdk.off('message:received', handler);
+```
+
+## Events
+
+### Connection Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `connection:connecting` | - | Connection attempt started |
+| `connection:connected` | `{ userId }` | Successfully connected |
+| `connection:disconnected` | `{ code, message, wasClean }` | Disconnected |
+| `connection:reconnecting` | `{ attempt, delay }` | Reconnecting |
+| `connection:reconnected` | `{ userId }` | Successfully reconnected |
+| `connection:error` | `SDKError` | Connection error |
+
+### Message Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `message:received` | `IncomingMessage` | Message from bot/agent |
+| `message:sent` | `{ id, message }` | Message sent successfully |
+| `message:failed` | `{ messageId, error }` | Message failed to send |
+
+### Agent Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `agent:assigned` | `AgentProfile` | Live agent joined the conversation |
+| `agent:left` | - | Agent left or ticket closed/resolved |
+| `agent:typing` | `boolean` | Agent is typing |
+
+### Ticket Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `ticket:closed` | - | Ticket has been closed |
+| `ticket:resolved` | - | Ticket has been resolved |
+
+### History Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `history:previousMessages` | `Message[]` | Previous conversation messages (auto-fetched on connect) |
+
+> History is automatically fetched when `connect()` is called. On reconnection, only missed messages are fetched.
+
+### Network Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `network:online` | - | Network connection restored |
+| `network:offline` | - | Network connection lost |
+
+## Integration Modes
+
+### Mode 1: Fully Headless (SDK Only)
+
+Use the SDK as your only communication channel. Best for custom chat widgets.
+
+```typescript
+import { YellowChat } from 'yellow-chat-sdk';
+
+const sdk = new YellowChat();
+
+sdk.on('message:received', (message) => {
+  console.log('Message:', message);
+});
+
+await sdk.init({
+  bot: 'your-bot-id',
+  source: 'yellowmessenger'  // Default - can be omitted
+});
+
+await sdk.connect();
+await sdk.sendMessage('Hello');
+```
+
+### Mode 2: Hybrid Mode (REST API + SDK)
+
+Start with REST API for bot interactions, switch to SDK when live agent connects.
+
+**Why use Hybrid Mode?**
+- Server-side control over bot conversations
+- Reduced client-side complexity for bot-only flows
+- Real-time WebSocket only when needed (live agent)
+
+```typescript
+import { YellowChat } from 'yellow-chat-sdk';
+
+let chatMode = 'rest';
+let sdk = null;
+const senderId = 'unique-user-id';
+
+// REST API for bot messages
+async function sendMessageViaREST(message) {
+  const response = await fetch('https://cloud.yellow.ai/integrations/sync/v1/message', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-api-key': 'your-api-key'
+    },
+    body: JSON.stringify({
+      botId: 'your-bot-id',
+      sender: senderId,
+      data: { message }
+    })
+  });
+  
+  const data = await response.json();
+  
+  // Check if live agent connected
+  if (data.data?.messageArray?.some(m => 
+    m.message?.toLowerCase().includes('live agent') && 
+    m.message?.toLowerCase().includes('connected')
+  )) {
+    await switchToWebSocketMode();
+  }
+  
+  return data;
+}
+
+// Switch to SDK when live agent connects
+async function switchToWebSocketMode() {
+  sdk = new YellowChat();
+  
+  sdk.on('message:received', (message) => {
+    console.log('Agent message:', message);
+  });
+  
+  sdk.on('ticket:closed', () => {
+    console.log('Ticket closed - switching back to REST');
+    chatMode = 'rest';
+  });
+  
+  sdk.on('ticket:resolved', () => {
+    console.log('Ticket resolved - switching back to REST');
+    chatMode = 'rest';
+  });
+  
+  await sdk.init({
+    bot: 'your-bot-id',
+    source: 'syncApi'  // CRITICAL: Must be 'syncApi' for hybrid mode!
+  });
+  
+  await sdk.connect(senderId);  // Use same senderId from REST API
+  chatMode = 'websocket';
+}
+
+// Send message based on current mode
+async function sendMessage(message) {
+  if (chatMode === 'rest') {
+    return sendMessageViaREST(message);
+  } else {
+    return sdk.sendMessage(message);
+  }
+}
+```
+
+> **Critical:** When using hybrid mode, you **MUST** set `source: 'syncApi'` in the SDK configuration. This ensures that messages sent via the SDK are correctly associated with tickets created via the REST API. Using mismatched sources will cause tickets to close unexpectedly.
+
+## Message Types
+
+All messages from the SDK follow a **standardized, flattened format**:
+
+```typescript
+interface IncomingMessage {
+  id: string;                                    // Unique message ID
+  timestamp: Date;                               // Message timestamp
+  type: MessageType;                             // Message type
+  content: MessageContent;                       // Flattened content
+  sender: 'bot' | 'agent' | 'user' | 'system';  // Who sent the message
+}
+
+// Message types
+type MessageType = 'text' | 'image' | 'video' | 'audio' | 'file' | 'location' | 'system' | 'cards' | 'quickReplies';
+
+// Content is FLATTENED based on type:
+// Text:     { message: "Hello" }
+// Image:    { url: "https://..." }
+// Video:    { url: "https://...", controls: true, autoplay: false, ... }
+// Audio:    { url: "https://..." }
+// File:     { url: "https://...", name: "document.pdf" }
+// Location: { latitude: 12.34, longitude: 56.78 }
+// System:   { message: "Agent joined the conversation" }
+```
+
+### Example: Handling Different Message Types
+
+```typescript
+sdk.on('message:received', (message) => {
+  switch (message.type) {
+    case 'text':
+      console.log('Text:', message.content.message);
+      break;
+    case 'image':
+      console.log('Image URL:', message.content.url);
+      break;
+    case 'video':
+      console.log('Video URL:', message.content.url);
+      // Optional: message.content.controls, message.content.autoplay
+      break;
+    case 'file':
+      console.log('File:', message.content.name, message.content.url);
+      break;
+    case 'system':
+      console.log('System:', message.content.message);
+      // e.g., "Agent joined the conversation", "Conversation ended"
+      break;
+  }
+});
+```
+
+## Error Handling
+
+```typescript
+import { YellowChatError } from 'yellow-chat-sdk';
+
+try {
+  await sdk.sendMessage('Hello');
+} catch (error) {
+  if (error instanceof YellowChatError) {
+    console.error('SDK Error:', error.code, error.message);
+    if (error.recoverable) {
+      // Retry logic
+    }
+  }
+}
+
+// Or listen for error events
+sdk.on('connection:error', (error) => {
+  console.error('Connection error:', error);
+});
+
+sdk.on('message:failed', ({ messageId, error }) => {
+  console.error('Message failed:', messageId, error);
+});
+```
+
+## TypeScript
+
+The SDK is written in TypeScript and includes full type definitions.
+
+```typescript
+import type {
+  SDKConfig,
+  IncomingMessage,
+  AgentProfile,
+  SDKEvents,
+  SDKEventName
+} from 'yellow-chat-sdk';
+```
+
+## Browser Support
+
+- Chrome 60+
+- Firefox 55+
+- Safari 11+
+- Edge 79+
+
+## License
+
+MIT