@schmitech/chatbot-widget 0.3.4 → 0.3.6

package/README.md

@@ -1,203 +1,265 @@
-# 💬 Chatbot Widget
+# How to Use the Chatbot Widget
 
-A simple, reusable chatbot widget seamlessly integrated into any website with minimal effort.
+This guide will help you integrate the chatbot widget into your website with minimal effort.
 
----
+## Quick Start
 
-## 🌟 Key Features
+### 1. Include the Widget Files
 
-- 🚀 **Quick Integration:** One-line JavaScript integration
-- 📱 **Responsive Design:** Mobile-friendly and adaptive layout
-- 🎨 **Customizable Appearance:** Easy theme adjustments
-- 📝 **Rich Text:** Supports Markdown and automatic link formatting
-- 🖱️ **User-Friendly UI:** Scrollable conversation view with "scroll to top" shortcut
-- 🧹 **Clear Conversation:** Reset chat with a single click
+Choose one of these methods to include the widget:
 
----
-
-## 🛠️ Installation
-
-### ✅ Prerequisites
-- Node.js 18+ and npm
-
-### 📦 Setup Instructions
-
-1. **Clone Repository**
-
-```bash
-git https://github.com/schmitech/orbit.git
-cd orbit/widget
-```
-
-2. **Install & Build API**
-
-```bash
-cd api
-npm install
-npm run build
-```
-
-3. **Install & Build Widget**
-
-```bash
-cd ../widget
-npm install
-npm run build
-npm run build:bundle
-```
-
-The build outputs are located in `widget/dist`:
-- `chatbot-widget.bundle.js` (JS + CSS combined, recommended)
-- `chatbot-widget.umd.js` (JS only, UMD)
-- `chatbot-widget.css` (CSS only)
-
----
-
-## 🎨 Customization
-
-See `demo.html` for customization examples:
-
-```bash
-python3 -m http.server 8080
-```
-
----
-
-## 🚢 Deployment
-
-1. Host `chatbot-widget.bundle.js` on a CDN or server.
-2. Update your HTML with the script reference.
-3. Ensure your chatbot API URL is accessible.
-
----
-
-## ⚙️ Widget API Reference
-
-### `initChatbotWidget(config)`
-Initializes widget configuration.
-
-| Parameter | Description | Required |
-|-----------|-------------|----------|
-| `apiUrl` | URL of chatbot API | ✅ Yes |
-| `apiKey` | API key for authentication | ✅ Yes |
-| `containerSelector` | CSS selector for widget container | ❌ No (Defaults to body) |
-
-Example configuration:
-```javascript
-initChatbotWidget({
-  apiUrl: 'https://your-api-url.com',
-  apiKey: 'your-api-key',
-  containerSelector: '#chat-container'
-});
+**Option 1 - All-in-one bundle (Recommended):**
+```html
+<script src="https://unpkg.com/@schmitech/chatbot-widget@latest/dist/chatbot-widget.bundle.js"></script>
 ```
 
----
-
-## 🧑‍💻 Development Commands
-
-```bash
-# Development server
-npm run dev
-
-# Code linting
-npm run lint
-
-# Production builds
-npm run build
-npm run build:bundle
-
-# Preview build
-npm run preview
+**Option 2 - Separate files:**
+```html
+<script src="https://unpkg.com/@schmitech/chatbot-widget@latest/dist/chatbot-widget.umd.js"></script>
+<link rel="stylesheet" href="https://unpkg.com/@schmitech/chatbot-widget@latest/dist/chatbot-widget.css">
 ```
 
----
-
-## 📤 Publish to npm
+### 2. Initialize the Widget
 
-**Build package:**
+Add this code to your website:
 
-```bash
-npm run build
-```
-
-**Test locally (optional):**
-
-```bash
-npm pack --dry-run
+```html
+<script>
+  window.addEventListener('load', function() {
+    window.initChatbotWidget({
+      apiUrl: 'https://your-api-url.com',  // Your chatbot API endpoint
+      apiKey: 'your-api-key',             // Your API key
+      sessionId: 'optional-session-id',    // Optional: Provide a custom session ID
+      widgetConfig: {
+        header: {
+          title: "Chat Assistant"
+        },
+        welcome: {
+          title: "Welcome!",
+          description: "How can I help you today?"
+        },
+        suggestedQuestions: [
+          {
+            text: "How can you help me?",
+            query: "What can you do?"
+          },
+          {
+            text: "Contact support",
+            query: "How do I contact support?"
+          }
+        ],
+        theme: {
+          primary: '#2C3E50',
+          secondary: '#f97316',
+          background: '#ffffff',
+          text: {
+            primary: '#1a1a1a',
+            secondary: '#666666',
+            inverse: '#ffffff'
+          },
+          input: {
+            background: '#f9fafb',
+            border: '#e5e7eb'
+          },
+          message: {
+            user: '#2C3E50',
+            assistant: '#ffffff',
+            userText: '#ffffff'
+          },
+          suggestedQuestions: {
+            background: '#fff7ed',
+            hoverBackground: '#ffedd5',
+            text: '#2C3E50'
+          },
+          iconColor: '#f97316'
+        },
+        icon: "message-square"
+      }
+    });
+  });
+</script>
 ```
 
-**Update version:**
+## Session Management
 
-```bash
-npm version [patch|minor|major]
-```
+The widget now includes improved session management:
 
-**Publish:**
+1. **Server-Provided Session ID**: If your server provides a session ID through `window.CHATBOT_SESSION_ID`, the widget will use it automatically.
 
-```bash
-npm publish --access public
-```
+2. **Custom Session ID**: You can provide your own session ID during initialization:
+   ```javascript
+   window.initChatbotWidget({
+     apiUrl: 'https://your-api-url.com',
+     apiKey: 'your-api-key',
+     sessionId: 'your-custom-session-id',
+     // ... other config
+   });
+   ```
 
-Package URL: [@schmitech/chatbot-widget](https://www.npmjs.com/package/@schmitech/chatbot-widget)
+3. **Automatic Session ID**: If no session ID is provided, the widget will:
+   - First check for an existing session ID in `sessionStorage`
+   - If none exists, generate a new UUID
+   - Store the session ID in both `sessionStorage` and `window.CHATBOT_SESSION_ID`
 
----
+## Advanced Usage
 
-## 🔗 Usage Examples
+### Custom Container
 
-### HTML Integration
+To place the widget in a specific container instead of the bottom-right corner:
 
-**Full bundle:**
 ```html
-<script src="https://unpkg.com/@schmitech/chatbot-widget@0.2.0/dist/chatbot-widget.bundle.js"></script>
+<div id="my-chat-container"></div>
+
+<script>
+  window.initChatbotWidget({
+    apiUrl: 'https://your-api-url.com',
+    apiKey: 'your-api-key',
+    containerSelector: '#my-chat-container',
+    widgetConfig: {
+      // ... your config here
+    }
+  });
+</script>
 ```
 
-**UMD + CSS separately:**
-```html
-<script src="https://unpkg.com/@schmitech/chatbot-widget@0.2.0"></script>
-<link rel="stylesheet" href="https://unpkg.com/@schmitech/chatbot-widget@0.2.0/dist/chatbot-widget.css">
-```
+### React/TypeScript Integration
 
-### JavaScript/TypeScript
+For React applications, you can integrate the widget like this:
 
-```javascript
-import { ChatWidget } from '@schmitech/chatbot-widget';
-import '@schmitech/chatbot-widget/bundle';
+```tsx
+import { useEffect } from 'react';
+
+function App() {
+  useEffect(() => {
+    if (typeof window !== 'undefined' && window.initChatbotWidget) {
+      window.initChatbotWidget({
+        apiUrl: process.env.REACT_APP_API_ENDPOINT,
+        apiKey: process.env.REACT_APP_API_KEY,
+        sessionId: process.env.REACT_APP_SESSION_ID, // Optional: Provide custom session ID
+        widgetConfig: {
+          // ... your config here
+        }
+      });
+    }
+  }, []);
+
+  return (
+    // Your app content
+  );
+}
 ```
 
-**React/TSX example:**
-```tsx
-useEffect(() => {
-  if (typeof window !== 'undefined' && window.initChatbotWidget) {
-    window.initChatbotWidget({
-      apiUrl: import.meta.env.VITE_API_ENDPOINT,
-      apiKey: import.meta.env.VITE_API_KEY,
-      widgetConfig: { /* widget configurations */ }
-    });
-  }
-}, []);
+## Configuration Options
+
+### Required Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiUrl` | string | Your chatbot API endpoint URL |
+| `apiKey` | string | Your API authentication key |
+
+### Optional Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `sessionId` | string | Unique identifier for the chat session. If not provided, one will be generated automatically |
+| `containerSelector` | string | CSS selector for custom container |
+| `widgetConfig` | object | Widget appearance and behavior settings |
+
+### Widget Configuration
+
+The `widgetConfig` object supports these properties:
+
+```typescript
+{
+  header: {
+    title: string;          // Widget header title
+  },
+  welcome: {
+    title: string;          // Welcome message title
+    description: string;    // Welcome message description
+  },
+  suggestedQuestions: [     // Array of suggested questions
+    {
+      text: string;        // Button text
+      query: string;       // Question to send
+    }
+  ],
+  theme: {                 // Theme customization
+    primary: string;       // Primary color
+    secondary: string;     // Secondary/accent color
+    background: string;    // Background color
+    text: {
+      primary: string;     // Primary text color
+      secondary: string;   // Secondary text color
+      inverse: string;     // Inverse text color
+    },
+    input: {
+      background: string;  // Input background
+      border: string;      // Input border color
+    },
+    message: {
+      user: string;        // User message bubble color
+      assistant: string;   // Assistant message bubble color
+      userText: string;    // User message text color
+    },
+    suggestedQuestions: {
+      background: string;      // Suggested questions background
+      hoverBackground: string; // Suggested questions hover background
+      text: string;           // Suggested questions text color
+    },
+    iconColor: string;     // Widget icon color
+  },
+  icon: string;            // Widget icon type
+}
 ```
 
----
+## Available Icons
 
-## ⚠️ Known Issues & Troubleshooting
+Choose from these built-in icons:
+- `heart` ❤️
+- `message-square` 💬
+- `message-circle` 🗨️
+- `help-circle` ❓
+- `info` ℹ️
+- `bot` 🤖
+- `sparkles` ✨
 
-### **Scrolling behavior:**
+## Customizing Height
 
-By default, widget height is `500px`. Customize with CSS:
+To adjust the widget height, add this CSS to your website:
 
 ```css
 :root {
-  --chat-container-height: 600px;
+  --chat-container-height: 600px; /* Default is 500px */
 }
 ```
 
-- Scrollbar auto-appears with long content
-- "Scroll to top" button shows after scrolling `200px`
-- Auto-scroll to bottom on new messages
-- Clear conversations easily from the header
+## Troubleshooting
+
+1. **Widget not appearing?**
+   - Check browser console for errors
+   - Verify API URL and key are correct
+   - Ensure all required scripts are loaded
+   - Check if the container element exists
+
+2. **Session ID issues?**
+   - Verify that `window.CHATBOT_SESSION_ID` is set if using server-provided sessions
+   - Check browser console for session-related errors
+   - Ensure `sessionStorage` is available and not blocked
+
+3. **API connection issues?**
+   - Verify your API endpoint is accessible
+   - Check API key is valid
+   - Ensure CORS is properly configured on your API
+   - Verify session ID is being sent with requests
 
----
+4. **Styling conflicts?**
+   - The widget uses scoped CSS to prevent conflicts
+   - If you see styling issues, check for conflicting CSS rules
 
-## 📃 License
+## Support
 
-Apache 2.0 License - See [LICENSE](LICENSE).
+For more help:
+- Visit our [GitHub repository](https://github.com/schmitech/orbit)
+- Open an issue on GitHub for bug reports