@developer.notchatbot/webchat 1.0.8 → 1.0.9

package/README.md

@@ -1,734 +1,734 @@
-# 🔷 WebChat Widget
-
-A beautiful, embeddable chatbot widget built with **React**, **TypeScript**, **Vite**, **pnpm** and **Tailwind CSS** that can be easily integrated into any website with **just one file**.
-
-## ✨ Features
-
-- **📦 Single File Bundle**: Everything in one file - no separate CSS needed!
-- **🔷 TypeScript**: Full type safety with strict typing and excellent IntelliSense
-- **⚛️ React 18**: Component-based architecture for maintainability
-- **🎨 Tailwind CSS**: Utility-first styling with prefixed classes (`ncb-`)
-- **⚡ Vite**: Lightning-fast development and optimized builds
-- **📦 pnpm**: Efficient package management and faster installs
-- **🔧 Easy Integration**: Add to any website with just one script tag
-- **🎨 Modern Design**: Beautiful, responsive UI that works on all devices
-- **🛠️ Customizable**: Configure colors, text, and behavior to match your brand
-- **✨ Smooth Animations**: Typing indicators and smooth transitions
-- **📱 Mobile Responsive**: Optimized for mobile and desktop
-- **🔌 API Ready**: Built-in support for chat API integration
-- **🚫 Zero Conflicts**: Prefixed CSS classes prevent style conflicts
-- **🛡️ Type Safe**: Catch errors at compile time with TypeScript
-
-## 📦 Quick Start
-
-### 1. Add the widget to your website
-
-```html
-<div id="webchat-component"></div>
-
-<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
-<script>
-WebChat.initialize({
-    title: "Customer Support",
-    placeholder: "Ask us anything...",
-    primaryColor: "#667eea"
-});
-</script>
-```
-
-### 2. That's it! 🎉
-
-The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!
-
-## ⚙️ Configuration Options
-
-```typescript
-interface WebChatConfig {
-  title?: string;                       // Chat window title
-  placeholder?: string;                 // Input placeholder text
-  primaryColor?: string;                // Primary theme color
-  apiKey?: string;                      // Your chatbot UID (required for API)
-  position?: 'bottom-right' | 'bottom-left'; // Widget position
-  initialMessage?: string;              // Custom initial bot message
-  closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
-  closeButtonText?: string;             // Text for close button (when type is 'text')
-  closeButtonCustomIcon?: string;       // Custom icon SVG or URL (when type is 'custom')
-  marginBottom?: number;                // Distance from bottom edge in pixels (default: 16)
-  marginSide?: number;                  // Distance from left/right edge in pixels (default: 16)
-  mobile?: WebChatPositionConfig;       // Mobile-specific position settings
-  desktop?: WebChatPositionConfig;      // Desktop-specific position settings
-}
-
-interface WebChatPositionConfig {
-  position?: 'bottom-right' | 'bottom-left';
-  marginBottom?: number;
-  marginSide?: number;
-}
-
-WebChat.initialize({
-    title: "Chat Assistant",
-    placeholder: "Type your message...",
-    primaryColor: "#007bff",
-    apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
-    position: "bottom-right",
-    initialMessage: "¡Hola! 👋 Soy tu asistente virtual. ¿En qué puedo ayudarte hoy?",
-    closeButtonIcon: "default", // or "text" or "custom"
-    marginBottom: 20,           // Distance from bottom edge (default: 16px)
-    marginSide: 20,             // Distance from side edge (default: 16px)
-    // Device-specific overrides
-    mobile: {
-        position: "bottom-left",
-        marginBottom: 80,
-        marginSide: 15
-    },
-    desktop: {
-        position: "bottom-right", 
-        marginBottom: 30,
-        marginSide: 30
-    }
-});
-```
-
-## 🎨 Customization
-
-### Colors
-```javascript
-WebChat.initialize({
-    primaryColor: "#ff6b6b",  // Custom brand color
-    // ... other options
-});
-```
-
-### API Integration
-
-The WebChat widget automatically detects the environment and uses the appropriate API endpoints:
-
-- **Development** (localhost): `http://localhost:3001/api/webchat`
-- **Production** (any other domain): `https://next.notchatbot.com/api/webchat`
-
-```javascript
-WebChat.initialize({
-    apiKey: "your-chatbot-uid",    // Chatbot UID from your Next.js admin panel
-    // Endpoints are automatically configured based on environment
-    // No need to specify apiEndpoint manually
-});
-```
-
-#### Manual Endpoint Override (Advanced)
-If you need to override the automatic endpoint detection:
-
-```javascript
-// This is handled automatically, but you can check the environment:
-import { getChatEndpoint, getConversationEndpoint } from './src/config/endpoints';
-
-console.log('Chat endpoint:', getChatEndpoint());
-console.log('Conversation endpoint:', getConversationEndpoint());
-```
-
-### 💬 Initial Message Customization
-Customize the first message your users see when they open the chat:
-
-```javascript
-WebChat.initialize({
-    title: "MiTienda Support",
-    // Custom welcome message with your brand's personality
-    initialMessage: "¡Hola! 👋 Soy el asistente de MiTienda.\n\n¿Buscas algún producto específico? ¡Estoy aquí para ayudarte!\n\nPuedes preguntarme sobre:\n• Productos disponibles\n• Precios y ofertas\n• Envíos y devoluciones\n• Soporte técnico\n\n¿En qué puedo ayudarte hoy? 😊",
-    apiKey: "your-api-key"
-});
-```
-
-### ❌ Close Button Customization
-Customize the appearance of the close button in the chat header:
-
-#### Option 1: Default X Icon (SVG)
-```javascript
-WebChat.initialize({
-    closeButtonIcon: "default" // Standard X icon
-});
-```
-
-#### Option 2: Custom Text
-```javascript
-WebChat.initialize({
-    closeButtonIcon: "text",
-    closeButtonText: "CERRAR" // or "✕", "CLOSE", etc.
-});
-```
-
-#### Option 3: Custom SVG Icon
-```javascript
-WebChat.initialize({
-    closeButtonIcon: "custom",
-    closeButtonCustomIcon: '<svg viewBox="0 0 24 24" fill="currentColor"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>'
-});
-```
-
-#### Option 4: Custom Icon from URL
-```javascript
-WebChat.initialize({
-    closeButtonIcon: "custom",
-    closeButtonCustomIcon: "https://yoursite.com/icons/close-icon.svg"
-});
-```
-
-### 📐 Position and Margins Customization
-Control where the chat widget appears on the screen and how much space it has from the edges:
-
-#### Bottom Right Position (Default)
-```javascript
-WebChat.initialize({
-    position: "bottom-right",
-    marginBottom: 20,  // 20px from bottom edge
-    marginSide: 25,    // 25px from right edge
-    apiKey: "your-api-key"
-});
-```
-
-#### Bottom Left Position
-```javascript
-WebChat.initialize({
-    position: "bottom-left",
-    marginBottom: 30,  // 30px from bottom edge
-    marginSide: 20,    // 20px from left edge
-    apiKey: "your-api-key"
-});
-```
-
-#### Position Examples for Different Layouts
-
-**E-commerce Site (avoid cart button)**
-```javascript
-WebChat.initialize({
-    position: "bottom-left",
-    marginBottom: 20,
-    marginSide: 20,
-    apiKey: "your-api-key"
-});
-```
-
-**Corporate Website (professional look)**
-```javascript
-WebChat.initialize({
-    position: "bottom-right",
-    marginBottom: 40,   // More space from bottom
-    marginSide: 30,     // More space from side
-    apiKey: "your-api-key"
-});
-```
-
-**Mobile-First Design (more accessible)**
-```javascript
-WebChat.initialize({
-    position: "bottom-right",
-    marginBottom: 80,   // Avoid mobile navigation
-    marginSide: 15,     // Less space on mobile
-    apiKey: "your-api-key"
-});
-```
-
-### 💰 Cost Optimization
-The WebChat widget is optimized to minimize API costs:
-
-- **Lazy Loading**: Conversation history is only fetched when the chat is opened, not on page load
-- **Smart Caching**: Once loaded, conversation history is cached to avoid duplicate fetches
-- **Conditional Fetching**: Only fetches when a conversation actually exists
-
-This ensures users can visit your e-commerce site without triggering unnecessary API calls.
-
-### 📱💻 Device-Specific Configurations
-Configure different positions and margins for mobile and desktop devices:
-
-#### Complete Device-Specific Setup
-```javascript
-WebChat.initialize({
-    title: "Customer Support",
-    apiKey: "your-api-key",
-    
-    // Global fallback settings (used if device-specific not provided)
-    position: "bottom-right",
-    marginBottom: 20,
-    marginSide: 20,
-    
-    // Desktop-specific settings
-    desktop: {
-        position: "bottom-right",
-        marginBottom: 30,        // More space on desktop
-        marginSide: 40           // More space from edge
-    },
-    
-    // Mobile-specific settings  
-    mobile: {
-        position: "bottom-left", // Different position on mobile
-        marginBottom: 80,        // Avoid mobile navigation bars
-        marginSide: 15           // Less space on smaller screens
-    }
-});
-```
-
-#### E-commerce Site Example
-```javascript
-WebChat.initialize({
-    title: "Shopping Assistant",
-    apiKey: "your-api-key",
-    
-    // Desktop: bottom-right (standard)
-    desktop: {
-        position: "bottom-right",
-        marginBottom: 25,
-        marginSide: 25
-    },
-    
-    // Mobile: bottom-left (avoid cart/menu buttons)
-    mobile: {
-        position: "bottom-left",
-        marginBottom: 90,        // Clear mobile navigation
-        marginSide: 15
-    }
-});
-```
-
-#### Corporate Website Example
-```javascript
-WebChat.initialize({
-    title: "Business Support",
-    apiKey: "your-api-key",
-    
-    // Consistent position, different margins
-    position: "bottom-right",   // Global fallback
-    
-    desktop: {
-        marginBottom: 40,        // Professional spacing
-        marginSide: 50
-    },
-    
-    mobile: {
-        marginBottom: 70,        // Clear mobile UI elements  
-        marginSide: 20
-    }
-});
-```
-
-## 👨‍💻 Developer Guide
-
-### 🚀 Getting Started
-
-#### Prerequisites
-- **Node.js 18+** (for modern React and TypeScript)
-- **pnpm 8+** (recommended package manager - faster than npm/yarn)
-- **Git** (for version control)
-- **VS Code** (recommended IDE with TypeScript support)
-
-#### Initial Setup
-```bash
-# 1. Clone the repository
-git clone https://github.com/your-username/webchat-widget.git
-cd webchat-widget
-
-# 2. Install dependencies with pnpm (much faster than npm)
-pnpm install
-
-# 3. Start development server
-pnpm dev
-```
-
-The development server will start at `http://localhost:3000` and automatically open `example.html`.
-
-### 🔧 Development Workflow
-
-#### 1. **Understanding the Codebase Structure**
-```
-src/
-├── components/           # React TypeScript components
-│   ├── ChatBot.tsx      # Main container component
-│   ├── ChatButton.tsx   # Floating chat button
-│   ├── ChatWindow.tsx   # Chat window container
-│   ├── ChatHeader.tsx   # Window header with close button
-│   ├── MessageList.tsx  # Scrollable message list
-│   ├── Message.tsx      # Individual message bubble
-│   ├── MessageInput.tsx # Input field with send button
-│   └── TypingIndicator.tsx # Animated typing dots
-├── types.ts             # TypeScript interfaces and types
-├── index.tsx            # Main entry point (exports WebChat API)
-├── vite-env.d.ts        # Type declarations for Vite
-└── styles.css           # Tailwind CSS directives
-```
-
-#### 2. **Adding New Features**
-
-**Step 1: Update Types** (if needed)
-```typescript
-// src/types.ts
-export interface NewFeatureProps {
-  enabled: boolean;
-  config?: SomeConfig;
-}
-```
-
-**Step 2: Create/Modify Components**
-```typescript
-// src/components/NewFeature.tsx
-import React from 'react';
-import type { NewFeatureProps } from '../types';
-
-const NewFeature: React.FC<NewFeatureProps> = ({ enabled, config }) => {
-  // Component logic here
-  return (
-    <div className="nbc-new-feature">
-      {/* Use nbc- prefix for all CSS classes */}
-    </div>
-  );
-};
-
-export default NewFeature;
-```
-
-**Step 3: Add to Main Component**
-```typescript
-// src/components/ChatBot.tsx
-import NewFeature from './NewFeature';
-
-// Use the new component in ChatBot
-```
-
-#### 3. **Styling Guidelines**
-
-- **Always use `nbc-` prefix** for CSS classes to avoid conflicts
-- **Use Tailwind utilities** whenever possible
-- **Follow the existing pattern** for consistent styling
-
-```tsx
-// ✅ Good - uses nbc- prefix
-<div className="nbc-bg-blue-500 nbc-text-white nbc-p-4">
-
-// ❌ Bad - no prefix, will conflict with host site
-<div className="bg-blue-500 text-white p-4">
-```
-
-#### 4. **TypeScript Best Practices**
-
-- **Define interfaces** for all component props
-- **Use strict typing** for functions and variables
-- **Leverage IntelliSense** for better development experience
-
-```typescript
-// ✅ Good - strict typing
-const handleMessage = (message: string): void => {
-  // Function implementation
-};
-
-// ❌ Bad - no typing
-const handleMessage = (message) => {
-  // Function implementation
-};
-```
-
-### 🏗️ Building & Compilation
-
-#### Development Build
-```bash
-# Start development server with hot reload
-pnpm dev
-
-# Access at: http://localhost:3000
-# Changes are reflected immediately
-```
-
-#### Production Build
-```bash
-# Build for production (TypeScript compilation + bundling)
-pnpm build
-
-# Output: dist/webchat-bundle.min.umd.cjs (single file)
-# Size: ~159KB (50KB gzipped)
-```
-
-#### Build Process Explanation
-1. **TypeScript Compilation** (`tsc`) - Type checking and compilation
-2. **Vite Bundling** - Bundles React, CSS, and all dependencies
-3. **CSS Injection** - Inlines CSS into JavaScript for single-file output
-4. **Minification** - Optimizes and compresses the output
-
-### 🧪 Testing the Compiled Version
-
-#### Option 1: Preview Server
-```bash
-# Build and start preview server
-pnpm build
-pnpm preview
-
-# Access at: http://localhost:4173
-# Tests the actual production build
-```
-
-#### Option 2: Local Testing
-```bash
-# After building, test locally
-pnpm build
-
-# Open example/production.html in browser
-# Or serve with any static file server
-python3 -m http.server 8000
-# Then visit: http://localhost:8000/example/production.html
-```
-
-#### Option 3: Integration Testing
-Create a test HTML file:
-```html
-<!DOCTYPE html>
-<html>
-<head>
-    <title>Widget Test</title>
-</head>
-<body>
-    <h1>Testing WebChat Widget</h1>
-    <div id="chat-test"></div>
-    
-    <!-- Load your built widget -->
-    <script src="./dist/webchat-bundle.min.umd.cjs"></script>
-    <script>
-        // Test the widget
-        WebChat.initialize({
-            elementId: "chat-test",
-            title: "Test Chat",
-            placeholder: "Test message...",
-            primaryColor: "#007bff"
-        });
-    </script>
-</body>
-</html>
-```
-
-### 📦 Publishing to npm
-
-#### 1. Prepare for Publishing
-```bash
-# 1. Update version in package.json
-npm version patch  # or minor, major
-
-# 2. Build the production version
-pnpm build
-
-# 3. Test the build
-pnpm preview
-```
-
-#### 2. Configure package.json for npm
-```json
-{
-  "name": "@yourorg/webchat-widget",
-  "version": "1.0.0",
-  "description": "Embeddable React TypeScript chatbot widget",
-  "main": "dist/webchat-bundle.min.umd.cjs",
-  "types": "dist/types/index.d.ts",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "keywords": ["chatbot", "widget", "react", "typescript", "embeddable"],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/yourorg/webchat-widget.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
-```
-
-#### 3. Publish to npm
-```bash
-# 1. Login to npm (if not already)
-npm login
-
-# 2. Publish the package
-npm publish
-
-# 3. Verify publication
-npm view @yourorg/webchat-widget
-```
-
-#### 4. Using Published Package
-```html
-<!-- From npm CDN -->
-<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
-
-<!-- Or install via npm -->
-npm install @yourorg/webchat-widget
-```
-
-### 🌐 Hosting on unpkg
-
-#### Automatic unpkg Hosting
-Once published to npm, your package is automatically available on unpkg:
-
-```html
-<!-- Latest version -->
-<script src="https://unpkg.com/@yourorg/webchat-widget"></script>
-
-<!-- Specific version -->
-<script src="https://unpkg.com/@yourorg/webchat-widget@1.0.0"></script>
-
-<!-- Direct file access -->
-<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
-```
-
-#### unpkg URLs Explained
-- `https://unpkg.com/package-name` - Latest version, main file
-- `https://unpkg.com/package-name@version` - Specific version
-- `https://unpkg.com/package-name/file-path` - Direct file access
-- `https://unpkg.com/package-name@version/file-path` - Version + file
-
-#### Real-world Integration Example
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <title>My Website with Chat</title>
-</head>
-<body>
-    <h1>Welcome to My Website</h1>
-    <p>Content goes here...</p>
-    
-    <!-- Chat widget integration -->
-    <div id="customer-chat"></div>
-    
-    <!-- Load from unpkg -->
-    <script src="https://unpkg.com/@yourorg/webchat-widget@latest"></script>
-    <script>
-        WebChat.initialize({
-            elementId: "customer-chat",
-            title: "Customer Support",
-            placeholder: "How can we help you?",
-            primaryColor: "#007bff",
-            apiEndpoint: "https://your-api.com/chat",
-            apiKey: "your-api-key"
-        });
-    </script>
-</body>
-</html>
-```
-
-### 🚀 Deployment Workflow Summary
-
-```bash
-# Complete workflow from development to deployment
-git checkout -b feature/new-feature
-# ... make changes ...
-git commit -m "Add new feature"
-git push origin feature/new-feature
-# ... create PR, review, merge ...
-
-# Deployment
-git checkout main
-git pull origin main
-npm version patch
-pnpm build
-npm publish
-git push --tags
-
-# Your widget is now available at:
-# https://unpkg.com/@yourorg/webchat-widget@latest
-```
-
-### 🛠️ Troubleshooting
-
-#### Common Issues
-
-**TypeScript Errors**
-```bash
-# Check TypeScript errors
-pnpm build  # Will show TS errors
-
-# Fix common issues:
-# 1. Missing types - add to src/types.ts
-# 2. Import errors - check file extensions (.tsx)
-# 3. Strict mode - follow TypeScript strict rules
-```
-
-**Build Issues**
-```bash
-# Clear cache and rebuild
-rm -rf node_modules dist
-pnpm install
-pnpm build
-```
-
-**CSS Conflicts**
-```typescript
-// Always use nbc- prefix in className
-className="nbc-bg-blue-500 nbc-text-white"
-```
-
-**unpkg Caching**
-```bash
-# Force cache refresh
-https://unpkg.com/@yourorg/webchat-widget?t=timestamp
-```
-
-## 🛠️ Development
-
-### Prerequisites
-- Node.js 18+ (for modern React and TypeScript)
-- pnpm 8+ (recommended package manager)
-
-### Setup
-```bash
-# Clone the repository
-git clone https://github.com/your-username/webchat-widget.git
-cd webchat-widget
-
-# Install dependencies with pnpm
-pnpm install
-
-# Start development server with hot reload
-pnpm dev
-```
-
-### Build for Production
-```bash
-pnpm build
-```
-
-This creates a single optimized file in the `dist/` directory:
-- `webchat-bundle.min.umd.cjs` (159KB / 50KB gzipped) - Complete TypeScript bundle with React, Tailwind CSS, and all functionality
-
-### Preview Production Build
-```bash
-pnpm preview
-```
-
-## 📁 Project Structure
-
-```
-webchat-widget/
-├── src/
-│   ├── components/           # React TypeScript components
-│   │   ├── ChatBot.tsx      # Main chatbot component
-│   │   ├── ChatButton.tsx   # Toggle button
-│   │   ├── ChatWindow.tsx   # Chat window container
-│   │   ├── ChatHeader.tsx   # Window header
-│   │   ├── MessageList.tsx  # Message list with scroll
-│   │   ├── Message.tsx      # Individual message
-│   │   ├── MessageInput.tsx # Input field
-│   │   └── TypingIndicator.tsx # Typing animation
-│   ├── types.ts             # TypeScript interfaces and types
-│   ├── index.tsx            # Main entry point (auto-injects CSS)
-│   ├── vite-env.d.ts        # Vite environment types
-│   └── styles.css           # Tailwind directives
-├── example.html             # Development example
-├── example/
-│   └── production.html      # Production example
-├── dist/                    # Built files
-│   └── webchat-bundle.min.umd.cjs # Single file TypeScript bundle
-├── tsconfig.json            # TypeScript configuration
-├── tsconfig.node.json       # Node TypeScript configuration
-├── tailwind.config.js       # Tailwind configuration
-├── postcss.config.js        # PostCSS configuration
-├── vite.config.js           # Vite configuration
-└── package.json             # pnpm + React + TypeScript dependencies
-```
-
-## 📄 License
-
+# 🔷 WebChat Widget
+
+A beautiful, embeddable chatbot widget built with **React**, **TypeScript**, **Vite**, **pnpm** and **Tailwind CSS** that can be easily integrated into any website with **just one file**.
+
+## ✨ Features
+
+- **📦 Single File Bundle**: Everything in one file - no separate CSS needed!
+- **🔷 TypeScript**: Full type safety with strict typing and excellent IntelliSense
+- **⚛️ React 18**: Component-based architecture for maintainability
+- **🎨 Tailwind CSS**: Utility-first styling with prefixed classes (`ncb-`)
+- **⚡ Vite**: Lightning-fast development and optimized builds
+- **📦 pnpm**: Efficient package management and faster installs
+- **🔧 Easy Integration**: Add to any website with just one script tag
+- **🎨 Modern Design**: Beautiful, responsive UI that works on all devices
+- **🛠️ Customizable**: Configure colors, text, and behavior to match your brand
+- **✨ Smooth Animations**: Typing indicators and smooth transitions
+- **📱 Mobile Responsive**: Optimized for mobile and desktop
+- **🔌 API Ready**: Built-in support for chat API integration
+- **🚫 Zero Conflicts**: Prefixed CSS classes prevent style conflicts
+- **🛡️ Type Safe**: Catch errors at compile time with TypeScript
+
+## 📦 Quick Start
+
+### 1. Add the widget to your website
+
+```html
+<div id="webchat-component"></div>
+
+<script src="https://your-cdn.com/webchat-bundle.min.umd.cjs"></script>
+<script>
+WebChat.initialize({
+    title: "Customer Support",
+    placeholder: "Ask us anything...",
+    primaryColor: "#667eea"
+});
+</script>
+```
+
+### 2. That's it! 🎉
+
+The chatbot button will appear in the bottom-right corner of your page. CSS is automatically injected!
+
+## ⚙️ Configuration Options
+
+```typescript
+interface WebChatConfig {
+  title?: string;                       // Chat window title
+  placeholder?: string;                 // Input placeholder text
+  primaryColor?: string;                // Primary theme color
+  apiKey?: string;                      // Your chatbot UID (required for API)
+  position?: 'bottom-right' | 'bottom-left'; // Widget position
+  initialMessage?: string;              // Custom initial bot message
+  closeButtonIcon?: 'default' | 'text' | 'custom'; // Close button type
+  closeButtonText?: string;             // Text for close button (when type is 'text')
+  closeButtonCustomIcon?: string;       // Custom icon SVG or URL (when type is 'custom')
+  marginBottom?: number;                // Distance from bottom edge in pixels (default: 16)
+  marginSide?: number;                  // Distance from left/right edge in pixels (default: 16)
+  mobile?: WebChatPositionConfig;       // Mobile-specific position settings
+  desktop?: WebChatPositionConfig;      // Desktop-specific position settings
+}
+
+interface WebChatPositionConfig {
+  position?: 'bottom-right' | 'bottom-left';
+  marginBottom?: number;
+  marginSide?: number;
+}
+
+WebChat.initialize({
+    title: "Chat Assistant",
+    placeholder: "Type your message...",
+    primaryColor: "#007bff",
+    apiKey: "your-chatbot-uid",        // Chatbot UID from admin panel
+    position: "bottom-right",
+    initialMessage: "¡Hola! 👋 Soy tu asistente virtual. ¿En qué puedo ayudarte hoy?",
+    closeButtonIcon: "default", // or "text" or "custom"
+    marginBottom: 20,           // Distance from bottom edge (default: 16px)
+    marginSide: 20,             // Distance from side edge (default: 16px)
+    // Device-specific overrides
+    mobile: {
+        position: "bottom-left",
+        marginBottom: 80,
+        marginSide: 15
+    },
+    desktop: {
+        position: "bottom-right", 
+        marginBottom: 30,
+        marginSide: 30
+    }
+});
+```
+
+## 🎨 Customization
+
+### Colors
+```javascript
+WebChat.initialize({
+    primaryColor: "#ff6b6b",  // Custom brand color
+    // ... other options
+});
+```
+
+### API Integration
+
+The WebChat widget automatically detects the environment and uses the appropriate API endpoints:
+
+- **Development** (localhost): `http://localhost:3001/api/webchat`
+- **Production** (any other domain): `https://next.notchatbot.com/api/webchat`
+
+```javascript
+WebChat.initialize({
+    apiKey: "your-chatbot-uid",    // Chatbot UID from your Next.js admin panel
+    // Endpoints are automatically configured based on environment
+    // No need to specify apiEndpoint manually
+});
+```
+
+#### Manual Endpoint Override (Advanced)
+If you need to override the automatic endpoint detection:
+
+```javascript
+// This is handled automatically, but you can check the environment:
+import { getChatEndpoint, getConversationEndpoint } from './src/config/endpoints';
+
+console.log('Chat endpoint:', getChatEndpoint());
+console.log('Conversation endpoint:', getConversationEndpoint());
+```
+
+### 💬 Initial Message Customization
+Customize the first message your users see when they open the chat:
+
+```javascript
+WebChat.initialize({
+    title: "MiTienda Support",
+    // Custom welcome message with your brand's personality
+    initialMessage: "¡Hola! 👋 Soy el asistente de MiTienda.\n\n¿Buscas algún producto específico? ¡Estoy aquí para ayudarte!\n\nPuedes preguntarme sobre:\n• Productos disponibles\n• Precios y ofertas\n• Envíos y devoluciones\n• Soporte técnico\n\n¿En qué puedo ayudarte hoy? 😊",
+    apiKey: "your-api-key"
+});
+```
+
+### ❌ Close Button Customization
+Customize the appearance of the close button in the chat header:
+
+#### Option 1: Default X Icon (SVG)
+```javascript
+WebChat.initialize({
+    closeButtonIcon: "default" // Standard X icon
+});
+```
+
+#### Option 2: Custom Text
+```javascript
+WebChat.initialize({
+    closeButtonIcon: "text",
+    closeButtonText: "CERRAR" // or "✕", "CLOSE", etc.
+});
+```
+
+#### Option 3: Custom SVG Icon
+```javascript
+WebChat.initialize({
+    closeButtonIcon: "custom",
+    closeButtonCustomIcon: '<svg viewBox="0 0 24 24" fill="currentColor"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/></svg>'
+});
+```
+
+#### Option 4: Custom Icon from URL
+```javascript
+WebChat.initialize({
+    closeButtonIcon: "custom",
+    closeButtonCustomIcon: "https://yoursite.com/icons/close-icon.svg"
+});
+```
+
+### 📐 Position and Margins Customization
+Control where the chat widget appears on the screen and how much space it has from the edges:
+
+#### Bottom Right Position (Default)
+```javascript
+WebChat.initialize({
+    position: "bottom-right",
+    marginBottom: 20,  // 20px from bottom edge
+    marginSide: 25,    // 25px from right edge
+    apiKey: "your-api-key"
+});
+```
+
+#### Bottom Left Position
+```javascript
+WebChat.initialize({
+    position: "bottom-left",
+    marginBottom: 30,  // 30px from bottom edge
+    marginSide: 20,    // 20px from left edge
+    apiKey: "your-api-key"
+});
+```
+
+#### Position Examples for Different Layouts
+
+**E-commerce Site (avoid cart button)**
+```javascript
+WebChat.initialize({
+    position: "bottom-left",
+    marginBottom: 20,
+    marginSide: 20,
+    apiKey: "your-api-key"
+});
+```
+
+**Corporate Website (professional look)**
+```javascript
+WebChat.initialize({
+    position: "bottom-right",
+    marginBottom: 40,   // More space from bottom
+    marginSide: 30,     // More space from side
+    apiKey: "your-api-key"
+});
+```
+
+**Mobile-First Design (more accessible)**
+```javascript
+WebChat.initialize({
+    position: "bottom-right",
+    marginBottom: 80,   // Avoid mobile navigation
+    marginSide: 15,     // Less space on mobile
+    apiKey: "your-api-key"
+});
+```
+
+### 💰 Cost Optimization
+The WebChat widget is optimized to minimize API costs:
+
+- **Lazy Loading**: Conversation history is only fetched when the chat is opened, not on page load
+- **Smart Caching**: Once loaded, conversation history is cached to avoid duplicate fetches
+- **Conditional Fetching**: Only fetches when a conversation actually exists
+
+This ensures users can visit your e-commerce site without triggering unnecessary API calls.
+
+### 📱💻 Device-Specific Configurations
+Configure different positions and margins for mobile and desktop devices:
+
+#### Complete Device-Specific Setup
+```javascript
+WebChat.initialize({
+    title: "Customer Support",
+    apiKey: "your-api-key",
+    
+    // Global fallback settings (used if device-specific not provided)
+    position: "bottom-right",
+    marginBottom: 20,
+    marginSide: 20,
+    
+    // Desktop-specific settings
+    desktop: {
+        position: "bottom-right",
+        marginBottom: 30,        // More space on desktop
+        marginSide: 40           // More space from edge
+    },
+    
+    // Mobile-specific settings  
+    mobile: {
+        position: "bottom-left", // Different position on mobile
+        marginBottom: 80,        // Avoid mobile navigation bars
+        marginSide: 15           // Less space on smaller screens
+    }
+});
+```
+
+#### E-commerce Site Example
+```javascript
+WebChat.initialize({
+    title: "Shopping Assistant",
+    apiKey: "your-api-key",
+    
+    // Desktop: bottom-right (standard)
+    desktop: {
+        position: "bottom-right",
+        marginBottom: 25,
+        marginSide: 25
+    },
+    
+    // Mobile: bottom-left (avoid cart/menu buttons)
+    mobile: {
+        position: "bottom-left",
+        marginBottom: 90,        // Clear mobile navigation
+        marginSide: 15
+    }
+});
+```
+
+#### Corporate Website Example
+```javascript
+WebChat.initialize({
+    title: "Business Support",
+    apiKey: "your-api-key",
+    
+    // Consistent position, different margins
+    position: "bottom-right",   // Global fallback
+    
+    desktop: {
+        marginBottom: 40,        // Professional spacing
+        marginSide: 50
+    },
+    
+    mobile: {
+        marginBottom: 70,        // Clear mobile UI elements  
+        marginSide: 20
+    }
+});
+```
+
+## 👨‍💻 Developer Guide
+
+### 🚀 Getting Started
+
+#### Prerequisites
+- **Node.js 18+** (for modern React and TypeScript)
+- **pnpm 8+** (recommended package manager - faster than npm/yarn)
+- **Git** (for version control)
+- **VS Code** (recommended IDE with TypeScript support)
+
+#### Initial Setup
+```bash
+# 1. Clone the repository
+git clone https://github.com/your-username/webchat-widget.git
+cd webchat-widget
+
+# 2. Install dependencies with pnpm (much faster than npm)
+pnpm install
+
+# 3. Start development server
+pnpm dev
+```
+
+The development server will start at `http://localhost:3000` and automatically open `example.html`.
+
+### 🔧 Development Workflow
+
+#### 1. **Understanding the Codebase Structure**
+```
+src/
+├── components/           # React TypeScript components
+│   ├── ChatBot.tsx      # Main container component
+│   ├── ChatButton.tsx   # Floating chat button
+│   ├── ChatWindow.tsx   # Chat window container
+│   ├── ChatHeader.tsx   # Window header with close button
+│   ├── MessageList.tsx  # Scrollable message list
+│   ├── Message.tsx      # Individual message bubble
+│   ├── MessageInput.tsx # Input field with send button
+│   └── TypingIndicator.tsx # Animated typing dots
+├── types.ts             # TypeScript interfaces and types
+├── index.tsx            # Main entry point (exports WebChat API)
+├── vite-env.d.ts        # Type declarations for Vite
+└── styles.css           # Tailwind CSS directives
+```
+
+#### 2. **Adding New Features**
+
+**Step 1: Update Types** (if needed)
+```typescript
+// src/types.ts
+export interface NewFeatureProps {
+  enabled: boolean;
+  config?: SomeConfig;
+}
+```
+
+**Step 2: Create/Modify Components**
+```typescript
+// src/components/NewFeature.tsx
+import React from 'react';
+import type { NewFeatureProps } from '../types';
+
+const NewFeature: React.FC<NewFeatureProps> = ({ enabled, config }) => {
+  // Component logic here
+  return (
+    <div className="nbc-new-feature">
+      {/* Use nbc- prefix for all CSS classes */}
+    </div>
+  );
+};
+
+export default NewFeature;
+```
+
+**Step 3: Add to Main Component**
+```typescript
+// src/components/ChatBot.tsx
+import NewFeature from './NewFeature';
+
+// Use the new component in ChatBot
+```
+
+#### 3. **Styling Guidelines**
+
+- **Always use `nbc-` prefix** for CSS classes to avoid conflicts
+- **Use Tailwind utilities** whenever possible
+- **Follow the existing pattern** for consistent styling
+
+```tsx
+// ✅ Good - uses nbc- prefix
+<div className="nbc-bg-blue-500 nbc-text-white nbc-p-4">
+
+// ❌ Bad - no prefix, will conflict with host site
+<div className="bg-blue-500 text-white p-4">
+```
+
+#### 4. **TypeScript Best Practices**
+
+- **Define interfaces** for all component props
+- **Use strict typing** for functions and variables
+- **Leverage IntelliSense** for better development experience
+
+```typescript
+// ✅ Good - strict typing
+const handleMessage = (message: string): void => {
+  // Function implementation
+};
+
+// ❌ Bad - no typing
+const handleMessage = (message) => {
+  // Function implementation
+};
+```
+
+### 🏗️ Building & Compilation
+
+#### Development Build
+```bash
+# Start development server with hot reload
+pnpm dev
+
+# Access at: http://localhost:3000
+# Changes are reflected immediately
+```
+
+#### Production Build
+```bash
+# Build for production (TypeScript compilation + bundling)
+pnpm build
+
+# Output: dist/webchat-bundle.min.umd.cjs (single file)
+# Size: ~159KB (50KB gzipped)
+```
+
+#### Build Process Explanation
+1. **TypeScript Compilation** (`tsc`) - Type checking and compilation
+2. **Vite Bundling** - Bundles React, CSS, and all dependencies
+3. **CSS Injection** - Inlines CSS into JavaScript for single-file output
+4. **Minification** - Optimizes and compresses the output
+
+### 🧪 Testing the Compiled Version
+
+#### Option 1: Preview Server
+```bash
+# Build and start preview server
+pnpm build
+pnpm preview
+
+# Access at: http://localhost:4173
+# Tests the actual production build
+```
+
+#### Option 2: Local Testing
+```bash
+# After building, test locally
+pnpm build
+
+# Open example/production.html in browser
+# Or serve with any static file server
+python3 -m http.server 8000
+# Then visit: http://localhost:8000/example/production.html
+```
+
+#### Option 3: Integration Testing
+Create a test HTML file:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Widget Test</title>
+</head>
+<body>
+    <h1>Testing WebChat Widget</h1>
+    <div id="chat-test"></div>
+    
+    <!-- Load your built widget -->
+    <script src="./dist/webchat-bundle.min.umd.cjs"></script>
+    <script>
+        // Test the widget
+        WebChat.initialize({
+            elementId: "chat-test",
+            title: "Test Chat",
+            placeholder: "Test message...",
+            primaryColor: "#007bff"
+        });
+    </script>
+</body>
+</html>
+```
+
+### 📦 Publishing to npm
+
+#### 1. Prepare for Publishing
+```bash
+# 1. Update version in package.json
+npm version patch  # or minor, major
+
+# 2. Build the production version
+pnpm build
+
+# 3. Test the build
+pnpm preview
+```
+
+#### 2. Configure package.json for npm
+```json
+{
+  "name": "@yourorg/webchat-widget",
+  "version": "1.0.0",
+  "description": "Embeddable React TypeScript chatbot widget",
+  "main": "dist/webchat-bundle.min.umd.cjs",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": ["chatbot", "widget", "react", "typescript", "embeddable"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourorg/webchat-widget.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+#### 3. Publish to npm
+```bash
+# 1. Login to npm (if not already)
+npm login
+
+# 2. Publish the package
+npm publish
+
+# 3. Verify publication
+npm view @yourorg/webchat-widget
+```
+
+#### 4. Using Published Package
+```html
+<!-- From npm CDN -->
+<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
+
+<!-- Or install via npm -->
+npm install @yourorg/webchat-widget
+```
+
+### 🌐 Hosting on unpkg
+
+#### Automatic unpkg Hosting
+Once published to npm, your package is automatically available on unpkg:
+
+```html
+<!-- Latest version -->
+<script src="https://unpkg.com/@yourorg/webchat-widget"></script>
+
+<!-- Specific version -->
+<script src="https://unpkg.com/@yourorg/webchat-widget@1.0.0"></script>
+
+<!-- Direct file access -->
+<script src="https://unpkg.com/@yourorg/webchat-widget/dist/webchat-bundle.min.umd.cjs"></script>
+```
+
+#### unpkg URLs Explained
+- `https://unpkg.com/package-name` - Latest version, main file
+- `https://unpkg.com/package-name@version` - Specific version
+- `https://unpkg.com/package-name/file-path` - Direct file access
+- `https://unpkg.com/package-name@version/file-path` - Version + file
+
+#### Real-world Integration Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>My Website with Chat</title>
+</head>
+<body>
+    <h1>Welcome to My Website</h1>
+    <p>Content goes here...</p>
+    
+    <!-- Chat widget integration -->
+    <div id="customer-chat"></div>
+    
+    <!-- Load from unpkg -->
+    <script src="https://unpkg.com/@yourorg/webchat-widget@latest"></script>
+    <script>
+        WebChat.initialize({
+            elementId: "customer-chat",
+            title: "Customer Support",
+            placeholder: "How can we help you?",
+            primaryColor: "#007bff",
+            apiEndpoint: "https://your-api.com/chat",
+            apiKey: "your-api-key"
+        });
+    </script>
+</body>
+</html>
+```
+
+### 🚀 Deployment Workflow Summary
+
+```bash
+# Complete workflow from development to deployment
+git checkout -b feature/new-feature
+# ... make changes ...
+git commit -m "Add new feature"
+git push origin feature/new-feature
+# ... create PR, review, merge ...
+
+# Deployment
+git checkout main
+git pull origin main
+npm version patch
+pnpm build
+npm publish
+git push --tags
+
+# Your widget is now available at:
+# https://unpkg.com/@yourorg/webchat-widget@latest
+```
+
+### 🛠️ Troubleshooting
+
+#### Common Issues
+
+**TypeScript Errors**
+```bash
+# Check TypeScript errors
+pnpm build  # Will show TS errors
+
+# Fix common issues:
+# 1. Missing types - add to src/types.ts
+# 2. Import errors - check file extensions (.tsx)
+# 3. Strict mode - follow TypeScript strict rules
+```
+
+**Build Issues**
+```bash
+# Clear cache and rebuild
+rm -rf node_modules dist
+pnpm install
+pnpm build
+```
+
+**CSS Conflicts**
+```typescript
+// Always use nbc- prefix in className
+className="nbc-bg-blue-500 nbc-text-white"
+```
+
+**unpkg Caching**
+```bash
+# Force cache refresh
+https://unpkg.com/@yourorg/webchat-widget?t=timestamp
+```
+
+## 🛠️ Development
+
+### Prerequisites
+- Node.js 18+ (for modern React and TypeScript)
+- pnpm 8+ (recommended package manager)
+
+### Setup
+```bash
+# Clone the repository
+git clone https://github.com/your-username/webchat-widget.git
+cd webchat-widget
+
+# Install dependencies with pnpm
+pnpm install
+
+# Start development server with hot reload
+pnpm dev
+```
+
+### Build for Production
+```bash
+pnpm build
+```
+
+This creates a single optimized file in the `dist/` directory:
+- `webchat-bundle.min.umd.cjs` (159KB / 50KB gzipped) - Complete TypeScript bundle with React, Tailwind CSS, and all functionality
+
+### Preview Production Build
+```bash
+pnpm preview
+```
+
+## 📁 Project Structure
+
+```
+webchat-widget/
+├── src/
+│   ├── components/           # React TypeScript components
+│   │   ├── ChatBot.tsx      # Main chatbot component
+│   │   ├── ChatButton.tsx   # Toggle button
+│   │   ├── ChatWindow.tsx   # Chat window container
+│   │   ├── ChatHeader.tsx   # Window header
+│   │   ├── MessageList.tsx  # Message list with scroll
+│   │   ├── Message.tsx      # Individual message
+│   │   ├── MessageInput.tsx # Input field
+│   │   └── TypingIndicator.tsx # Typing animation
+│   ├── types.ts             # TypeScript interfaces and types
+│   ├── index.tsx            # Main entry point (auto-injects CSS)
+│   ├── vite-env.d.ts        # Vite environment types
+│   └── styles.css           # Tailwind directives
+├── example.html             # Development example
+├── example/
+│   └── production.html      # Production example
+├── dist/                    # Built files
+│   └── webchat-bundle.min.umd.cjs # Single file TypeScript bundle
+├── tsconfig.json            # TypeScript configuration
+├── tsconfig.node.json       # Node TypeScript configuration
+├── tailwind.config.js       # Tailwind configuration
+├── postcss.config.js        # PostCSS configuration
+├── vite.config.js           # Vite configuration
+└── package.json             # pnpm + React + TypeScript dependencies
+```
+
+## 📄 License
+
 MIT License - see the [LICENSE](LICENSE) file for details.