@traiyani/chatsdk-react 1.0.1 → 1.0.3

package/README.md

@@ -2,19 +2,47 @@
 
 React SDK for ChatSDK - Real-time chat solution with product-based conversations, Socket.io, instant messaging, and file sharing.
 
-## Installation
+## Features
+
+- Real-time messaging via Socket.IO
+- Product-based conversations with metadata
+- File/image/video uploads and sharing
+- Block/unblock users
+- Internationalization (English + Arabic with RTL)
+- Dark mode support (light / dark / auto)
+- Typing indicators
+- Read receipts and message status
+- Unread message counts
+- Ready-made UI components (Conversation List + Chat Window)
+- Pre-built — works with any bundler, zero config
+
+## Table of Contents
+
+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)
+
+---
+
+## 1. Installation
 
 ```bash
 npm install @traiyani/chatsdk-react axios socket.io-client
 ```
 
-### Peer Dependencies
-
-Ensure your project has these installed:
-
-```bash
-npm install react react-dom axios socket.io-client
-```
+### Requirements
 
 | Dependency | Minimum Version |
 |---|---|
@@ -23,36 +51,343 @@ npm install react react-dom axios socket.io-client
 | `axios` | >= 0.21.0 |
 | `socket.io-client` | >= 4.0.0 |
 
-## Quick Start
+**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';
+```
+
+---
+
+## 2. SDK Initialization
+
+Initialize the SDK once in your app, before any authentication or chat operations.
+
+```tsx
+import { ChatSDK } from '@traiyani/chatsdk-react';
+
+const sdk = ChatSDK.getInstance();
+
+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)
+}
+```
+
+### 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, ... });
+```
+
+---
+
+## 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]}`;
+
+  const encoder = new TextEncoder();
+  const data = encoder.encode(base);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+}
+```
+
+**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, ChatWindow, ConversationList } from '@traiyani/chatsdk-react';
+import { ChatSDK, ConversationList, ChatWindow } from '@traiyani/chatsdk-react';
 import '@traiyani/chatsdk-react/dist/chatsdk.css';
 
-function App() {
+function ChatApp() {
   const [currentUser, setCurrentUser] = useState(null);
   const [selectedConversation, setSelectedConversation] = useState(null);
 
   useEffect(() => {
     const init = async () => {
       const sdk = ChatSDK.getInstance();
-
       await sdk.init({
-        apiBaseUrl: 'https://your-chat-api.com',
-        appId: 'your-app-id',
+        apiBaseUrl: process.env.REACT_APP_API_URL,
+        appId: process.env.REACT_APP_APP_ID,
         environment: 'production',
-        enableLogging: false,
-        autoConnect: false,
       });
 
       const user = await sdk.chatUsers.authenticate(
-        'user-123',          // your app's user ID
-        'your-app-id',       // your ChatSDK app ID
-        'John Doe',          // display name
-        'john@example.com'   // email
+        'user-123', 'your-app-id', 'John Doe', 'john@example.com', true
       );
-
       await sdk.connect(user.id);
       setCurrentUser(user);
     };
@@ -63,241 +398,318 @@ function App() {
 
   return (
     <div style={{ display: 'flex', height: '100vh' }}>
-      <ConversationList
-        currentUser={currentUser}
-        onSelectConversation={setSelectedConversation}
-        selectedConversationId={selectedConversation?.id}
-      />
-      {selectedConversation && (
-        <ChatWindow
-          conversation={selectedConversation}
+      <div style={{ width: '350px', borderRight: '1px solid #e0e0e0' }}>
+        <ConversationList
           currentUser={currentUser}
-          onClose={() => setSelectedConversation(null)}
-          onBack={() => setSelectedConversation(null)}
+          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>
   );
 }
 ```
 
-**Zero build configuration changes required. Works with Vite, webpack, Next.js, Create React App, Parcel, and any React bundler.**
-
-## Components
+---
 
-### ChatWindow
+## 6. Sending Messages
 
-Displays the chat interface with messages, file uploads, block/unblock, and real-time updates.
+### Send a Text Message
 
 ```tsx
-<ChatWindow
-  conversation={selectedConversation}
-  currentUser={currentUser}
-  onClose={handleClose}
-  onBack={handleBack}
-/>
-```
+const sdk = ChatSDK.getInstance();
 
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `conversation` | `ChatSDKConversation \| null` | Yes | Active conversation object |
-| `currentUser` | `ChatSDKUser` | Yes | Authenticated user object |
-| `onClose` | `() => void` | No | Called when user clicks close |
-| `onBack` | `() => void` | No | Called when user clicks back (mobile) |
+const message = await sdk.messages.sendMessage(
+  conversationId,
+  'Hello! Is this still available?'
+);
 
-### ConversationList
+console.log('Message sent:', message.id);
+```
 
-Displays the list of conversations with search, unread counts, and real-time updates.
+### Send with Metadata
 
 ```tsx
-<ConversationList
-  currentUser={currentUser}
-  onSelectConversation={handleSelect}
-  selectedConversationId={activeConversationId}
-/>
+const message = await sdk.messages.sendMessageWithOptions({
+  conversationId: conversationId,
+  content: 'Here is my offer',
+  type: 'text',
+  metadata: { offerAmount: 4500, currency: 'QAR' },
+});
 ```
 
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `currentUser` | `ChatSDKUser` | Yes | Authenticated user object |
-| `onSelectConversation` | `(conv: ChatSDKConversation) => void` | Yes | Called when user selects a conversation |
-| `selectedConversationId` | `string` | No | ID of currently selected conversation |
+### Load Messages (with Pagination)
 
-### ThemeToggle
+```tsx
+const messages = await sdk.messages.getMessages({
+  conversationId: conversationId,
+  limit: 50,
+  offset: 0,
+});
+
+messages.forEach(msg => {
+  console.log(`${msg.senderName}: ${msg.content}`);
+});
+```
 
-A button that cycles through light, dark, and auto themes. Must be wrapped in `<ThemeProvider>`.
+### Send Typing Indicator
 
 ```tsx
-<ThemeProvider>
-  <ThemeToggle showLabel />
-</ThemeProvider>
+// User started typing
+await sdk.messages.sendTypingIndicator(conversationId, true);
+
+// User stopped typing
+await sdk.messages.sendTypingIndicator(conversationId, false);
 ```
 
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `className` | `string` | No | Additional CSS class name |
-| `showLabel` | `boolean` | No | Show current theme label text |
+### 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);
+```
 
-## Hooks
+---
 
-### useTheme
+## 7. File Uploads & Attachments
 
-Theme management (light, dark, auto).
+### Upload and Send a File
 
 ```tsx
-import { useTheme } from '@traiyani/chatsdk-react';
+const sdk = ChatSDK.getInstance();
 
-function MyComponent() {
-  const { theme, actualTheme, setTheme, toggleTheme } = useTheme();
-  return <button onClick={toggleTheme}>Current: {actualTheme}</button>;
-}
+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);
 ```
 
-### useThemeContext
-
-Same API as `useTheme`, but reads from the nearest `<ThemeProvider>` so all descendants share state.
+### Convenience Methods
 
 ```tsx
-import { useThemeContext } from '@traiyani/chatsdk-react';
+// Send image
+await sdk.media.sendImage(conversationId, imageFile, 'Photo caption');
+
+// Send video
+await sdk.media.sendVideo(conversationId, videoFile);
 
-const { theme, actualTheme, setTheme, toggleTheme } = useThemeContext();
+// Send document (PDF, DOC, etc.)
+await sdk.media.sendDocument(conversationId, pdfFile);
+
+// Send audio
+await sdk.media.sendAudio(conversationId, audioFile);
 ```
 
-## Configuration
+**Supported file types:** Images (`.jpg`, `.png`, `.gif`, `.webp`), Videos (`.mp4`, `.mov`), Documents (`.pdf`, `.doc`, `.docx`), Audio (`.mp3`, `.wav`)
 
-Config values can come from any source — environment variables, server-rendered props, a config file, or hardcoded values:
+**Note:** The built-in `<ChatWindow />` component handles file picking, uploading, and preview automatically.
 
-```tsx
-// Create React App
-await sdk.init({ apiBaseUrl: process.env.REACT_APP_API_URL, ... })
+---
 
-// Vite
-await sdk.init({ apiBaseUrl: import.meta.env.VITE_API_URL, ... })
+## 8. Unread Message Counts
 
-// Next.js
-await sdk.init({ apiBaseUrl: process.env.NEXT_PUBLIC_API_URL, ... })
+### Get Unread Conversations Count
 
-// Hardcoded / server-rendered
-await sdk.init({ apiBaseUrl: 'https://chat-api.example.com', ... })
+```tsx
+const count = await sdk.chatUsers.getUnreadConversationsCount();
+console.log(`${count} conversations with unread messages`);
 ```
 
-### Full Configuration
+### Get Total Unread Message Count
 
-```typescript
-interface ChatSDKConfig {
-  apiBaseUrl: string;
-  wsUrl?: string;
-  appId: string;
-  apiKey?: string;
-  environment: 'development' | 'staging' | 'production';
-  enableLogging?: boolean;
-  autoConnect?: boolean;
-  timeout?: number;
-}
+```tsx
+const total = await sdk.chatUsers.getTotalUnreadCount();
+console.log(`${total} total unread messages`);
 ```
 
-## Starting a Product-Based Chat
+### Get Detailed Unread Summary
 
 ```tsx
-const sdk = ChatSDK.getInstance();
+const summary = await sdk.chatUsers.getUnreadSummary();
+console.log('Total unread conversations:', summary.totalConversationsWithUnread);
+console.log('Total unread messages:', summary.totalUnreadMessages);
 
-const conversation = await sdk.chatUsers.startChatWithProduct(
-  'unique-group-id',   // externalGroupId for deduplication
-  'seller-user-id',    // the other participant's chat user ID
-  {
-    productId: 'prod-123',
-    productName: 'iPhone 15 Pro',
-    productImage: 'https://example.com/iphone.jpg',
-    price: 4999,
-    currency: 'QAR',
-    category: 'Electronics',
-  }
-);
+summary.unreadSummary.forEach(item => {
+  console.log(`${item.room_name}: ${item.unread_count} unread`);
+});
 ```
 
-## Manager Classes (Advanced Usage)
+### Auto-Mark as Read
 
-Access individual managers through the SDK instance for fine-grained control:
+```tsx
+// When user opens a conversation
+sdk.chatUsers.startViewingConversation(conversationId);
+
+// When user leaves the conversation
+sdk.chatUsers.stopViewingConversation(conversationId);
+```
+
+---
+
+## 9. Block & Unblock Users
 
 ```tsx
-const sdk = ChatSDK.getInstance();
+await sdk.users.blockUser(userIdToBlock);
+await sdk.users.unblockUser(userIdToUnblock);
+const blockedUsers = await sdk.users.getBlockedUsers();
+```
 
-// Users
-const users = await sdk.users.searchUsers({ query: 'john', limit: 10 });
+**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
 
-// Conversations
-const convos = await sdk.conversations.getConversations({ limit: 20 });
+---
 
-// Messages
-const msgs = await sdk.messages.getMessages({ conversationId: 'abc', limit: 50 });
+## 10. Real-Time Events
 
-// Media
-const result = await sdk.media.uploadMedia({ file, type: 'image', conversationId: 'abc' });
+### Listen for Events
 
-// Real-time events
-sdk.socket.on('message_received', (data) => console.log('New message:', data));
+```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);
+});
 ```
 
-## Internationalization
+### 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
-import { t, changeLanguage, getCurrentLanguage, isRTL } from '@traiyani/chatsdk-react';
+sdk.socket.joinConversation(conversationId);
+sdk.socket.leaveConversation(conversationId);
+sdk.socket.sendTypingIndicator(conversationId, true);
+const isConnected = sdk.socket.isConnected();
+```
+
+---
 
-// Get translated string
-const message = t('welcome_message');
+## 11. Theme Support
 
-// Change language
-changeLanguage('ar'); // or 'en'
+```tsx
+import { ThemeProvider, ThemeToggle, useTheme } from '@traiyani/chatsdk-react';
 
-// Check if RTL
-if (isRTL()) {
-  // Apply RTL styles
+// 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();
 ```
 
-Supported locales: `en`, `ar`.
+---
 
-## TypeScript Support
+## 12. Internationalization (i18n)
 
-Full type definitions are included. Import types directly:
+Supported languages: **English** (`en`), **Arabic** (`ar` with RTL)
 
 ```tsx
-import type {
-  ChatSDKUser,
-  ChatSDKMessage,
-  ChatSDKConversation,
-  ChatSDKConfig,
-  ProductContext,
-  ChatWindowProps,
-  ConversationListProps,
-} from '@traiyani/chatsdk-react';
+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
 ```
 
-## Styling
+---
 
-Import the CSS file once in your app entry point:
+## 13. Logout & Cleanup
 
 ```tsx
-import '@traiyani/chatsdk-react/dist/chatsdk.css';
+const sdk = ChatSDK.getInstance();
+
+// Disconnect WebSocket
+sdk.socket.disconnect();
+
+// Logout (clears token)
+await sdk.chatUsers.logout();
 ```
 
-All theme colors, conversation styles, and utility classes are bundled into this single file.
+---
 
-## Features
+## 14. TypeScript Support
 
-- React 16.8+ with TypeScript
-- Real-time messaging via Socket.io
-- File/image uploads with progress
-- Product-based conversations
-- Block/unblock users
-- Theme support (light / dark / auto)
-- Internationalization (EN / AR with RTL)
-- Responsive design (desktop + mobile)
-- Message status (sending, sent, delivered, read)
-- Typing indicators
-- Unread message counts with badges
-- Search conversations
-- Pre-built — works with any bundler, no build config needed
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@traiyani/chatsdk-react",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "ChatSDK React SDK - Pre-built, plug-and-play real-time chat components for React",
   "main": "dist/chatsdk-react.cjs",
   "module": "dist/chatsdk-react.mjs",