Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
commit b4753cef7e
81 changed files with 9255 additions and 0 deletions
--- a/docs/WIDGET_INTEGRATION.md
+++ b/docs/WIDGET_INTEGRATION.md
@@ -0,0 +1,158 @@
+# Widget Integration Guide
+
+## Quick Start
+
+### 1. Include the Widget Script
+
+Add the widget loader script to your HTML page:
+
+```html
+<script src="https://cdn.example.com/virtual-banker/widget.js"
+        data-tenant-id="your-tenant-id"
+        data-user-id="user-123"
+        data-auth-token="jwt-token"
+        data-api-url="https://api.example.com"
+        data-avatar-enabled="true"></script>
+<div id="virtual-banker-widget"></div>
+```
+
+### 2. Configuration Options
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-tenant-id` | Yes | Tenant identifier |
+| `data-user-id` | No | User identifier (for authenticated sessions) |
+| `data-auth-token` | No | JWT token for authentication |
+| `data-api-url` | No | API base URL (default: http://localhost:8081) |
+| `data-avatar-enabled` | No | Enable/disable avatar (default: true) |
+
+## Programmatic API
+
+### Methods
+
+```javascript
+// Open widget
+window.VirtualBankerWidgetAPI.open();
+
+// Close widget
+window.VirtualBankerWidgetAPI.close();
+
+// Minimize widget
+window.VirtualBankerWidgetAPI.minimize();
+
+// Set context (page/route information)
+window.VirtualBankerWidgetAPI.setContext({
+  route: '/account',
+  accountId: 'acc-123',
+  productId: 'prod-456'
+});
+
+// Update authentication token
+window.VirtualBankerWidgetAPI.setAuthToken('new-jwt-token');
+```
+
+## PostMessage Events
+
+Listen for widget events from the parent window:
+
+```javascript
+window.addEventListener('message', (event) => {
+  if (event.data.source === 'virtual-banker-widget') {
+    switch (event.data.type) {
+      case 'ready':
+        console.log('Widget is ready');
+        break;
+      
+      case 'session_started':
+        console.log('Session ID:', event.data.payload.sessionId);
+        break;
+      
+      case 'action_requested':
+        console.log('Action:', event.data.payload.action);
+        console.log('Params:', event.data.payload.params);
+        // Handle action (e.g., open ticket, schedule appointment)
+        break;
+      
+      case 'action_completed':
+        console.log('Action completed:', event.data.payload);
+        break;
+      
+      case 'handoff_to_human':
+        console.log('Handoff reason:', event.data.payload.reason);
+        // Show human agent interface
+        break;
+    }
+  }
+});
+```
+
+## Sending Messages to Widget
+
+Send commands to the widget from the parent window:
+
+```javascript
+const widget = document.getElementById('virtual-banker-widget');
+if (widget && widget.contentWindow) {
+  widget.contentWindow.postMessage({
+    type: 'open',
+    source: 'virtual-banker-host'
+  }, '*');
+}
+```
+
+Available commands:
+- `open` - Open the widget
+- `close` - Close the widget
+- `minimize` - Minimize the widget
+- `setContext` - Update context
+- `setAuthToken` - Update auth token
+
+## Styling
+
+The widget can be styled via CSS:
+
+```css
+#virtual-banker-widget {
+  position: fixed;
+  bottom: 20px;
+  right: 20px;
+  width: 400px;
+  height: 600px;
+  z-index: 9999;
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.2);
+}
+
+#virtual-banker-widget.minimized {
+  height: 60px;
+  width: 200px;
+}
+```
+
+## Theming
+
+Theme can be configured per tenant via the backend API. The widget will automatically apply the theme from the session configuration.
+
+## Accessibility
+
+The widget is built with accessibility in mind:
+- Full keyboard navigation
+- Screen reader support
+- ARIA labels
+- Captions always available
+- Reduced motion support (respects OS preference)
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Security
+
+- Content Security Policy (CSP) compatible
+- No direct secrets in browser
+- Ephemeral session tokens only
+- CORS configured for embedding
+