@mypatientspace/chatbot-widget 1.0.74 → 1.0.76

package/README.md

@@ -8,10 +8,14 @@ A standalone chatbot widget that third-party websites can embed via a single `<s
 
 - Self-contained React application bundled into a single JS file
 - Easy integration with any website
-- Floating button mode (default) or embedded mode
-- Customizable theming
+- Embedded mode (default) or floating button mode
+- Customizable theming with light, dark, and system color modes
 - Style isolation (won't conflict with host site CSS)
 - Native mobile support via WebView
+- Voice input support
+- Quick action buttons
+- Survey/questionnaire support
+- Content citations with overlay view
 
 ## Tech Stack
 
@@ -83,57 +87,6 @@ yarn build:demo         # Demo only
 yarn preview
 ```
 
-## Demo Widget
-
-An embeddable demo page with configuration panel and live preview. Useful for testing and showcasing the widget.
-
-### Via CDN
-
-```html
-<div id="chatbot-demo" style="height: 600px;"></div>
-<script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-demo.umd.js"></script>
-<script>
-  ChatbotWidgetDemo.init({
-    containerSelector: '#chatbot-demo',
-    showJsonEditor: true,
-    initialConfig: {
-      apiEndpoint: 'https://your-api.com/chat',
-      token: 'your-auth-token',
-      headerTitle: 'My Healthcare Bot',
-      theme: { colors: { primary: '#007bff' } }
-    },
-    onConfigChange: (config) => console.log('Config:', config)
-  });
-</script>
-```
-
-> **Note:** The "Use Mock API" toggle is only available in development mode (`yarn dev`). When embedding the demo in production, you must provide `apiEndpoint` and `token` in the `initialConfig`.
-
-### Demo API
-
-```javascript
-ChatbotWidgetDemo.init(config);    // Initialize demo
-ChatbotWidgetDemo.destroy();       // Remove demo
-ChatbotWidgetDemo.update(config);  // Update configuration
-```
-
-### Demo Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `containerSelector` | `string` | Required | CSS selector for container |
-| `showConfigPanel` | `boolean` | `true` | Show left config panel |
-| `showPreviewPanel` | `boolean` | `true` | Show right preview panel |
-| `showJsonEditor` | `boolean` | `true` | Show Form/JSON toggle |
-| `showDisplaySettings` | `boolean` | `true` | Show display settings section |
-| `showSessionSettings` | `boolean` | `true` | Show session settings section |
-| `showAppearanceSettings` | `boolean` | `true` | Show appearance section |
-| `showThemeSettings` | `boolean` | `true` | Show theme colors section |
-| `showContentSettings` | `boolean` | `true` | Show content settings section |
-| `showQuickActions` | `boolean` | `true` | Show quick actions section |
-| `initialConfig` | `Partial<WidgetConfig>` | `{}` | Pre-fill widget config (including `apiEndpoint` and `token`) |
-| `onConfigChange` | `(config) => void` | - | Called when config changes |
-
 ## Web Integration
 
 ### Minimal Setup
@@ -141,7 +94,7 @@ ChatbotWidgetDemo.update(config);  // Update configuration
 <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
 <script>
   ChatbotWidget.init({
-    apiEndpoint: 'https://your-api.com/chat',
+    apiEndpoint: 'https://your-api.com',
     token: 'your-auth-token'
   });
 </script>
@@ -152,60 +105,61 @@ ChatbotWidgetDemo.update(config);  // Update configuration
 <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
 <script>
   ChatbotWidget.init({
-    apiEndpoint: 'https://your-api.com/chat',
+    // API & Auth
+    apiEndpoint: 'https://your-api.com',
     token: 'your-auth-token',
+    userType: 'patient',             // 'patient' (default) or 'staff'
+    assistantId: 'your-assistant-id',
+
+    // Display mode
+    floatingMode: true,          // false = embedded (default), true = FAB button
+    position: 'bottom-left',     // FAB position (default: 'bottom-right')
+    hideExpandButton: true,      // Hide expand/minimize button from header
+    showCloseSlot: true,         // Empty placeholder for custom close button
+
+    // Content
     headerTitle: 'Health Support',
+    headerSubtitle: 'Online now',
     greeting: 'Hi! How can I help?',
+    placeholder: 'Ask me anything...',
     brandingText: 'Powered by MyCompany',
+    disclaimerText: 'AI can make mistakes. Verify important information.',
     headerIcon: '/logo.png',
-    fabIcon: '/avatar.png',
-    placeholder: 'Ask me anything...',
-    position: 'bottom-left',
-    colorMode: 'system',  // 'light', 'dark', or 'system' (auto-detect)
+    fabIcon: '/avatar.png',       // Only used in floating mode
     quickActions: ['I need help', 'Book appointment'],
+
+    // Appearance
+    colorMode: 'system',  // 'light', 'dark', or 'system' (auto-detect)
     theme: {
-      // All color properties are optional - only set what you want to change
       colors: {
-        // Main colors
         primary: '#ff6600',        // FAB button, links, main accent
         primaryDark: '#cc5200',    // Hover states
         secondary: '#2d3748',      // Header background
-        accent: '#4299e1',         // Secondary accent
-        accentLight: '#bee3f8',    // Light accent
-
-        // Status colors
-        success: '#48bb78',        // Success states
-        info: '#4299e1',           // Info states
-        error: '#f56565',          // Error states
-
-        // Background colors
+        headerText: '#ffffff',     // Header text color
         background: '#ffffff',     // Chat window background
         surface: '#f7fafc',        // Input/card backgrounds
-
-        // Text colors
         text: '#2d3748',           // Primary text
         textLight: '#718096',      // Secondary text, timestamps
-
-        // Message bubbles
         userBubble: '#ff6600',     // User message background
         userBubbleText: '#ffffff', // User message text
         botBubble: '#edf2f7',      // Bot message background
         botBubbleText: '#2d3748',  // Bot message text
-
-        // Borders
-        border: '#e2e8f0',         // Border color
-        borderLight: '#edf2f7',    // Light border
-
-        // Other
-        white: '#ffffff',          // White color
-        recording: '#f56565',      // Voice recording indicator
       },
-
-      // Typography and shape
       fontFamily: 'Inter, system-ui, sans-serif',
       borderRadius: '8px',
       shadow: '0 4px 12px rgba(0, 0, 0, 0.1)',
-    }
+    },
+
+    // Callbacks
+    onOpen: () => console.log('Chat opened'),
+    onClose: () => console.log('Chat closed'),
+    onMessageSent: (message) => console.log('Sent:', message),
+    onMessageReceived: (message) => console.log('Received:', message),
+    onQuickAction: (action) => console.log('Quick action:', action),
+    onStreamChunk: (chunk) => console.log('Chunk:', chunk),
+    onCitationClick: (citation) => console.log('Citation:', citation),
+    onNewChat: () => console.log('New chat started'),
+    onWidgetReady: (api) => console.log('Widget ready:', api),
   });
 </script>
 ```
@@ -215,21 +169,76 @@ ChatbotWidgetDemo.update(config);  // Update configuration
 import '@mypatientspace/chatbot-widget';
 
 ChatbotWidget.init({
-  apiEndpoint: 'https://your-api.com/chat'
+  apiEndpoint: 'https://your-api.com'
 });
 ```
 
+### Patient & Staff Integration
+
+The widget supports two user types with separate API routing. Each type uses different backend endpoints for chat, message history, and assistant lookup.
+
+#### Patient (Default)
+
+Patient mode is the default — no `userType` needed:
+
+```html
+<script>
+  ChatbotWidget.init({
+    apiEndpoint: 'https://your-api.com',
+    token: 'your-auth-token'
+  });
+</script>
+```
+
+API endpoints used:
+- `POST /api/patient/chat/stream` — Send messages
+- `GET /api/patient/chat/messages` — Load history
+- `GET /api/patient/assistant` — Get assistant config
+
+#### Staff
+
+Staff mode requires `userType: 'staff'` along with `contextPatientId` and `patientTypeId`:
+
+```html
+<script>
+  ChatbotWidget.init({
+    apiEndpoint: 'https://your-api.com',
+    token: 'your-auth-token',
+    userType: 'staff',
+    contextPatientId: 'patient-123',
+    patientTypeId: 'type-456'
+  });
+</script>
+```
+
+API endpoints used:
+- `POST /api/staff/chat/stream` — Send messages (includes `contextPatientId` in body)
+- `GET /api/staff/chat/messages` — Load history (requires `contextPatientId` query param)
+- `GET /api/staff/assistant/{patientTypeId}` — Get assistant config
+
+#### Required Fields by User Type
+
+| Field | Patient | Staff |
+|-------|---------|-------|
+| `apiEndpoint` | Required | Required |
+| `token` | Required | Required |
+| `userType` | Optional (default) | `'staff'` |
+| `contextPatientId` | Optional | Required |
+| `patientTypeId` | - | Required |
+
 ### API Methods
 ```javascript
-ChatbotWidget.open();    // Open chat window
-ChatbotWidget.close();   // Close chat window
-ChatbotWidget.toggle();  // Toggle open/close
-ChatbotWidget.destroy(); // Remove widget completely
+ChatbotWidget.open();         // Open chat window
+ChatbotWidget.close();        // Close chat window
+ChatbotWidget.toggle();       // Toggle open/close
+ChatbotWidget.startNewChat(); // Clear session and start new chat
+ChatbotWidget.update(config); // Update widget configuration
+ChatbotWidget.destroy();      // Remove widget completely
 ```
 
 ## Embedded Mode
 
-By default, the widget displays as a floating button that opens a popup. You can also embed the chat directly inside any container on your page.
+By default, the widget is embedded inside a container element. You can enable floating mode for a FAB button popup.
 
 ### Using containerSelector
 
@@ -241,7 +250,7 @@ Embed the chat inside an existing element:
 <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
 <script>
   ChatbotWidget.init({
-    apiEndpoint: 'https://your-api.com/chat',
+    apiEndpoint: 'https://your-api.com',
     containerSelector: '#my-chat'
   });
 </script>
@@ -254,7 +263,7 @@ Enable floating mode with FAB button (classic chatbot style):
 ```html
 <script>
   ChatbotWidget.init({
-    apiEndpoint: 'https://your-api.com/chat',
+    apiEndpoint: 'https://your-api.com',
     floatingMode: true
   });
 </script>
@@ -294,7 +303,7 @@ class ChatActivity : AppCompatActivity() {
                     <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
                     <script>
                         ChatbotWidget.init({
-                            apiEndpoint: 'https://your-api.com/chat'
+                            apiEndpoint: 'https://your-api.com'
                         });
                         ChatbotWidget.open();
                     </script>
@@ -338,7 +347,7 @@ class ChatViewController: UIViewController {
             <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
             <script>
                 ChatbotWidget.init({
-                    apiEndpoint: 'https://your-api.com/chat'
+                    apiEndpoint: 'https://your-api.com'
                 });
                 ChatbotWidget.open();
             </script>
@@ -351,6 +360,48 @@ class ChatViewController: UIViewController {
 }
 ```
 
+### iOS (Objective-C)
+```objc
+#import <UIKit/UIKit.h>
+#import <WebKit/WebKit.h>
+
+@interface ChatViewController : UIViewController
+@property (nonatomic, strong) WKWebView *webView;
+@end
+
+@implementation ChatViewController
+
+- (void)viewDidLoad {
+    [super viewDidLoad];
+
+    WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
+    config.preferences.javaScriptEnabled = YES;
+
+    self.webView = [[WKWebView alloc] initWithFrame:self.view.bounds configuration:config];
+    self.webView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
+    [self.view addSubview:self.webView];
+
+    NSString *html = @"<!DOCTYPE html>"
+        "<html>"
+        "<head>"
+        "<meta name='viewport' content='width=device-width, initial-scale=1, maximum-scale=1'>"
+        "<style>body { margin: 0; padding: 0; }</style>"
+        "</head>"
+        "<body>"
+        "<script src='https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js'></script>"
+        "<script>"
+        "ChatbotWidget.init({ apiEndpoint: 'https://your-api.com' });"
+        "ChatbotWidget.open();"
+        "</script>"
+        "</body>"
+        "</html>";
+
+    [self.webView loadHTMLString:html baseURL:[NSURL URLWithString:@"https://your-domain.com"]];
+}
+
+@end
+```
+
 ### React Native
 ```jsx
 import { WebView } from 'react-native-webview';
@@ -366,7 +417,7 @@ const ChatScreen = () => {
         <script src="https://unpkg.com/@mypatientspace/chatbot-widget@latest/dist/mypatientspace-widget.umd.js"></script>
         <script>
             ChatbotWidget.init({
-                apiEndpoint: 'https://your-api.com/chat'
+                apiEndpoint: 'https://your-api.com'
             });
             ChatbotWidget.open();
         </script>
@@ -388,27 +439,34 @@ const ChatScreen = () => {
 
 ### All Options
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `apiEndpoint` | `string` | No | Chat API endpoint URL (widget offline if not set) |
-| `token` | `string` | No | Auth token for API requests |
-| `sessionId` | `string` | No | Existing session ID to resume |
-| `assistantId` | `string` | No | Specific assistant ID to use |
-| `contextPatientId` | `string` | No | Patient context for the chat |
-| `loadHistory` | `boolean` | No | Load previous chat history (default: true) |
-| `colorMode` | `'light' \| 'dark' \| 'system'` | No | Color mode for the widget (default: 'light') |
-| `theme` | `ThemeConfig` | No | Custom theme (see Theme Configuration below) |
-| `position` | `'bottom-right' \| 'bottom-left'` | No | FAB button position |
-| `containerSelector` | `string` | No | CSS selector for embedded container |
-| `floatingMode` | `boolean` | No | Show FAB button and floating chat (default: false) |
-| `greeting` | `string` | No | Initial bot greeting message |
-| `placeholder` | `string` | No | Input field placeholder text |
-| `headerTitle` | `string` | No | Chat window header title |
-| `headerSubtitle` | `string` | No | Chat window header subtitle |
-| `headerIcon` | `string` | No | Header icon image URL |
-| `fabIcon` | `string` | No | FAB button image URL |
-| `brandingText` | `string` | No | Footer branding text |
-| `quickActions` | `string[]` | No | Predefined quick action buttons (displayed as labels and sent as messages) |
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiEndpoint` | `string` | - | Base API URL, e.g. `https://your-api.com` (widget offline if not set) |
+| `token` | `string` | - | Auth token for API requests |
+| `userType` | `'patient' \| 'staff'` | `'patient'` | User type for API endpoint routing |
+| `patientTypeId` | `string` | - | Patient type ID for staff assistant lookup (required when `userType` is `'staff'`) |
+| `sessionId` | `string` | - | Existing session ID to resume |
+| `assistantId` | `string` | - | Specific assistant ID to use |
+| `contextPatientId` | `string` | - | Patient context for the chat |
+| `loadHistory` | `boolean` | `true` | Load previous chat history |
+| `colorMode` | `'light' \| 'dark' \| 'system'` | `'light'` | Color mode for the widget |
+| `theme` | `ThemeConfig` | - | Custom theme colors, fonts, border radius, shadow |
+| `position` | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | FAB button position |
+| `containerSelector` | `string` | - | CSS selector for embedded container |
+| `floatingMode` | `boolean` | `false` | Show FAB button and floating chat |
+| `hideExpandButton` | `boolean` | `false` | Hide the expand/minimize button from header |
+| `showCloseSlot` | `boolean` | `false` | Show empty circle placeholder for custom close button |
+| `greeting` | `string` | From API | Initial bot greeting message |
+| `placeholder` | `string` | From API | Input field placeholder text |
+| `headerTitle` | `string` | From API | Chat window header title |
+| `headerSubtitle` | `string` | From API | Chat window header subtitle |
+| `headerIcon` | `string` | From API | Header icon image URL |
+| `fabIcon` | `string` | From API | FAB button image URL |
+| `brandingText` | `string` | From API | Footer branding text |
+| `disclaimerText` | `string` | From API | Disclaimer text below input area |
+| `quickActions` | `string[]` | From API | Predefined quick action buttons |
+
+> **Note:** Content fields (`greeting`, `headerTitle`, `placeholder`, `brandingText`, `headerIcon`, `fabIcon`, `quickActions`, `disclaimerText`) are loaded from the assistant's API configuration by default. Setting them in the widget config overrides the API values.
 
 ### Callbacks
 
@@ -420,35 +478,14 @@ const ChatScreen = () => {
 | `onMessageReceived` | `(message: Message)` | Called after bot response completes |
 | `onQuickAction` | `(action: string)` | Called when quick action is clicked |
 | `onStreamChunk` | `(chunk: string)` | Called for each streamed response chunk |
-
-### Message Interface
-
-```typescript
-interface Message {
-  id: string;
-  content: string;
-  sender: 'user' | 'bot';
-  timestamp: Date;
-  status: 'sending' | 'sent' | 'error';
-  audioUrl?: string;  // Base64 audio data URL for TTS playback
-}
-```
-
-### ThemeConfig Interface
-
-```typescript
-interface ThemeConfig {
-  colors?: Partial<ThemeColors>;  // Any subset of theme colors
-  fontFamily?: string;
-  borderRadius?: string;
-  shadow?: string;
-}
-```
+| `onCitationClick` | `(citation: Citation)` | Called when a content card is clicked |
+| `onNewChat` | `()` | Called when user starts a new chat |
+| `onWidgetReady` | `(api: WidgetApi)` | Called when widget is ready with API methods |
 
 ### Available Theme Colors
 
-| Color | Default | Description |
-|-------|---------|-------------|
+| Color | Light Default | Description |
+|-------|---------------|-------------|
 | `primary` | `#00c2d1` | FAB button, links, main accent |
 | `primaryDark` | `#017992` | Hover states |
 | `secondary` | `#3c4d73` | Header background |
@@ -467,25 +504,27 @@ interface ThemeConfig {
 | `border` | `#d1d5db` | Border color |
 | `borderLight` | `#e5e7eb` | Light border |
 | `error` | `#ef4444` | Error states |
+| `errorBackground` | `#fef2f2` | Error background |
 | `white` | `#ffffff` | White color |
 | `recording` | `#ef4444` | Voice recording indicator |
+| `headerText` | `#ffffff` | Header text and icon color |
+| `scrollbarThumb` | `rgba(60, 77, 115, 0.2)` | Scrollbar thumb color |
+| `scrollbarThumbHover` | `rgba(60, 77, 115, 0.3)` | Scrollbar thumb hover |
+
+### Default Fallback Values
 
-## Default Values
+Content fields are resolved with this priority: **Config > Assistant API > Component default**
 
-| Option | Default Value |
-|--------|---------------|
+| Field | Component Fallback |
+|-------|-------------------|
 | `headerTitle` | "AI Doctor" |
 | `greeting` | "Hello! Welcome to our healthcare support. How can I assist you today?" |
 | `placeholder` | "Type a message..." |
 | `brandingText` | "Developed by myPatientSpace" |
-| `headerIcon` | https://web.mypatientspace.com/img/logo-symbol.png |
-| `fabIcon` | https://web.mypatientspace.com/img/logo-symbol.png |
-| `position` | "bottom-right" |
-| `colorMode` | "light" |
-| `loadHistory` | true |
-| `containerSelector` | undefined (creates container in body) |
-| `floatingMode` | false (embedded is default) |
-| `quickActions` | Book Appointment, Hours, Contact, Location |
+| `disclaimerText` | "AI can make mistakes. Verify important information." |
+| `headerIcon` | MPS logo |
+| `fabIcon` | MPS logo |
+| `quickActions` | Empty (from API only) |
 
 ## License