@makemore/agent-frontend 1.7.1 → 2.0.0

package/README.md

@@ -1,11 +1,10 @@
 # Agent Frontend
 
-A standalone, zero-dependency chat widget for AI agents. Embed conversational AI into any website with a single script tag.
+A lightweight chat widget for AI agents built with Preact. Embed conversational AI into any website with a single script tag.
 
 <p align="center">
-  <img src="https://img.shields.io/badge/vanilla-JavaScript-yellow" alt="Vanilla JS">
-  <img src="https://img.shields.io/badge/size-~15kb-green" alt="Size">
-  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero Dependencies">
+  <img src="https://img.shields.io/badge/Preact-673AB8?logo=preact&logoColor=white" alt="Preact">
+  <img src="https://img.shields.io/badge/size-~25kb-green" alt="Size">
   <img src="https://img.shields.io/badge/license-MIT-purple" alt="MIT License">
 </p>
 
@@ -13,10 +12,11 @@ A standalone, zero-dependency chat widget for AI agents. Embed conversational AI
 
 Most chat widgets are tightly coupled to specific frameworks or require complex build setups. Agent Frontend is different:
 
-- **Zero dependencies** - Pure vanilla JavaScript, no React/Vue/Angular required
+- **Lightweight** - Built with Preact (~3kb) for minimal bundle size
 - **CSS isolated** - Won't conflict with your existing styles (uses `all: initial` reset)
 - **SSE streaming** - Real-time token-by-token responses, not polling
 - **Production ready** - Session management, error handling, conversation persistence
+- **Component-based** - Clean architecture with hooks for state management
 
 ## Features
 
@@ -174,7 +174,126 @@ See `django-tts-example.py` for the complete Django backend implementation.
 | `showTTSButton` | boolean | `true` | Show TTS toggle button in header |
 | `showVoiceSettings` | boolean | `true` | Show voice settings button in header (works with proxy and direct API) |
 | `showExpandButton` | boolean | `true` | Show expand/minimize button in header |
+| `showConversationSidebar` | boolean | `true` | Show conversation history sidebar with hamburger menu |
 | `onEvent` | function | `null` | Callback for SSE events: `(eventType, payload) => void` |
+| `authStrategy` | string | `null` | Auth strategy: `'token'`, `'jwt'`, `'session'`, `'anonymous'`, `'none'` (auto-detected if null) |
+| `authToken` | string | `null` | Token value for `'token'` or `'jwt'` strategies |
+| `authHeader` | string | `null` | Custom header name (defaults based on strategy) |
+| `authTokenPrefix` | string | `null` | Custom token prefix (defaults based on strategy) |
+| `anonymousSessionEndpoint` | string | `null` | Endpoint for anonymous session (defaults to `apiPaths.anonymousSession`) |
+| `anonymousTokenKey` | string | `'chat_widget_anonymous_token'` | localStorage key for anonymous token |
+| `onAuthError` | function | `null` | Callback for auth errors: `(error) => void` |
+
+### Authentication
+
+The widget supports multiple authentication strategies with sensible defaults:
+
+#### Token Authentication (Django REST Framework)
+
+```javascript
+ChatWidget.init({
+  backendUrl: 'https://api.example.com',
+  agentKey: 'my-agent',
+  authStrategy: 'token',
+  authToken: 'abc123...',
+  // Sends: Authorization: Token abc123...
+});
+```
+
+#### JWT/Bearer Authentication
+
+```javascript
+ChatWidget.init({
+  backendUrl: 'https://api.example.com',
+  agentKey: 'my-agent',
+  authStrategy: 'jwt',
+  authToken: 'eyJ...',
+  // Sends: Authorization: Bearer eyJ...
+});
+```
+
+#### Session-Based Authentication (Cookies)
+
+```javascript
+ChatWidget.init({
+  backendUrl: 'https://api.example.com',
+  agentKey: 'my-agent',
+  authStrategy: 'session',
+  // Sends requests with credentials: 'include'
+  // No auth header, relies on session cookie
+});
+```
+
+#### Anonymous Session Tokens
+
+```javascript
+ChatWidget.init({
+  backendUrl: 'https://api.example.com',
+  agentKey: 'my-agent',
+  authStrategy: 'anonymous',
+  anonymousSessionEndpoint: '/api/accounts/anonymous-session/',
+  // On first request: fetches anonymous token from endpoint
+  // Persists token to localStorage
+  // Sends: X-Anonymous-Token: {token}
+});
+```
+
+#### No Authentication (Public Endpoints)
+
+```javascript
+ChatWidget.init({
+  backendUrl: 'https://api.example.com',
+  agentKey: 'my-agent',
+  authStrategy: 'none',
+  // No auth headers sent
+});
+```
+
+#### Custom Headers and Prefixes
+
+```javascript
+ChatWidget.init({
+  authStrategy: 'token',
+  authToken: 'mytoken123',
+  authHeader: 'X-API-Key',        // Custom header name
+  authTokenPrefix: '',             // No prefix (just the token)
+  // Sends: X-API-Key: mytoken123
+});
+```
+
+#### Dynamic Token Updates
+
+Update authentication after initialization (e.g., after user login):
+
+```javascript
+// After user logs in
+ChatWidget.setAuth({
+  strategy: 'jwt',
+  token: 'new-jwt-token-after-login'
+});
+
+// After user logs out
+ChatWidget.clearAuth();
+
+// Handle token refresh on auth errors
+ChatWidget.init({
+  authStrategy: 'jwt',
+  authToken: initialToken,
+  onAuthError: async (error) => {
+    if (error.status === 401) {
+      const newToken = await refreshToken();
+      ChatWidget.setAuth({ token: newToken });
+    }
+  }
+});
+```
+
+#### Auto-Detection
+
+If no `authStrategy` is specified, the widget auto-detects based on config:
+- If `authToken` is provided → uses `'token'` strategy
+- If `anonymousSessionEndpoint` or `apiPaths.anonymousSession` is configured → uses `'anonymous'` strategy
+- Otherwise → uses `'none'`
 
 ### Event Callback
 
@@ -456,6 +575,12 @@ ChatWidget.send('Hello, I need help!');
 // Clear the conversation
 ChatWidget.clearMessages();
 
+// Conversation sidebar controls
+ChatWidget.toggleSidebar();  // Open/close conversation sidebar
+ChatWidget.newConversation();  // Start a new conversation
+ChatWidget.switchConversation('conversation-id');  // Switch to a specific conversation
+ChatWidget.loadMoreMessages();  // Load older messages
+
 // Text-to-speech controls
 ChatWidget.toggleTTS();  // Toggle TTS on/off
 ChatWidget.stopSpeech(); // Stop current speech and clear queue
@@ -477,6 +602,10 @@ ChatWidget.setAutoRunMode('automatic');  // 'automatic', 'confirm', or 'manual'
 // Change auto-run delay (in milliseconds)
 ChatWidget.setAutoRunDelay(2000);
 
+// Authentication methods
+ChatWidget.setAuth({ strategy: 'jwt', token: 'new-token' }); // Update auth
+ChatWidget.clearAuth(); // Clear authentication
+
 // Remove the widget from the page
 ChatWidget.destroy();
 
@@ -606,9 +735,135 @@ agent-frontend/
 
 Requires: `EventSource` (SSE), `fetch`, `localStorage`
 
+## Multiple Instances
+
+You can create multiple independent chat widgets on the same page using `createInstance()`:
+
+### Basic Multi-Instance Setup
+
+```html
+<div id="chat-1" style="width: 400px; height: 500px;"></div>
+<div id="chat-2" style="width: 400px; height: 500px;"></div>
+
+<script>
+  // Create first widget
+  const widget1 = ChatWidget.createInstance({
+    containerId: 'chat-1',
+    backendUrl: 'https://your-api.com',
+    agentKey: 'support-agent',
+    title: 'Support Chat',
+    primaryColor: '#0066cc',
+    embedded: true,
+  });
+
+  // Create second widget
+  const widget2 = ChatWidget.createInstance({
+    containerId: 'chat-2',
+    backendUrl: 'https://your-api.com',
+    agentKey: 'sales-agent',
+    title: 'Sales Chat',
+    primaryColor: '#00cc66',
+    embedded: true,
+  });
+</script>
+```
+
+### Instance Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `containerId` | string | `null` | ID of the container element for embedded mode |
+| `embedded` | boolean | `false` | If true, renders inline in container instead of floating |
+| `metadata` | object | `{}` | Custom metadata to send with each request |
+
+### Instance Methods
+
+Each instance returned by `createInstance()` has its own methods:
+
+```javascript
+const widget = ChatWidget.createInstance({ ... });
+
+// Control the widget
+widget.open();
+widget.close();
+widget.send('Hello!');
+widget.clearMessages();
+
+// TTS controls
+widget.toggleTTS();
+widget.stopSpeech();
+
+// Authentication
+widget.setAuth({ strategy: 'jwt', token: 'new-token' });
+widget.clearAuth();
+
+// Get state/config
+const state = widget.getState();
+const config = widget.getConfig();
+
+// Destroy the widget
+widget.destroy();
+```
+
+### Managing Multiple Instances
+
+```javascript
+// Get a specific instance by ID
+const widget = ChatWidget.getInstance('cw-1');
+
+// Get all instances
+const allWidgets = ChatWidget.getAllInstances();
+
+// Destroy all instances
+ChatWidget.getAllInstances().forEach(w => w.destroy());
+```
+
+### Embedded vs Floating Mode
+
+**Embedded Mode** (`embedded: true`):
+- Widget renders inside the specified container
+- No floating button or close button
+- Widget is always visible
+- Perfect for split-pane layouts, dashboards, or dedicated chat pages
+
+**Floating Mode** (`embedded: false`, default):
+- Widget appears as a floating button in the corner
+- Clicking opens the chat panel
+- Has close and expand buttons
+- Traditional chat widget behavior
+
+### Storage Isolation
+
+Each embedded instance uses isolated localStorage keys based on `containerId`:
+- `chat_widget_conversation_id_chat-1` for widget in `#chat-1`
+- `chat_widget_conversation_id_chat-2` for widget in `#chat-2`
+
+This ensures conversations don't get mixed up between instances.
+
 ## Version History
 
-### v1.4.0 (Latest)
+### v2.0.0 (Latest)
+- 🔄 **Preact Rewrite**: Complete rewrite using Preact for better maintainability
+- 🧩 **Component Architecture**: Modular components (ChatWidget, Header, InputForm, Message, MessageList, Sidebar)
+- 🪝 **React-style Hooks**: useChat and useModels hooks for state management
+- 🎛️ **Model Selector**: Built-in model selection dropdown
+- 📦 **Smaller Bundle**: Optimized build with esbuild
+- 🔧 **Better Developer Experience**: Watch mode, source maps, cleaner code structure
+
+### v1.10.1
+- 📚 **Conversation Sidebar**: Browse and switch between past conversations via hamburger menu
+- 📜 **Message Pagination**: Load older messages with "load more" functionality
+- 🔐 **CSRF Support**: Automatic CSRF token handling for Django session auth
+- ➕ **New Conversation**: Start fresh conversations from the sidebar
+- 🔄 **Auto-restore**: Automatically loads messages when returning to a conversation
+
+### v1.5.0
+- 🔀 **Multiple Instances**: Create multiple independent chat widgets on the same page
+- 📦 **Embedded Mode**: Render widgets inline in containers for dashboards and split-pane layouts
+- 🔒 **Storage Isolation**: Each instance has isolated localStorage for conversations
+- 🎯 **Instance API**: Full control over individual widget instances
+
+### v1.4.0
 - ✨ **Text-to-Speech**: ElevenLabs integration with secure Django proxy support
 - 🔊 Automatic speech for assistant and simulated user messages
 - 🎛️ Smart speech queuing to prevent overlap
@@ -638,4 +893,4 @@ Requires: `EventSource` (SSE), `fetch`, `localStorage`
 
 ## License
 
-MIT © 2024
+MIT © 2025