@traiyani/chatsdk-react 1.0.2 → 1.0.4

package/README.md

@@ -16,67 +16,713 @@ React SDK for ChatSDK - Real-time chat solution with product-based conversations
 - Ready-made UI components (Conversation List + Chat Window)
 - Pre-built — works with any bundler, zero config
 
-## Requirements
+## Table of Contents
 
-- **React**: >= 16.8.0
-- **Node.js**: >= 16.0.0
+1. [Installation](#1-installation)
+2. [SDK Initialization](#2-sdk-initialization)
+3. [User Authentication](#3-user-authentication)
+4. [Start a New Conversation](#4-start-a-new-conversation)
+5. [Using Ready-Made UI Components](#5-using-ready-made-ui-components)
+6. [Sending Messages](#6-sending-messages)
+7. [File Uploads & Attachments](#7-file-uploads--attachments)
+8. [Unread Message Counts](#8-unread-message-counts)
+9. [Block & Unblock Users](#9-block--unblock-users)
+10. [Real-Time Events](#10-real-time-events)
+11. [Theme Support](#11-theme-support)
+12. [Internationalization (i18n)](#12-internationalization-i18n)
+13. [Logout & Cleanup](#13-logout--cleanup)
+14. [TypeScript Support](#14-typescript-support)
+15. [Troubleshooting](#15-troubleshooting)
 
-## Installation
+---
+
+## 1. Installation
 
 ```bash
 npm install @traiyani/chatsdk-react axios socket.io-client
 ```
 
-Import the stylesheet in your app's entry point:
+### Requirements
+
+| Dependency | Minimum Version |
+|---|---|
+| `react` | >= 16.8.0 |
+| `react-dom` | >= 16.8.0 |
+| `axios` | >= 0.21.0 |
+| `socket.io-client` | >= 4.0.0 |
+
+**No build configuration changes needed.** Works with Vite, webpack, Next.js, Create React App, Parcel, and any React bundler out of the box.
+
+### Import CSS
+
+Import the stylesheet once in your app's entry point:
 
 ```tsx
 import '@traiyani/chatsdk-react/dist/chatsdk.css';
 ```
 
-## Quick Start
+---
 
-See [DOCUMENTATION.md](./DOCUMENTATION.md) for the complete integration guide covering:
+## 2. SDK Initialization
 
-1. SDK Initialization
-2. User Authentication (login with `isLoggedinUser = true`)
-3. Verify Other User (with `isLoggedinUser = false`)
-4. Generate `externalGroupId` (GUID for fast room lookup)
-5. Start Conversations (direct + product-based with metadata)
-6. Using Ready-Made UI Components (ConversationList + ChatWindow)
-7. Sending Messages
-8. File Uploads
-9. Unread Message Counts
-10. Block & Unblock Users
-11. Real-Time Events
-12. Theme Support
-13. Internationalization (i18n)
-14. Logout & Cleanup
-15. Troubleshooting
+Initialize the SDK once in your app, before any authentication or chat operations.
 
-## Peer Dependencies
+```tsx
+import { ChatSDK } from '@traiyani/chatsdk-react';
 
-| Package | Version |
-|---------|---------|
-| `react` | >= 16.8.0 |
-| `react-dom` | >= 16.8.0 |
-| `axios` | >= 0.21.0 |
-| `socket.io-client` | >= 4.0.0 |
+const sdk = ChatSDK.getInstance();
 
-## What's Inside the Package
+await sdk.init({
+  apiBaseUrl: 'https://your-chat-api.com/api',  // Your Mzad Chat API URL
+  appId: 'your-app-id',                          // Your application ID
+  environment: 'production',                      // 'development' | 'staging' | 'production'
+  enableLogging: true,                            // Enable console logs (set false in production)
+  autoConnect: true,                              // Auto-connect WebSocket after auth
+});
+```
 
+### Configuration Options
+
+```typescript
+interface ChatSDKConfig {
+  apiBaseUrl: string;                              // Required - API server URL
+  appId: string;                                   // Required - Your application ID
+  environment: 'development' | 'staging' | 'production';  // Required
+  wsUrl?: string;                                  // WebSocket URL (defaults to apiBaseUrl)
+  apiKey?: string;                                 // API key (if required by server)
+  enableLogging?: boolean;                         // Enable debug logging (default: false)
+  autoConnect?: boolean;                           // Auto-connect WebSocket (default: true)
+  timeout?: number;                                // HTTP request timeout in ms (default: 30000)
+}
 ```
-dist/
-  chatsdk-react.mjs   – ES module build
-  chatsdk-react.cjs   – CommonJS build
-  chatsdk.css          – single merged stylesheet
-  index.d.ts           – TypeScript declarations
-  *.map                – source maps
+
+### Environment Variables
+
+Config values can come from any source:
+
+```tsx
+// Create React App
+await sdk.init({ apiBaseUrl: process.env.REACT_APP_API_URL, appId: process.env.REACT_APP_APP_ID, ... });
+
+// Vite
+await sdk.init({ apiBaseUrl: import.meta.env.VITE_API_URL, appId: import.meta.env.VITE_APP_ID, ... });
+
+// Next.js
+await sdk.init({ apiBaseUrl: process.env.NEXT_PUBLIC_API_URL, appId: process.env.NEXT_PUBLIC_APP_ID, ... });
 ```
 
-## License
+---
 
-MIT
+## 3. User Authentication
+
+The SDK uses the `chatUsers.authenticate()` method which tries login first and falls back to registration automatically.
+
+### 3.1 Login the Current User (`isLoggedinUser = true`)
+
+Use `isLoggedinUser = true` when the user is the **currently logged-in user** of your app. This saves the auth token so the SDK can make API calls on behalf of this user.
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+// Authenticate the current logged-in user
+const currentUser = await sdk.chatUsers.authenticate(
+  'external-user-123',       // Your app's user ID
+  'your-app-id',             // App ID (must match sdk.init)
+  'John Doe',                // Display name
+  'john@example.com',        // Email
+  true                       // isLoggedinUser = true → saves token
+);
+
+// Connect WebSocket for real-time messaging
+await sdk.connect(currentUser.id);
+
+console.log('Logged in:', currentUser.name);
+```
+
+**What happens under the hood:**
+1. Tries to **login** the user (if already registered in chat system)
+2. If login fails, **registers** the user automatically
+3. Saves the auth token to localStorage (because `isLoggedinUser = true`)
+4. All subsequent API calls use this token
+
+### 3.2 Verify Another User's Existence (`isLoggedinUser = false`)
+
+Use `isLoggedinUser = false` when you need to verify or register **another user** (e.g., a seller, the other participant) without switching the current session. This does NOT save the token.
+
+```tsx
+// Verify/register the other user (seller) without switching sessions
+const otherUser = await sdk.chatUsers.authenticate(
+  'seller-456',              // The other user's external ID
+  'your-app-id',             // App ID
+  'Jane Smith',              // Their display name
+  'jane@example.com',        // Their email
+  false                      // isLoggedinUser = false → does NOT save token
+);
+
+console.log('Other user verified:', otherUser.name, otherUser.id);
+// Now you can use otherUser.id to start a chat
+```
+
+**Why this matters:** Before starting a chat with another user, you must ensure they exist in the chat system. Calling `authenticate` with `isLoggedinUser = false` creates or verifies the user without disrupting your current session.
+
+### 3.3 Check Login Status
+
+```tsx
+const isLoggedIn = sdk.chatUsers.isAuthenticated();
+const currentUser = sdk.getCurrentUser();
+```
+
+---
+
+## 4. Start a New Conversation
+
+### 4.1 Understanding `externalGroupId` (Required)
+
+All `startChat` methods require an `externalGroupId`. This is a unique identifier your app generates to enable fast room lookup (98% faster) and prevent duplicate conversations.
+
+**How to generate it:**
+
+```tsx
+async function generateExternalGroupId(userId1, userId2, productId) {
+  const sorted = [userId1, userId2].sort();
+  const base = productId
+    ? `${sorted[0]}_${sorted[1]}_product_${productId}`
+    : `${sorted[0]}_${sorted[1]}`;
+
+  return await hashString(base);
+}
+
+async function hashString(input) {
+  if (typeof crypto !== 'undefined' && crypto.subtle) {
+    const data = new TextEncoder().encode(input);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    return Array.from(new Uint8Array(hashBuffer))
+      .map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+  // Fallback for non-HTTPS environments (e.g. http://localhost)
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = (hash * 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+```
+
+**Usage:**
+
+```tsx
+const currentUserId = sdk.getCurrentUser().id;
+const externalGroupId = await generateExternalGroupId(currentUserId, otherUser.id, 'PRODUCT_123');
+```
+
+### 4.2 Simple Direct Chat
+
+```tsx
+const conversation = await sdk.chatUsers.startChat(
+  externalGroupId,    // Generated GUID
+  otherUser.id        // The other participant's chat user ID
+);
+
+console.log('Chat started:', conversation.id);
+```
+
+### 4.3 Chat with Product Context & Metadata
+
+```tsx
+// Create product context
+const productContext = {
+  productId: 'CAR_456',
+  productName: 'Toyota Camry 2023',
+  productImage: 'https://example.com/car.jpg',
+  price: 25000,
+  currency: 'QAR',
+  category: 'Vehicles',
+  productMetadata: {
+    mileage: '50000',
+    transmission: 'Automatic',
+    year: '2023',
+  },
+};
+
+// Optional: custom chat metadata
+const chatMetadata = {
+  dealType: 'sale',
+  negotiable: true,
+  priority: 'high',
+  source: 'featured_listing',
+};
+
+// Start product chat
+const conversation = await sdk.chatUsers.startChatWithProduct(
+  externalGroupId,     // Generated GUID (include productId in generation)
+  otherUser.id,        // Seller's chat user ID
+  productContext,      // Product information
+  chatMetadata         // Optional chat metadata
+);
+
+console.log('Product chat started:', conversation.id);
+```
+
+### 4.4 Complete Flow: Login → Verify Seller → Start Product Chat
+
+```tsx
+import { ChatSDK } from '@traiyani/chatsdk-react';
+
+const sdk = ChatSDK.getInstance();
+
+// Step 1: Initialize SDK
+await sdk.init({
+  apiBaseUrl: 'https://your-chat-api.com/api',
+  appId: 'your-app-id',
+  environment: 'production',
+});
+
+// Step 2: Login the current user (buyer)
+const currentUser = await sdk.chatUsers.authenticate(
+  'buyer-external-id',
+  'your-app-id',
+  'Ahmed',
+  'ahmed@example.com',
+  true   // isLoggedinUser = true → this is the logged-in user
+);
+await sdk.connect(currentUser.id);
+
+// Step 3: Verify/register the other user (seller) — does NOT switch session
+const seller = await sdk.chatUsers.authenticate(
+  'seller-external-id',
+  'your-app-id',
+  'Mohammed',
+  'mohammed@example.com',
+  false  // isLoggedinUser = false → just verify existence
+);
+
+// Step 4: Generate externalGroupId
+const externalGroupId = await generateExternalGroupId(
+  currentUser.id,
+  seller.id,
+  'PRODUCT_789'
+);
+
+// Step 5: Start chat with product
+const conversation = await sdk.chatUsers.startChatWithProduct(
+  externalGroupId,
+  seller.id,
+  {
+    productId: 'PRODUCT_789',
+    productName: 'iPhone 15 Pro',
+    productImage: 'https://example.com/iphone.jpg',
+    price: 4999,
+    currency: 'QAR',
+    category: 'Electronics',
+  }
+);
+
+// Step 6: Now show ChatWindow component with this conversation
+```
+
+---
+
+## 5. Using Ready-Made UI Components
+
+The SDK includes two ready-made React components with full functionality.
+
+### 5.1 Conversation List
+
+Displays all conversations with last message preview, unread badges, product context, and real-time updates.
+
+```tsx
+import { ConversationList } from '@traiyani/chatsdk-react';
+
+<ConversationList
+  currentUser={currentUser}
+  onSelectConversation={(conversation) => setSelectedConversation(conversation)}
+  selectedConversationId={selectedConversation?.id}
+/>
+```
+
+**Props:**
+
+```typescript
+interface ConversationListProps {
+  currentUser: ChatSDKUser;                            // Required - authenticated user
+  onSelectConversation: (conv: Conversation) => void;  // Required - selection callback
+  selectedConversationId?: string;                     // Highlights active conversation
+}
+```
+
+### 5.2 Chat Window
+
+Full chat interface with messaging, file uploads, typing indicators, message status, block/unblock, and product context bar.
+
+```tsx
+import { ChatWindow } from '@traiyani/chatsdk-react';
+
+<ChatWindow
+  conversation={selectedConversation}
+  currentUser={currentUser}
+  onClose={() => setSelectedConversation(null)}
+  onBack={() => setSelectedConversation(null)}
+/>
+```
+
+**Props:**
+
+```typescript
+interface ChatWindowProps {
+  conversation: Conversation | null;  // Required - active conversation
+  currentUser: ChatSDKUser;           // Required - authenticated user
+  onClose?: () => void;               // Called when close button pressed
+  onBack?: () => void;                // Called when back button pressed (mobile)
+}
+```
+
+### 5.3 Complete App Example
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { ChatSDK, ConversationList, ChatWindow } from '@traiyani/chatsdk-react';
+import '@traiyani/chatsdk-react/dist/chatsdk.css';
+
+function ChatApp() {
+  const [currentUser, setCurrentUser] = useState(null);
+  const [selectedConversation, setSelectedConversation] = useState(null);
+
+  useEffect(() => {
+    const init = async () => {
+      const sdk = ChatSDK.getInstance();
+      await sdk.init({
+        apiBaseUrl: process.env.REACT_APP_API_URL,
+        appId: process.env.REACT_APP_APP_ID,
+        environment: 'production',
+      });
+
+      const user = await sdk.chatUsers.authenticate(
+        'user-123', 'your-app-id', 'John Doe', 'john@example.com', true
+      );
+      await sdk.connect(user.id);
+      setCurrentUser(user);
+    };
+    init();
+  }, []);
+
+  if (!currentUser) return <div>Loading...</div>;
+
+  return (
+    <div style={{ display: 'flex', height: '100vh' }}>
+      <div style={{ width: '350px', borderRight: '1px solid #e0e0e0' }}>
+        <ConversationList
+          currentUser={currentUser}
+          onSelectConversation={setSelectedConversation}
+          selectedConversationId={selectedConversation?.id}
+        />
+      </div>
+      <div style={{ flex: 1 }}>
+        {selectedConversation ? (
+          <ChatWindow
+            conversation={selectedConversation}
+            currentUser={currentUser}
+            onClose={() => setSelectedConversation(null)}
+            onBack={() => setSelectedConversation(null)}
+          />
+        ) : (
+          <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%' }}>
+            Select a conversation
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## 6. Sending Messages
+
+### Send a Text Message
 
-## Support
+```tsx
+const sdk = ChatSDK.getInstance();
+
+const message = await sdk.messages.sendMessage(
+  conversationId,
+  'Hello! Is this still available?'
+);
+
+console.log('Message sent:', message.id);
+```
+
+### Send with Metadata
+
+```tsx
+const message = await sdk.messages.sendMessageWithOptions({
+  conversationId: conversationId,
+  content: 'Here is my offer',
+  type: 'text',
+  metadata: { offerAmount: 4500, currency: 'QAR' },
+});
+```
+
+### Load Messages (with Pagination)
+
+```tsx
+const messages = await sdk.messages.getMessages({
+  conversationId: conversationId,
+  limit: 50,
+  offset: 0,
+});
+
+messages.forEach(msg => {
+  console.log(`${msg.senderName}: ${msg.content}`);
+});
+```
+
+### Send Typing Indicator
+
+```tsx
+// User started typing
+await sdk.messages.sendTypingIndicator(conversationId, true);
+
+// User stopped typing
+await sdk.messages.sendTypingIndicator(conversationId, false);
+```
+
+### Mark Messages as Read
+
+```tsx
+// Mark all messages in a conversation as read
+await sdk.chatUsers.markRoomMessagesRead(conversationId);
+
+// Mark a specific message as read
+await sdk.chatUsers.markMessageRead(messageId);
+```
+
+---
+
+## 7. File Uploads & Attachments
+
+### Upload and Send a File
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+const result = await sdk.media.uploadMedia({
+  file: selectedFile,          // File object from input
+  type: 'image',              // 'image' | 'video' | 'audio' | 'document'
+  conversationId: conversationId,
+  caption: 'Check this out',
+  onProgress: (progress) => {
+    console.log(`Upload: ${progress}%`);
+  },
+});
+
+console.log('Uploaded:', result.fileUrl);
+```
+
+### Convenience Methods
+
+```tsx
+// Send image
+await sdk.media.sendImage(conversationId, imageFile, 'Photo caption');
+
+// Send video
+await sdk.media.sendVideo(conversationId, videoFile);
+
+// Send document (PDF, DOC, etc.)
+await sdk.media.sendDocument(conversationId, pdfFile);
+
+// Send audio
+await sdk.media.sendAudio(conversationId, audioFile);
+```
+
+**Supported file types:** Images (`.jpg`, `.png`, `.gif`, `.webp`), Videos (`.mp4`, `.mov`), Documents (`.pdf`, `.doc`, `.docx`), Audio (`.mp3`, `.wav`)
+
+**Note:** The built-in `<ChatWindow />` component handles file picking, uploading, and preview automatically.
+
+---
+
+## 8. Unread Message Counts
+
+### Get Unread Conversations Count
+
+```tsx
+const count = await sdk.chatUsers.getUnreadConversationsCount();
+console.log(`${count} conversations with unread messages`);
+```
+
+### Get Total Unread Message Count
+
+```tsx
+const total = await sdk.chatUsers.getTotalUnreadCount();
+console.log(`${total} total unread messages`);
+```
+
+### Get Detailed Unread Summary
+
+```tsx
+const summary = await sdk.chatUsers.getUnreadSummary();
+console.log('Total unread conversations:', summary.totalConversationsWithUnread);
+console.log('Total unread messages:', summary.totalUnreadMessages);
+
+summary.unreadSummary.forEach(item => {
+  console.log(`${item.room_name}: ${item.unread_count} unread`);
+});
+```
+
+### Auto-Mark as Read
+
+```tsx
+// When user opens a conversation
+sdk.chatUsers.startViewingConversation(conversationId);
 
-- Documentation: [DOCUMENTATION.md](./DOCUMENTATION.md)
+// When user leaves the conversation
+sdk.chatUsers.stopViewingConversation(conversationId);
+```
+
+---
+
+## 9. Block & Unblock Users
+
+```tsx
+await sdk.users.blockUser(userIdToBlock);
+await sdk.users.unblockUser(userIdToUnblock);
+const blockedUsers = await sdk.users.getBlockedUsers();
+```
+
+**Notes:**
+- Blocking is per-conversation, not global
+- Blocked users cannot send messages in that conversation
+- The built-in `<ChatWindow />` has a block/unblock UI built in
+
+---
+
+## 10. Real-Time Events
+
+### Listen for Events
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+sdk.socket.on('message_received', (data) => {
+  console.log('New message:', data.message.content);
+});
+
+sdk.socket.on('typing_indicator', (data) => {
+  console.log(data.isTyping ? 'User is typing...' : 'User stopped typing');
+});
+
+sdk.socket.on('user_status_changed', (data) => {
+  console.log('User status:', data.status);
+});
+
+sdk.socket.on('connection_status', (status) => {
+  console.log('WebSocket:', status);
+});
+```
+
+### Available Event Types
+
+| Event | Description |
+|-------|-------------|
+| `message_received` | New message arrived |
+| `typing_indicator` | User started/stopped typing |
+| `user_status_changed` | User online/offline status changed |
+| `conversation_updated` | Conversation metadata changed |
+| `connection_status` | WebSocket connected/disconnected/error |
+
+### Socket Direct Operations
+
+```tsx
+sdk.socket.joinConversation(conversationId);
+sdk.socket.leaveConversation(conversationId);
+sdk.socket.sendTypingIndicator(conversationId, true);
+const isConnected = sdk.socket.isConnected();
+```
+
+---
+
+## 11. Theme Support
+
+```tsx
+import { ThemeProvider, ThemeToggle, useTheme } from '@traiyani/chatsdk-react';
+
+// Option 1: ThemeProvider + ThemeToggle
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeToggle showLabel />
+    </ThemeProvider>
+  );
+}
+
+// Option 2: useTheme hook
+function MyComponent() {
+  const { theme, actualTheme, setTheme, toggleTheme } = useTheme();
+  return <button onClick={toggleTheme}>Current: {actualTheme}</button>;
+}
+
+// Option 3: Imperative
+import { initializeTheme } from '@traiyani/chatsdk-react';
+initializeTheme();
+```
+
+---
+
+## 12. Internationalization (i18n)
+
+Supported languages: **English** (`en`), **Arabic** (`ar` with RTL)
+
+```tsx
+import { changeLanguage, getCurrentLanguage, isRTL, t } from '@traiyani/chatsdk-react';
+
+const title = t('conversations_title');
+changeLanguage('ar'); // Switches to Arabic + sets RTL
+const lang = getCurrentLanguage(); // 'en' or 'ar'
+const rtl = isRTL(); // true if Arabic
+```
+
+---
+
+## 13. Logout & Cleanup
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+// Disconnect WebSocket
+sdk.socket.disconnect();
+
+// Logout (clears token)
+await sdk.chatUsers.logout();
+```
+
+---
+
+## 14. TypeScript Support
+
+Full type declarations are included. No extra `@types/*` packages needed.
+
+```tsx
+import type {
+  ChatSDKConfig, ChatSDKUser, ChatSDKMessage, ChatSDKConversation,
+  ProductContext, Product, ChatState, ChatWindowProps, ConversationListProps,
+  SendMessageOptions, MediaUploadOptions, MediaUploadResult,
+  CreateConversationOptions, EventCallback,
+} from '@traiyani/chatsdk-react';
+```
+
+---
+
+## 15. Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| WebSocket not connecting | Ensure `autoConnect: true` in config, verify API URL is reachable, check CORS |
+| Messages not loading | Ensure user is authenticated first, verify `conversationId` is valid |
+| CSS not applying | Ensure `import '@traiyani/chatsdk-react/dist/chatsdk.css'` is in your entry file |
+| Authentication fails | Verify `apiBaseUrl` and `appId`, check browser console, ensure CORS is configured |
+| "SDK not initialized" | Ensure `await sdk.init()` is called before any other SDK method |
+
+## License
+
+MIT