@headwai/chat-bubble 1.0.2 → 2.0.0

package/README.dev.md

@@ -0,0 +1,604 @@
+# Chat Bubble Svelte
+
+The chat bubble is based on a Svelte integration for the [deep-chat](https://www.npmjs.com/package/deep-chat) component, providing an easy-to-use AI chat interface for your web applications.
+
+## Features
+
+- 🚀 Easy integration
+- 🔧 Configurable via environment variables
+- 💬 Support for various AI providers (LocalChat, OpenAI and more)
+- 📱 Responsive design
+- 🎨 Customizable UI components
+- 🔄 Real-time messaging with WebSocket support
+
+## Installation
+
+### Prerequisites
+
+- Node.js (version 16 or higher)
+- npm or yarn
+
+### Setup
+
+1. Clone this repository:
+```bash
+git clone <your-repo-url>
+cd chat-bubble
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Create a `.env` file in the root directory:
+```bash
+cp .env.example .env
+```
+
+4. Configure your environment variables (see [Configuration](#configuration) section)
+
+5. Start the development server:
+```bash
+npm run dev
+```
+
+## Configuration
+
+The deep-chat component can be configured using environment variables. Create a `.env` file in your project root with the following variables:
+
+### Required Environment Variables
+
+```env
+# API Configuration
+VITE_CHAT_BUBBLE_API_URL=https://your-api-endpoint.com/api/chat/completions
+VITE_CHAT_BUBBLE_API_KEY=your-api-key-here
+VITE_CHAT_BUBBLE_MODEL_ID=gpt-3.5-turbo
+
+# Connection Type (websocket, openAI, etc.)
+VITE_CHAT_BUBBLE_CONNECTION_TYPE=websocket
+```
+
+### Optional Environment Variables
+
+```env
+# Additional Headers
+VITE_CHAT_BUBBLE_CONTENT_TYPE=application/json
+
+# Request Configuration
+VITE_CHAT_BUBBLE_MAX_MESSAGES=0
+
+# UI Configuration
+VITE_CHAT_BUBBLE_PLACEHOLDER_TEXT=Welcome to the chat!
+VITE_CHAT_BUBBLE_DEMO_MODE=false
+VITE_CHAT_BUBBLE_FAVICON_PATH=/icons/favicon.svg
+```
+
+## Usage
+
+### Basic Integration
+
+To integrate the deep-chat component into your Svelte application:
+
+1. **Install the package** (if using as a standalone package):
+```bash
+npm install deep-chat
+```
+
+2. **Import and use in your Svelte component**:
+
+```svelte
+<script>
+  import { DeepChat } from "deep-chat";
+  
+  // Configuration using environment variables
+  const connect = {
+    type: import.meta.env.VITE_CHAT_BUBBLE_CONNECTION_TYPE || "websocket",
+    url: import.meta.env.VITE_CHAT_BUBBLE_API_URL,
+    headers: {
+      Authorization: `Bearer ${import.meta.env.VITE_CHAT_BUBBLE_API_KEY}`,
+      "Content-Type": import.meta.env.VITE_CHAT_BUBBLE_CONTENT_TYPE || "application/json"
+    },
+    additionalBodyProps: {
+      model: import.meta.env.VITE_CHAT_BUBBLE_MODEL_ID
+    }
+  };
+
+  const requestBodyLimits = {
+    maxMessages: parseInt(import.meta.env.VITE_CHAT_BUBBLE_MAX_MESSAGES) || 0
+  };
+
+  const textInputConfig = {
+    placeholder: {
+      text: import.meta.env.VITE_CHAT_BUBBLE_PLACEHOLDER_TEXT || "Type your message..."
+    }
+  };
+
+  // Message transformation for OpenAI compatibility
+  const requestInterceptor = (details) => {
+    if (details.body && details.body.messages) {
+      details.body.messages = details.body.messages.map(message => ({
+        role: message.role === "ai" ? "assistant" : message.role,
+        content: message.text || message.content
+      }));
+    }
+    return details;
+  };
+
+  const responseInterceptor = (response) => {
+    if (response.choices && response.choices[0] && response.choices[0].message) {
+      const message = response.choices[0].message;
+      return {
+        text: message.content,
+        role: message.role === "assistant" ? "ai" : message.role
+      };
+    }
+    
+    if (response.text || response.html || response.files) {
+      return response;
+    }
+    
+    if (typeof response === 'string') {
+      return { text: response };
+    }
+    
+    return response;
+  };
+</script>
+
+<deep-chat
+  demo={import.meta.env.VITE_CHAT_BUBBLE_DEMO_MODE === 'true'}
+  textInput={textInputConfig}
+  connect={connect}
+  requestBodyLimits={requestBodyLimits}
+  requestInterceptor={requestInterceptor}
+  responseInterceptor={responseInterceptor}
+/>
+```
+
+### Including Chat Bubble in Customer Websites
+
+#### Customizing Message Colors
+
+You can customize the background colors and text colors of user and AI messages, as well as the assistant icon color, in several ways:
+
+**Via environment variables (.env file):**
+```env
+# Message styling
+VITE_CHAT_BUBBLE_USER_MESSAGE_BG_COLOR=#007bff
+VITE_CHAT_BUBBLE_AI_MESSAGE_BG_COLOR=#f1f3f4
+VITE_CHAT_BUBBLE_USER_MESSAGE_TEXT_COLOR=#ffffff
+VITE_CHAT_BUBBLE_AI_MESSAGE_TEXT_COLOR=#000000
+
+# Assistant icon styling (creates a gradient automatically)
+VITE_CHAT_BUBBLE_FAVICON_BG_COLOR=#667eea
+```
+
+**Via runtime configuration (Script Embed - Option 2):**
+```html
+<script>
+    window.HEADWAI_CHAT_BUBBLE_CONFIG = {
+        apiUrl: 'https://customer-api.com/chat',
+        apiKey: 'customer-api-key',
+        userMessageBackgroundColor: '#4a90e2',  // Blue background for user messages
+        aiMessageBackgroundColor: '#e8f5e8',     // Light green background for AI messages
+        userMessageTextColor: '#ffffff',         // White text for user messages
+        aiMessageTextColor: '#2d5016',           // Dark green text for AI messages
+        faviconBackgroundColor: '#28a745'            // Green icon (gradient auto-generated)
+    };
+</script>
+```
+
+**Via props (NPM Package - Option 3):**
+```svelte
+<script>
+  import { ChatBubble } from '@headwai/chat-bubble';
+</script>
+
+<ChatBubble
+  apiUrl="https://api.example.com/chat"
+  apiKey="your-api-key"
+  userMessageBackgroundColor="#ff6b6b"   <!-- Red background for user messages -->
+  aiMessageBackgroundColor="#4ecdc4"     <!-- Teal background for AI messages -->
+  userMessageTextColor="#ffffff"         <!-- White text for user messages -->
+  aiMessageTextColor="#2c3e50"           <!-- Dark blue text for AI messages -->
+  faviconBackgroundColor="#e74c3c"           <!-- Red icon (gradient auto-generated) -->
+  {/* ...other props */}
+/>
+```
+
+**Via data attributes (Multiple chat bubbles):**
+```html
+<div data-chat-bubble 
+     data-chat-bubble-api-url="https://api1.com/chat"
+     data-chat-bubble-api-key="key1"
+     data-chat-bubble-user-message-background-color="#ff9500"
+     data-chat-bubble-ai-message-background-color="#00c851"
+     data-chat-bubble-user-message-text-color="#ffffff"
+     data-chat-bubble-ai-message-text-color="#004225"
+     data-chat-bubble-assistant-icon-color="#ff6f00"></div>
+```
+
+**Color Suggestions for Assistant Icon:**
+- **Corporate Blue:** `#0066cc` (creates blue gradient)
+- **Success Green:** `#28a745` (creates green gradient)  
+- **Warning Orange:** `#fd7e14` (creates orange gradient)
+- **Danger Red:** `#dc3545` (creates red gradient)
+- **Purple:** `#6f42c1` (creates purple gradient)
+- **Teal:** `#20c997` (creates teal gradient)
+
+The component automatically creates a beautiful linear gradient by making the second color 20% darker than your chosen base color.
+
+#### Option 1: Build and Deploy (Complete Application)
+
+This option bundles everything into a ready-to-use application including all interceptors and logic.
+
+**What gets bundled:**
+- ✅ Request/Response interceptors (OpenAI compatibility)
+- ✅ Environment variable configuration
+- ✅ All chat functionality
+- ✅ UI components and styling
+
+**Build and deployment steps:**
+1. **Configure environment variables** for production:
+```bash
+# Production .env file
+VITE_CHAT_BUBBLE_API_URL=https://api.customer-domain.com/chat
+VITE_CHAT_BUBBLE_API_KEY=prod-api-key
+VITE_CHAT_BUBBLE_MODEL_ID=gpt-4
+VITE_CHAT_BUBBLE_CONNECTION_TYPE=websocket
+VITE_CHAT_BUBBLE_DEMO_MODE=false
+```
+
+2. **Build the widget**:
+```bash
+npm run build:widget
+```
+
+3. **Deploy the `dist-widget` folder** to your web server or CDN.
+
+**Result:** Customers get a complete chat application - no additional coding required!
+
+#### Option 2: Embed Chat Bubble as Script (Plug-and-Play)
+
+After building the widget, you can include the chat component in any website as a complete widget.
+
+**Build steps:**
+1. **Build the widget**:
+```bash
+npm run build:widget
+```
+
+2. **Publish to NPM** (for jsDelivr access):
+```bash
+npm publish
+```
+
+**Customer integration:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Customer Website</title>
+    <!-- Configure via global variables -->
+    <script>
+        // Runtime configuration override
+        window.HEADWAI_CHAT_BUBBLE_CONFIG = {
+            apiUrl: 'https://customer-api.com/chat',
+            apiKey: 'customer-api-key',
+            modelId: 'gpt-4',
+            connectionType: 'websocket'
+        };
+    </script>
+</head>
+<body>
+    <!-- Your existing content -->
+    
+    <!-- Chat Bubble Integration - Auto-initializes! -->
+    <div id="chat-bubble-container"></div>
+    
+    <!-- Include from jsDelivr CDN -->
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css">
+    <script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
+</body>
+</html>
+```
+
+**Alternative: Multiple chat bubbles with data attributes:**
+```html
+<!-- Chat bubble with specific configuration -->
+<div data-chat-bubble 
+     data-chat-bubble-api-url="https://api1.com/chat"
+     data-chat-bubble-api-key="key1"></div>
+
+<!-- Another chat bubble with different config -->
+<div data-chat-bubble 
+     data-chat-bubble-api-url="https://api2.com/chat"
+     data-chat-bubble-api-key="key2"></div>
+
+<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
+```
+
+**What customers get:**
+- ✅ Complete chat interface
+- ✅ All interceptors included
+- ✅ OpenAI API compatibility built-in
+- ✅ Just needs API configuration
+- ✅ Auto-initialization on page load
+
+#### Option 3: NPM Package Integration (Developer Integration)
+
+For developers who need full control and customization.
+
+**Build and publish steps:**
+1. **Build the library**:
+```bash
+npm run build:lib
+```
+
+2. **Publish to NPM**:
+```bash
+npm publish
+```
+
+**Customer installation:**
+```bash
+# Install in customer's project
+npm install @headwai/chat-bubble
+```
+
+**For Svelte projects:**
+```svelte
+<!-- Customer's Svelte component -->
+<script>
+  import { ChatBubble } from '@headwai/chat-bubble';
+  
+  // Customers MUST implement these interceptors themselves
+  const requestInterceptor = (details) => {
+    if (details.body && details.body.messages) {
+      details.body.messages = details.body.messages.map(message => ({
+        role: message.role === "ai" ? "assistant" : message.role,
+        content: message.text || message.content
+      }));
+    }
+    return details;
+  };
+
+  const responseInterceptor = (response) => {
+    if (response.choices && response.choices[0] && response.choices[0].message) {
+      const message = response.choices[0].message;
+      return {
+        text: message.content,
+        role: message.role === "assistant" ? "ai" : message.role
+      };
+    }
+    return response;
+  };
+
+  const connect = {
+    type: "websocket",
+    url: process.env.API_URL,
+    headers: {
+      Authorization: `Bearer ${process.env.API_KEY}`,
+      "Content-Type": "application/json"
+    },
+    additionalBodyProps: {
+      model: process.env.MODEL_NAME
+    }
+  };
+</script>
+
+<ChatBubble
+  connect={connect}
+  requestInterceptor={requestInterceptor}
+  responseInterceptor={responseInterceptor}
+/>
+```
+
+**For vanilla JavaScript projects:**
+```html
+<script type="module">
+  import { createChatBubble } from 'https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist/index.js';
+  
+  // Initialize manually with custom configuration
+  const chatBubble = createChatBubble(
+    document.getElementById('chat-container'),
+    {
+      apiUrl: 'https://api.example.com/chat',
+      apiKey: 'your-api-key',
+      // ... other props
+    }
+  );
+</script>
+```
+
+**What customers need to implement:**
+- ❌ Request/Response interceptors (manual setup required)
+- ❌ Environment variable handling
+- ❌ API configuration logic
+- ✅ Deep chat component only
+
+## Deployment Options Comparison
+
+| Feature | Built App (Option 1) | Script Embed (Option 2) | NPM Package (Option 3) |
+|---------|----------------------|--------------------------|-------------------------|
+| **Build Command** | `npm run build:widget` | `npm run build:widget` + publish | `npm run build:lib` + publish |
+| **Interceptors Included** | ✅ Yes, automatically | ✅ Yes, automatically | ❌ No, manual setup required |
+| **Environment Variables** | ✅ Built-in support | ✅ Runtime configuration | ❌ Customer implements |
+| **OpenAI Compatibility** | ✅ Ready to use | ✅ Ready to use | ❌ Customer implements |
+| **Setup Complexity** | 🟢 Minimal (just config) | � Minimal (script tag) | �🟡 Moderate (coding required) |
+| **Customization** | 🟡 Limited to env vars | � Limited to config object | �🟢 Full control |
+| **File Size** | 🟡 Larger (complete app) | � Larger (complete app) | �🟢 Smaller (just component) |
+| **Use Case** | Self-hosted deployment | CDN/jsDelivr embedding | Developers, custom integration |
+| **Auto-initialization** | ✅ Yes | ✅ Yes | ❌ Manual setup |
+
+### Recommended Approach
+
+**For most customers:** Use **Option 2** (Script Embed via jsDelivr)
+- ✅ No coding required
+- ✅ All interceptors included
+- ✅ Easy CDN access via jsDelivr
+- ✅ Just configure via JavaScript object
+- ✅ Ready-to-deploy solution
+- ✅ Auto-initialization
+
+**For self-hosted deployments:** Use **Option 1** (Built Application)
+- ✅ Complete control over hosting
+- ✅ No external CDN dependencies
+- ✅ All interceptors included
+- ✅ Environment variable configuration
+
+**For developers who need customization:** Use **Option 3** (NPM Package)
+- ✅ Full control over interceptors
+- ✅ Custom API integrations
+- ✅ Smaller bundle size
+- ❌ More setup required
+
+## Publishing to NPM and jsDelivr Access
+
+### Publishing Steps
+
+1. **Build both library and widget**:
+```bash
+npm run build
+```
+
+2. **Login to NPM** (if not already logged in):
+```bash
+npm login
+```
+
+3. **Publish the package**:
+```bash
+npm publish
+```
+
+### jsDelivr CDN Access
+
+Once published to NPM, your package is automatically available on jsDelivr:
+
+**For Widget/Script Embed (Options 1 & 2):**
+```html
+<!-- Latest version -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.css">
+<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist-widget/chat-bubble.js"></script>
+
+<!-- Specific version -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.css">
+<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@1.0.0/dist-widget/chat-bubble.js"></script>
+```
+
+**For Library/Module Import (Option 3):**
+```html
+<!-- ES Module -->
+<script type="module">
+  import { ChatBubble, createChatBubble } from 'https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist/index.js';
+</script>
+
+<!-- UMD (Universal Module Definition) -->
+<script src="https://cdn.jsdelivr.net/npm/@headwai/chat-bubble@latest/dist/index.umd.js"></script>
+```
+
+### File Structure After Build
+
+```
+dist/                    # NPM package (Option 3)
+├── index.js            # ES module
+├── index.umd.js        # UMD module
+└── style.css           # Component styles
+
+dist-widget/            # Standalone widget (Options 1 & 2)
+├── widget.html         # Demo page
+├── chat-bubble.js      # Complete widget with auto-init
+├── chat-bubble.css     # Widget styles
+└── assets/             # Additional assets
+```
+
+## Environment Variables Reference
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `VITE_CHAT_BUBBLE_API_URL` | The API endpoint URL | - | ✅ |
+| `VITE_CHAT_BUBBLE_API_KEY` | API authentication key | - | ✅ |
+| `VITE_CHAT_BUBBLE_MODEL_ID` | AI model name to use | `gpt-3.5-turbo` | ✅ |
+| `VITE_CHAT_BUBBLE_CONNECTION_TYPE` | Connection type (websocket, openAI, etc.) | `websocket` | ✅ |
+| `VITE_CHAT_BUBBLE_CONTENT_TYPE` | HTTP Content-Type header | `application/json` | ❌ |
+| `VITE_CHAT_BUBBLE_MAX_MESSAGES` | Maximum messages in conversation history | `0` (unlimited) | ❌ |
+| `VITE_CHAT_BUBBLE_PLACEHOLDER_TEXT` | Chat input placeholder text | `Type your message...` | ❌ |
+| `VITE_CHAT_BUBBLE_DEMO_MODE` | Enable demo mode | `false` | ❌ |
+| `VITE_CHAT_BUBBLE_FAVICON_PATH` | Path to favicon/icon for chat toggle button | `/icons/favicon.svg` | ❌ |
+| `VITE_CHAT_BUBBLE_USER_MESSAGE_BG_COLOR` | Background color for user messages | `#007bff` | ❌ |
+| `VITE_CHAT_BUBBLE_AI_MESSAGE_BG_COLOR` | Background color for AI messages | `#f1f3f4` | ❌ |
+| `VITE_CHAT_BUBBLE_USER_MESSAGE_TEXT_COLOR` | Text color for user messages | `#000000` | ❌ |
+| `VITE_CHAT_BUBBLE_AI_MESSAGE_TEXT_COLOR` | Text color for AI messages | `#000000` | ❌ |
+| `VITE_CHAT_BUBBLE_FAVICON_BG_COLOR` | Base color for assistant icon gradient | `#667eea` | ❌ |
+
+## API Compatibility
+
+This component is designed to work with OpenAI-compatible APIs. The request and response interceptors handle the message format transformation between deep-chat and OpenAI formats.
+
+### Supported Message Flow
+
+1. **User Input** → Deep Chat format
+2. **Request Interceptor** → Transforms to OpenAI format
+3. **API Call** → Your configured endpoint
+4. **Response Interceptor** → Transforms back to Deep Chat format
+5. **Display** → Rendered in chat interface
+
+## Development
+
+### Scripts
+
+- `npm run dev` - Start development server
+- `npm run build` - Build both library and widget for production
+- `npm run build:lib` - Build NPM package (Option 3)
+- `npm run build:widget` - Build standalone widget (Options 1 & 2)
+- `npm run build:app` - Build demo application
+- `npm run preview` - Preview production build
+
+### Project Structure
+
+```
+chat-bubble/
+├── src/
+│   ├── App.svelte          # Main chat component
+│   ├── main.js             # Development entry point
+│   ├── lib.js              # NPM package entry point
+│   └── widget.js           # Widget/standalone entry point
+├── dist/                   # NPM package build output
+├── dist-widget/            # Widget build output
+├── package.json            # Dependencies and scripts
+├── vite.config.js          # Default Vite configuration
+├── vite.lib.config.js      # Library build configuration
+├── vite.widget.config.js   # Widget build configuration
+├── vite.app.config.js      # App build configuration
+├── svelte.config.js        # Svelte configuration
+├── index.html              # Development HTML
+├── widget.html             # Widget HTML template
+└── README.md               # This file
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **CORS Errors**: Ensure your API endpoint allows requests from your domain
+2. **Authentication Failures**: Verify your API key is correct and has proper permissions
+3. **WebSocket Connection Issues**: Check if your API supports WebSocket connections
+4. **Environment Variables Not Loading**: Ensure variables are prefixed with `VITE_CHAT_BUBBLE_`
+
+### Debug Mode
+
+Enable debug mode by setting:
+```env
+VITE_CHAT_BUBBLE_DEMO_MODE=true
+```
+
+This will enable demo features that can help test the component without a real API connection.
+
+## Support
+
+For issues and questions:
+- Create an issue in this repository
+- Check the [deep-chat documentation](https://deepchat.dev/)
+- Review the [API compatibility guide](https://deepchat.dev/docs/connect)