urasoft-live-support 1.0.0

package/README.md

@@ -0,0 +1,1413 @@
+# @urasoft/live-chat-widget
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/@urasoft/live-chat-widget.svg)](https://www.npmjs.com/package/@urasoft/live-chat-widget)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+
+**Universal live chat widget library for web applications**
+
+A modern, TypeScript-based chat widget with SignalR support, styled with Tailwind CSS. Works seamlessly with Vue, React, Next.js, Angular, or vanilla JavaScript.
+
+[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-documentation)
+
+</div>
+
+---
+
+## 🚀 Features
+
+-   💬 **Framework Agnostic** - Works with Vue, React, Next.js, Angular, or vanilla JavaScript
+-   🔌 **Built-in SignalR** - Real-time communication with configurable Hub connection
+-   🌐 **HTTP REST API Support** - Send messages via HTTP endpoints with custom body mapping
+-   🔄 **Hybrid Mode** - Send via HTTP, receive via SignalR (perfect for existing APIs)
+-   🔄 **Smart Reconnection** - Multiple reconnection strategies (exponential, linear, fixed, custom)
+-   📡 **10+ Event Callbacks** - Full control over connection lifecycle
+-   🎨 **Fully Customizable** - Position, colors, messages, and styling
+-   📱 **Responsive Design** - Mobile and desktop-friendly
+-   ⚡ **Lightweight** - Minimal dependencies, optimized bundle size
+-   🎯 **TypeScript First** - Complete type definitions with IntelliSense support
+-   🌐 **Flexible Configuration** - Headers (static/dynamic), query params, JWT token support
+-   🎛️ **Transport Options** - WebSockets, Server-Sent Events, or Long Polling
+
+## 📦 Installation
+
+```bash
+npm install @urasoft/live-chat-widget
+```
+
+Or with yarn:
+
+```bash
+yarn add @urasoft/live-chat-widget
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @urasoft/live-chat-widget
+```
+
+## 🔧 Quick Start
+
+### Basic Usage with SignalR
+
+```typescript
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+const chat = new ChatWidget({
+	position: "bottom-right",
+	primaryColor: "#007bff",
+	title: "Live Support",
+	signalR: {
+		hubUrl: "https://your-server.com/chatHub",
+	},
+});
+```
+
+### With JWT Authentication
+
+```typescript
+const chat = new ChatWidget({
+	position: "bottom-right",
+	signalR: {
+		hubUrl: "/chatHub",
+		accessTokenFactory: async () => {
+			const response = await fetch("/api/auth/token");
+			const data = await response.json();
+			return data.token;
+		},
+	},
+});
+```
+
+### HTTP + SignalR Hybrid (Send via HTTP, Receive via SignalR)
+
+```typescript
+const chat = new ChatWidget({
+	position: "bottom-right",
+	primaryColor: "#007bff",
+	title: "Live Support",
+	// HTTP: Send messages via REST API
+	http: {
+		sendEndpoint: "https://api.example.com/chat/messages",
+		method: "POST",
+		headers: {
+			"Authorization": "Bearer YOUR_TOKEN",
+			"Content-Type": "application/json"
+		},
+		bodyMapper: (message) => ({
+			content: message,
+			userId: "user-123",
+			timestamp: new Date().toISOString()
+		})
+	},
+	// SignalR: Receive messages in real-time
+	signalR: {
+		hubUrl: "https://api.example.com/chatHub",
+		receiveMethodName: "ReceiveMessage",
+		onMessageReceived: (message) => {
+			console.log("New message:", message);
+		}
+	}
+});
+```
+
+### User Flow
+
+**SignalR Only (Default):**
+1. User clicks the chat bubble
+2. Clicks "Connect to Live Support" button
+3. SignalR connection is established automatically
+4. Real-time messaging begins
+5. User can disconnect by clicking the disconnect button (🔌)
+
+**HTTP + SignalR Hybrid:**
+1. User clicks the chat bubble (no connection button needed)
+2. User can immediately start typing
+3. Messages are sent via HTTP POST to your API
+4. Responses are received via SignalR in real-time
+
+## 📖 Documentation
+
+### Table of Contents
+
+-   [Configuration Options](#configuration-options)
+-   [SignalR Integration](#signalr-integration)
+    -   [Reconnection Strategies](#reconnection-strategies)
+    -   [Event Callbacks](#event-callbacks)
+    -   [Transport & Logging](#transport--logging)
+-   [HTTP Integration](#http-integration)
+    -   [Basic HTTP Setup](#basic-http-setup)
+    -   [Custom Body Mapping](#custom-body-mapping)
+    -   [Dynamic Headers](#dynamic-headers)
+    -   [HTTP + SignalR Hybrid](#http--signalr-hybrid-1)
+-   [Framework Integration](#framework-integration)
+    -   [React / Next.js](#react--nextjs)
+    -   [Vue 3](#vue-3)
+    -   [Angular](#angular)
+    -   [Vanilla JavaScript](#vanilla-javascript)
+-   [API Methods](#api-methods)
+-   [Backend Setup](#backend-setup)
+
+---
+
+## Configuration Options
+
+### Complete Configuration Interface
+
+```typescript
+interface ChatConfig {
+	// ============================================
+	// UI Configuration
+	// ============================================
+
+	/** Widget position on screen
+	 * @default 'bottom-right'
+	 */
+	position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+
+	/** Primary color for the chat widget
+	 * @default '#007bff'
+	 */
+	primaryColor?: string;
+
+	/** Welcome message displayed when chat opens */
+	welcomeMessage?: string;
+
+	/** Chat header title
+	 * @default 'Live Support'
+	 */
+	title?: string;
+
+	/** Input placeholder text
+	 * @default 'Type your message...'
+	 */
+	placeholder?: string;
+
+	/** Agent/Support team name
+	 * @default 'Support Team'
+	 */
+	agentName?: string;
+
+	/** Agent avatar URL */
+	agentAvatar?: string;
+
+	/** Auto-open chat on page load
+	 * @default false
+	 */
+	autoOpen?: boolean;
+
+	/** Chat button icon
+	 * @default '💬'
+	 */
+	buttonIcon?: string;
+
+	// ============================================
+	// SignalR Configuration
+	// ============================================
+
+	signalR?: {
+		/** SignalR Hub URL (required) */
+		hubUrl: string;
+
+		/** Query parameters appended to Hub URL */
+		queryParams?: Record<string, string>;
+
+		/** HTTP Headers sent with the connection */
+		headers?: Record<string, string>;
+
+		/** Function to retrieve JWT token for authentication */
+		accessTokenFactory?: () => string | Promise<string>;
+
+		/** Hub method name for sending messages
+		 * @default 'SendMessage'
+		 */
+		sendMethodName?: string;
+
+		/** Hub method name for receiving messages
+		 * @default 'ReceiveMessage'
+		 */
+		receiveMethodName?: string;
+
+		// ============================================
+		// Reconnection Settings
+		// ============================================
+
+		reconnect?: {
+			/** Maximum number of reconnection attempts
+			 * @default 5
+			 */
+			maxRetries?: number;
+
+			/** Reconnection delay strategy
+			 * - exponential: 1s, 2s, 4s, 8s, 16s... (default)
+			 * - linear: 1s, 2s, 3s, 4s, 5s...
+			 * - fixed: same delay each time
+			 * - custom function: (retryCount) => delayInMs
+			 * @default 'exponential'
+			 */
+			delayStrategy?:
+				| "exponential"
+				| "linear"
+				| "fixed"
+				| ((retryCount: number) => number);
+
+			/** Initial delay in milliseconds
+			 * @default 1000
+			 */
+			initialDelay?: number;
+
+			/** Maximum delay in milliseconds
+			 * @default 30000
+			 */
+			maxDelay?: number;
+
+			/** Fixed delay in milliseconds (when using 'fixed' strategy)
+			 * @default 5000
+			 */
+			fixedDelay?: number;
+
+			/** Disable automatic reconnection
+			 * @default false
+			 */
+			disableAutoReconnect?: boolean;
+		};
+
+		// ============================================
+		// Event Callbacks
+		// ============================================
+
+		/** Called when connection is established */
+		onConnected?: (connectionId?: string) => void;
+
+		/** Called when connection is lost */
+		onDisconnected?: (error?: Error) => void;
+
+		/** Called when reconnection attempt starts */
+		onReconnecting?: (error?: Error) => void;
+
+		/** Called when reconnection succeeds */
+		onReconnected?: (connectionId?: string) => void;
+
+		/** Called before each retry attempt */
+		onRetry?: (
+			retryCount: number,
+			delayMs: number,
+			elapsedMs?: number
+		) => void;
+
+		/** Called when all reconnection attempts fail */
+		onReconnectFailed?: () => void;
+
+		/** Called when a message is received */
+		onMessageReceived?: (message: any) => void;
+
+		/** Called before sending a message (can modify message) */
+		onBeforeSend?: (message: string) => string | Promise<string>;
+
+		/** Called after message is sent */
+		onAfterSend?: (message: string) => void;
+
+		/** Called when any error occurs */
+		onError?: (error: Error) => void;
+
+		// ============================================
+		// Transport & Logging
+		// ============================================
+
+		/** Transport protocol
+		 * @default 'All'
+		 */
+		transport?: "WebSockets" | "ServerSentEvents" | "LongPolling" | "All";
+
+		/** Logging level
+		 * @default 'Information'
+		 */
+		logLevel?:
+			| "Trace"
+			| "Debug"
+			| "Information"
+			| "Warning"
+			| "Error"
+			| "Critical"
+			| "None";
+	};
+
+	// ============================================
+	// HTTP Configuration (Optional - for REST API message sending)
+	// ============================================
+
+	http?: {
+		/** HTTP Endpoint URL for sending messages (required) */
+		sendEndpoint: string;
+
+		/** HTTP Method
+		 * @default 'POST'
+		 */
+		method?: "POST" | "PUT" | "PATCH";
+
+		/** HTTP Headers (static or dynamic function) */
+		headers?:
+			| Record<string, string>
+			| (() => Record<string, string> | Promise<Record<string, string>>);
+
+		/** Custom body mapper - transform message before sending
+		 * @example (message) => ({ content: message, userId: '123' })
+		 */
+		bodyMapper?: (message: string, attachments?: FileAttachment[]) => any;
+
+		/** Response handler (optional) */
+		onResponse?: (response: Response) => void | Promise<void>;
+
+		/** Error handler */
+		onError?: (error: Error) => void;
+
+		/** Request timeout in milliseconds
+		 * @default 30000
+		 */
+		timeout?: number;
+	};
+
+	/** Callback when message is sent (when NOT using SignalR or HTTP) */
+	onSendMessage?: (message: string) => void;
+}
+```
+
+---
+
+## SignalR Integration
+
+### Basic SignalR Setup
+
+The widget automatically manages SignalR connections:
+
+```typescript
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "https://api.example.com/chatHub",
+	},
+});
+```
+
+### Reconnection Strategies
+
+The widget supports multiple reconnection strategies when connection is lost.
+
+#### 1. Exponential Backoff (Default)
+
+Delay doubles with each attempt: 1s → 2s → 4s → 8s → 16s...
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		reconnect: {
+			maxRetries: 10,
+			delayStrategy: "exponential",
+			initialDelay: 1000, // Start with 1 second
+			maxDelay: 60000, // Cap at 60 seconds
+		},
+		onRetry: (retryCount, delayMs) => {
+			console.log(`🔄 Retry attempt ${retryCount}, waiting ${delayMs}ms`);
+		},
+		onReconnected: (connectionId) => {
+			console.log("✅ Reconnected:", connectionId);
+		},
+		onReconnectFailed: () => {
+			console.error("❌ All reconnection attempts failed");
+			alert("Unable to connect. Please refresh the page.");
+		},
+	},
+});
+```
+
+#### 2. Linear Backoff
+
+Delay increases linearly: 1s → 2s → 3s → 4s → 5s...
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		reconnect: {
+			maxRetries: 5,
+			delayStrategy: "linear",
+			initialDelay: 2000, // Start with 2 seconds
+		},
+	},
+});
+```
+
+#### 3. Fixed Delay
+
+Same delay for each attempt: 5s → 5s → 5s → 5s...
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		reconnect: {
+			maxRetries: 8,
+			delayStrategy: "fixed",
+			fixedDelay: 5000, // Wait 5 seconds between each attempt
+		},
+	},
+});
+```
+
+#### 4. Custom Delay Function
+
+Define your own reconnection strategy:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		reconnect: {
+			maxRetries: 10,
+			delayStrategy: (retryCount) => {
+				// Custom strategy: Fibonacci-like delays
+				if (retryCount === 0) return 1000;
+				if (retryCount === 1) return 1000;
+				return Math.min(
+					fibonacci(retryCount) * 1000,
+					60000 // Cap at 60 seconds
+				);
+			},
+		},
+	},
+});
+
+function fibonacci(n: number): number {
+	if (n <= 1) return 1;
+	return fibonacci(n - 1) + fibonacci(n - 2);
+}
+```
+
+### Event Callbacks
+
+Monitor every stage of the SignalR connection lifecycle:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+
+		// Connection established
+		onConnected: (connectionId) => {
+			console.log("✅ Connected, Connection ID:", connectionId);
+			analytics.track("chat_connected");
+		},
+
+		// Connection lost
+		onDisconnected: (error) => {
+			console.log("❌ Disconnected:", error?.message);
+			analytics.track("chat_disconnected");
+		},
+
+		// Reconnection started
+		onReconnecting: (error) => {
+			console.log("🔄 Reconnecting...", error?.message);
+			// Show "Connecting..." in UI
+		},
+
+		// Reconnection succeeded
+		onReconnected: (connectionId) => {
+			console.log("✅ Reconnected:", connectionId);
+			// Show "Connected" in UI
+		},
+
+		// Before each retry attempt
+		onRetry: (retryCount, delayMs, elapsedMs) => {
+			console.log(`🔄 Attempt ${retryCount}, will wait ${delayMs}ms`);
+			console.log(`⏱️ Total elapsed time: ${elapsedMs}ms`);
+			// Update progress bar
+		},
+
+		// All retry attempts exhausted
+		onReconnectFailed: () => {
+			console.error("❌ Reconnection failed");
+			alert("Cannot connect to server. Please refresh the page.");
+		},
+
+		// Message received
+		onMessageReceived: (message) => {
+			console.log("📩 Message received:", message);
+			playNotificationSound();
+		},
+
+		// Before sending message (can modify it)
+		onBeforeSend: async (message) => {
+			console.log("📤 Sending:", message);
+			// Encrypt, sanitize, or format the message
+			const sanitized = sanitizeMessage(message);
+			return sanitized;
+		},
+
+		// After message sent
+		onAfterSend: (message) => {
+			console.log("✅ Sent:", message);
+			analytics.track("message_sent", { length: message.length });
+		},
+
+		// Any error occurs
+		onError: (error) => {
+			console.error("⚠️ SignalR Error:", error.message);
+			// Send to error tracking service (Sentry, LogRocket, etc.)
+			errorReporter.captureException(error);
+		},
+
+		reconnect: {
+			maxRetries: 5,
+			delayStrategy: "exponential",
+		},
+	},
+});
+```
+
+### Transport & Logging
+
+Configure transport protocol and logging level:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+
+		// Transport type
+		// Options: 'WebSockets' | 'ServerSentEvents' | 'LongPolling' | 'All'
+		transport: "WebSockets",
+
+		// Log level
+		// Use 'Debug' for development, 'Warning' or 'Error' for production
+		// Options: 'Trace' | 'Debug' | 'Information' | 'Warning' | 'Error' | 'Critical' | 'None'
+		logLevel: "Debug",
+	},
+});
+```
+
+### JWT Authentication
+
+Secure your connection with JWT tokens:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		accessTokenFactory: async () => {
+			const response = await fetch("/api/auth/token");
+			const { token } = await response.json();
+			return token;
+		},
+	},
+});
+```
+
+### Query Parameters
+
+Pass user information via query parameters:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		queryParams: {
+			userId: currentUser.id,
+			userName: currentUser.name,
+			department: "support",
+			language: "en",
+		},
+	},
+});
+```
+
+### Custom Headers
+
+Add custom HTTP headers to the connection:
+
+```typescript
+const chat = new ChatWidget({
+	signalR: {
+		hubUrl: "/chatHub",
+		headers: {
+			"X-Api-Key": "your-api-key",
+			"X-Client-Version": "1.0.0",
+			"X-Device-Id": deviceId,
+		},
+	},
+});
+```
+
+---
+
+## HTTP Integration
+
+The widget supports sending messages via HTTP REST API while optionally receiving messages through SignalR. This hybrid approach is perfect for scenarios where you want to use your existing REST API for message submission.
+
+### Basic HTTP Setup
+
+Send messages via HTTP POST to your API endpoint:
+
+```typescript
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+const chat = new ChatWidget({
+	position: "bottom-right",
+	primaryColor: "#007bff",
+	title: "Support Chat",
+	http: {
+		sendEndpoint: "https://api.example.com/chat/messages",
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"Authorization": "Bearer YOUR_API_TOKEN"
+		}
+	}
+});
+```
+
+**Default Request Body Format:**
+```json
+{
+  "message": "User's message text",
+  "attachments": [],
+  "timestamp": "2025-01-15T10:30:00.000Z"
+}
+```
+
+### Custom Body Mapping
+
+Transform the message into your API's expected format:
+
+```typescript
+const chat = new ChatWidget({
+	http: {
+		sendEndpoint: "https://api.example.com/messages",
+		bodyMapper: (message, attachments) => ({
+			// Custom format for your API
+			content: message,
+			userId: getCurrentUserId(),
+			sessionId: getSessionId(),
+			files: attachments?.map(f => ({
+				filename: f.name,
+				base64: f.data,
+				mimeType: f.type
+			})),
+			metadata: {
+				timestamp: new Date().toISOString(),
+				platform: "web",
+				language: navigator.language
+			}
+		})
+	}
+});
+```
+
+### Dynamic Headers
+
+Use a function to provide dynamic headers (e.g., fresh JWT tokens):
+
+```typescript
+const chat = new ChatWidget({
+	http: {
+		sendEndpoint: "/api/chat/send",
+		headers: async () => {
+			// Fetch fresh token on every request
+			const token = await getAccessToken();
+			return {
+				"Content-Type": "application/json",
+				"Authorization": `Bearer ${token}`,
+				"X-Request-ID": generateRequestId(),
+				"X-User-ID": getCurrentUserId()
+			};
+		},
+		bodyMapper: (message) => ({
+			text: message,
+			userId: getCurrentUserId()
+		})
+	}
+});
+```
+
+### HTTP + SignalR Hybrid
+
+**Perfect use case:** Send messages via your REST API, receive responses via SignalR
+
+```typescript
+const chat = new ChatWidget({
+	position: "bottom-right",
+
+	// HTTP: Send messages to REST API
+	http: {
+		sendEndpoint: "https://api.example.com/chat/messages",
+		method: "POST",
+		headers: async () => ({
+			"Authorization": `Bearer ${await getToken()}`,
+			"Content-Type": "application/json"
+		}),
+		bodyMapper: (message) => ({
+			content: message,
+			userId: currentUser.id,
+			conversationId: conversationId
+		}),
+		onResponse: async (response) => {
+			const data = await response.json();
+			console.log("Message sent successfully:", data.messageId);
+		},
+		onError: (error) => {
+			console.error("Failed to send message:", error);
+			alert("Could not send message. Please try again.");
+		},
+		timeout: 10000 // 10 seconds
+	},
+
+	// SignalR: Receive messages in real-time
+	signalR: {
+		hubUrl: "https://api.example.com/chatHub",
+		queryParams: {
+			userId: currentUser.id,
+			conversationId: conversationId
+		},
+		receiveMethodName: "ReceiveMessage",
+		onConnected: (connectionId) => {
+			console.log("Connected to SignalR:", connectionId);
+		},
+		onMessageReceived: (message) => {
+			console.log("New message received:", message);
+		},
+		reconnect: {
+			maxRetries: 5,
+			delayStrategy: "exponential"
+		}
+	}
+});
+```
+
+### Error Handling & Response Processing
+
+```typescript
+const chat = new ChatWidget({
+	http: {
+		sendEndpoint: "/api/chat/messages",
+
+		// Handle successful responses
+		onResponse: async (response) => {
+			const data = await response.json();
+
+			// Track analytics
+			analytics.track("message_sent", {
+				messageId: data.id,
+				timestamp: data.timestamp
+			});
+
+			// Show confirmation toast
+			if (data.queued) {
+				showToast("Your message is being processed...");
+			}
+		},
+
+		// Handle errors
+		onError: (error) => {
+			// Log to error tracking service
+			errorTracker.captureException(error);
+
+			// Show user-friendly message
+			if (error.name === "AbortError") {
+				showToast("Request timed out. Please try again.");
+			} else if (error.message.includes("401")) {
+				showToast("Session expired. Please log in again.");
+				redirectToLogin();
+			} else {
+				showToast("Failed to send message. Please check your connection.");
+			}
+		},
+
+		timeout: 15000 // 15 seconds
+	}
+});
+```
+
+### HTTP Only (No SignalR)
+
+If you don't need real-time message receiving:
+
+```typescript
+const chat = new ChatWidget({
+	position: "bottom-right",
+	title: "Contact Us",
+	welcomeMessage: "Send us a message and we'll get back to you soon!",
+
+	http: {
+		sendEndpoint: "https://api.example.com/contact/submit",
+		bodyMapper: (message) => ({
+			message: message,
+			email: userEmail,
+			subject: "Website Inquiry",
+			timestamp: new Date().toISOString()
+		}),
+		onResponse: async (response) => {
+			const data = await response.json();
+			// Show success message in chat
+			chat.addAgentMessage(
+				`Thank you! Your message has been received. Reference: ${data.ticketId}`
+			);
+		}
+	}
+});
+```
+
+### Backend API Example (Node.js/Express)
+
+```javascript
+app.post("/api/chat/messages", async (req, res) => {
+  const { content, userId, conversationId } = req.body;
+
+  // Save message to database
+  const message = await db.messages.create({
+    content,
+    userId,
+    conversationId,
+    timestamp: new Date()
+  });
+
+  // Process message (AI, routing, etc.)
+  const response = await processMessage(message);
+
+  // Send response via SignalR to user
+  await signalRHub.clients.user(userId).send("ReceiveMessage", {
+    text: response.content,
+    avatar: response.agentAvatar,
+    timestamp: new Date()
+  });
+
+  // Return confirmation
+  res.json({
+    success: true,
+    messageId: message.id,
+    queued: true
+  });
+});
+```
+
+---
+
+## Framework Integration
+
+### React / Next.js
+
+```tsx
+"use client"; // For Next.js 13+ App Router
+
+import { useEffect, useRef } from "react";
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+export default function ChatComponent() {
+	const chatRef = useRef<ChatWidget | null>(null);
+
+	useEffect(() => {
+		chatRef.current = new ChatWidget({
+			position: "bottom-right",
+			primaryColor: "#007bff",
+			title: "Live Support",
+			signalR: {
+				hubUrl: process.env.NEXT_PUBLIC_CHAT_HUB_URL || "/chatHub",
+				queryParams: {
+					userId: "user-123",
+				},
+				accessTokenFactory: async () => {
+					const response = await fetch("/api/auth/token");
+					const data = await response.json();
+					return data.token;
+				},
+				onConnected: (connectionId) => {
+					console.log("Chat connected:", connectionId);
+				},
+				onMessageReceived: (message) => {
+					console.log("New message:", message);
+				},
+			},
+		});
+
+		return () => {
+			chatRef.current?.destroy();
+		};
+	}, []);
+
+	return null;
+}
+```
+
+### Vue 3
+
+```vue
+<template>
+	<div></div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, onUnmounted } from "vue";
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+let chat: ChatWidget | null = null;
+
+onMounted(() => {
+	chat = new ChatWidget({
+		position: "bottom-right",
+		primaryColor: "#42b883",
+		title: "Live Support",
+		signalR: {
+			hubUrl: import.meta.env.VITE_CHAT_HUB_URL || "/chatHub",
+			queryParams: {
+				sessionId: "vue-session-123",
+			},
+			onConnected: (connectionId) => {
+				console.log("Chat connected:", connectionId);
+			},
+			onMessageReceived: (message) => {
+				console.log("New message:", message);
+			},
+		},
+	});
+});
+
+onUnmounted(() => {
+	chat?.destroy();
+});
+</script>
+```
+
+### Angular
+
+```typescript
+import { Component, OnInit, OnDestroy } from "@angular/core";
+import { ChatWidget } from "@urasoft/live-chat-widget";
+import "@urasoft/live-chat-widget/dist/styles.css";
+
+@Component({
+	selector: "app-chat",
+	template: "",
+})
+export class ChatComponent implements OnInit, OnDestroy {
+	private chat: ChatWidget | null = null;
+
+	ngOnInit() {
+		this.chat = new ChatWidget({
+			position: "bottom-right",
+			primaryColor: "#dd0031",
+			title: "Live Support",
+			signalR: {
+				hubUrl: "/chatHub",
+				queryParams: {
+					userId: "angular-user-123",
+				},
+				onConnected: (connectionId) => {
+					console.log("Chat connected:", connectionId);
+				},
+				onMessageReceived: (message) => {
+					console.log("New message:", message);
+				},
+			},
+		});
+	}
+
+	ngOnDestroy() {
+		this.chat?.destroy();
+	}
+}
+```
+
+### Vanilla JavaScript
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Chat Widget Demo</title>
+		<link
+			rel="stylesheet"
+			href="node_modules/@urasoft/live-chat-widget/dist/styles.css"
+		/>
+	</head>
+	<body>
+		<h1>My Website</h1>
+
+		<script type="module">
+			import { ChatWidget } from "./node_modules/@urasoft/live-chat-widget/dist/index.esm.js";
+
+			const chat = new ChatWidget({
+				position: "bottom-right",
+				primaryColor: "#007bff",
+				title: "Live Support",
+				welcomeMessage: "Hello! How can we help you today?",
+				signalR: {
+					hubUrl: "https://your-server.com/chatHub",
+					queryParams: {
+						userId: "guest-" + Date.now(),
+					},
+					onConnected: () => {
+						console.log("Connected to live chat");
+					},
+					onMessageReceived: (message) => {
+						console.log("Received:", message);
+					},
+				},
+			});
+		</script>
+	</body>
+</html>
+```
+
+---
+
+## API Methods
+
+### `open()`
+
+Open the chat window programmatically.
+
+```typescript
+chat.open();
+```
+
+### `close()`
+
+Close the chat window programmatically.
+
+```typescript
+chat.close();
+```
+
+### `destroy()`
+
+Completely remove the widget from the page and disconnect SignalR.
+
+```typescript
+chat.destroy();
+```
+
+### `addAgentMessage(message, avatar?)`
+
+Add an agent message programmatically (useful for SignalR message handling).
+
+```typescript
+chat.addAgentMessage("Hello! How can I help you?", "/avatar.png");
+```
+
+### `isConnected()`
+
+Check if SignalR is currently connected.
+
+```typescript
+if (chat.isConnected()) {
+	console.log("Chat is connected");
+}
+```
+
+---
+
+## Backend Setup
+
+### ASP.NET Core SignalR Hub (C#)
+
+```csharp
+using Microsoft.AspNetCore.SignalR;
+
+public class ChatHub : Hub
+{
+    public async Task SendMessage(string message)
+    {
+        // Get user identifier
+        var userId = Context.UserIdentifier;
+        var connectionId = Context.ConnectionId;
+
+        Console.WriteLine($"Message from {userId}: {message}");
+
+        // Process message and generate response
+        var response = await ProcessMessageAsync(message, userId);
+
+        // Send response back to caller
+        await Clients.Caller.SendAsync("ReceiveMessage", response);
+
+        // Or broadcast to all clients
+        // await Clients.All.SendAsync("ReceiveMessage", response);
+    }
+
+    public override async Task OnConnectedAsync()
+    {
+        // Get query parameters
+        var httpContext = Context.GetHttpContext();
+        var userId = httpContext?.Request.Query["userId"];
+        var userName = httpContext?.Request.Query["userName"];
+
+        Console.WriteLine($"User connected: {userId} ({userName})");
+
+        // Send welcome message
+        await Clients.Caller.SendAsync("ReceiveMessage",
+            "Welcome to live support! How can we help you today?");
+
+        await base.OnConnectedAsync();
+    }
+
+    public override async Task OnDisconnectedAsync(Exception? exception)
+    {
+        Console.WriteLine($"User disconnected: {Context.ConnectionId}");
+
+        if (exception != null)
+        {
+            Console.WriteLine($"Disconnection error: {exception.Message}");
+        }
+
+        await base.OnDisconnectedAsync(exception);
+    }
+
+    private async Task<string> ProcessMessageAsync(string message, string userId)
+    {
+        // Add your message processing logic here
+        // e.g., AI chatbot, database queries, etc.
+
+        await Task.Delay(500); // Simulate processing
+
+        return $"You said: {message}. How else can I assist you?";
+    }
+}
+```
+
+### Configure SignalR in Startup/Program.cs
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Add SignalR
+builder.Services.AddSignalR();
+
+// Add CORS if needed
+builder.Services.AddCors(options =>
+{
+    options.AddPolicy("ChatPolicy", policy =>
+    {
+        policy.WithOrigins("http://localhost:3000", "https://yourdomain.com")
+              .AllowAnyHeader()
+              .AllowAnyMethod()
+              .AllowCredentials();
+    });
+});
+
+var app = builder.Build();
+
+app.UseCors("ChatPolicy");
+
+// Map SignalR hub
+app.MapHub<ChatHub>("/chatHub");
+
+app.Run();
+```
+
+### Node.js / Express Example
+
+```javascript
+const express = require("express");
+const http = require("http");
+const { Server } = require("socket.io");
+
+const app = express();
+const server = http.createServer(app);
+const io = new Server(server, {
+	cors: {
+		origin: "http://localhost:3000",
+		methods: ["GET", "POST"],
+	},
+});
+
+io.on("connection", (socket) => {
+	console.log("User connected:", socket.id);
+
+	// Get query parameters
+	const { userId, userName } = socket.handshake.query;
+	console.log(`User: ${userName} (${userId})`);
+
+	// Send welcome message
+	socket.emit("ReceiveMessage", "Welcome to live support!");
+
+	// Handle incoming messages
+	socket.on("SendMessage", (message) => {
+		console.log("Message received:", message);
+
+		// Process and respond
+		const response = `You said: ${message}`;
+		socket.emit("ReceiveMessage", response);
+	});
+
+	socket.on("disconnect", () => {
+		console.log("User disconnected:", socket.id);
+	});
+});
+
+server.listen(3001, () => {
+	console.log("SignalR server running on port 3001");
+});
+```
+
+---
+
+## Custom Styling
+
+### Using CSS Variables
+
+```css
+:root {
+	--chat-primary-color: #007bff;
+	--chat-secondary-color: #6c757d;
+	--chat-background: #ffffff;
+	--chat-text-color: #212529;
+}
+```
+
+### Overriding Tailwind Classes
+
+```css
+/* Override specific chat widget styles */
+.chat-widget-container {
+	/* Your custom styles */
+}
+
+.chat-header {
+	background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.chat-message {
+	border-radius: 12px;
+}
+```
+
+---
+
+## Troubleshooting
+
+### Connection Issues
+
+**Problem:** Chat won't connect to SignalR Hub
+
+**Solutions:**
+
+-   Verify `hubUrl` is correct and accessible
+-   Check CORS settings on your server
+-   Ensure SignalR Hub is properly configured
+-   Check browser console for error messages
+-   Verify `accessTokenFactory` returns valid token (if using authentication)
+
+### Reconnection Not Working
+
+**Problem:** Chat doesn't reconnect after connection loss
+
+**Solutions:**
+
+-   Check `disableAutoReconnect` is not set to `true`
+-   Verify `maxRetries` is greater than 0
+-   Check `onError` callback for error details
+-   Ensure network connectivity is restored
+
+### Messages Not Displaying
+
+**Problem:** Messages sent but not appearing in chat
+
+**Solutions:**
+
+-   Verify `receiveMethodName` matches server-side method
+-   Check `onMessageReceived` callback is firing
+-   Ensure message format matches expected structure
+-   Check browser console for errors
+
+---
+
+## Performance Tips
+
+1. **Use WebSockets transport** for best performance:
+
+    ```typescript
+    signalR: {
+    	transport: "WebSockets";
+    }
+    ```
+
+2. **Adjust log level in production**:
+
+    ```typescript
+    signalR: {
+    	logLevel: "Warning"; // or "Error"
+    }
+    ```
+
+3. **Implement message throttling** in `onBeforeSend`:
+
+    ```typescript
+    onBeforeSend: async (message) => {
+    	await throttle(1000); // Wait 1 second between messages
+    	return message;
+    };
+    ```
+
+4. **Clean up properly** when component unmounts:
+    ```typescript
+    useEffect(() => {
+        const chat = new ChatWidget({...});
+        return () => chat.destroy(); // Important!
+    }, []);
+    ```
+
+---
+
+## Browser Support
+
+-   ✅ Chrome/Edge (latest)
+-   ✅ Firefox (latest)
+-   ✅ Safari (latest)
+-   ✅ Opera (latest)
+-   ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+
+---
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit issues or pull requests.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## License
+
+MIT © [Urasoft](https://urasoft.com)
+
+---
+
+## Links
+
+-   **Documentation:** [GitHub Repository](https://github.com/UrasoftYazilim/live-chat-widget)
+-   **npm Package:** [npmjs.com](https://www.npmjs.com/package/@urasoft/live-chat-widget)
+-   **Issues:** [GitHub Issues](https://github.com/UrasoftYazilim/live-chat-widget/issues)
+-   **Contact:** [Urasoft](https://urasoft.com)
+
+---
+
+<div align="center">
+
+Made with ❤️ by [Urasoft](https://urasoft.com)
+
+**[⬆ back to top](#urasoft-live-chat-widget)**
+
+</div>