@moveo-ai/web-client 0.108.0 → 0.109.0

package/README.md

@@ -14,7 +14,7 @@ Embeddable chat widget for integrating [Moveo.ai](https://moveo.ai) AI Agents in
 
 - Real-time chat with AI Agents
 - Customizable appearance and theming
-- Multi-language support (22 languages)
+- Multi-language support (26 locales)
 - File upload and media sharing
 - Mobile-responsive design
 - Secure iframe-based isolation
@@ -28,7 +28,7 @@ Embeddable chat widget for integrating [Moveo.ai](https://moveo.ai) AI Agents in
 - [Configuration](#configuration)
 - [TypeScript Support](#typescript-support)
 - [Browser Support](#browser-support)
-- [Local Development](#local-development)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Quick Start
@@ -58,12 +58,12 @@ npm install @moveo-ai/web-client
 ```
 
 ```typescript
-import MoveoAI from '@moveo-ai/web-client';
+import { init } from '@moveo-ai/web-client';
 
-MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
+init({ integrationId: 'YOUR_INTEGRATION_ID' });
 ```
 
-**Requirements:** Node.js 18+
+**Requirements:** Node.js 20+
 
 ## Usage
 
@@ -88,68 +88,168 @@ MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
 </html>
 ```
 
-### With Configuration Options
+### Programmatic Control
+
+`init` resolves to a `WidgetController` once the widget is ready:
 
 ```javascript
-MoveoAI.init({
-  integrationId: 'YOUR_INTEGRATION_ID',
-  context: {
-    user_id: 'user-123',
-    user_name: 'John Doe',
-    user_email: 'john@example.com',
-  },
-  language: 'en',
+MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' }).then((controller) => {
+  // Open the chat window
+  controller.openWindow();
+
+  // Close the chat window
+  controller.closeWindow();
+
+  // Send a message programmatically
+  controller.sendMessage({ text: 'Hello!' });
+
+  // Update the conversation context
+  controller.updateContext({ custom_field: 'custom_value' });
+
+  // Destroy the widget
+  controller.destroy();
 });
 ```
 
-### Programmatic Control
+### More examples
+
+<details>
+<summary>Check analytics events during development</summary>
+
+Log every event the widget tracks to verify your integration before wiring it
+into an analytics tool:
 
 ```javascript
-const controller = MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' });
+MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' }).then((controller) => {
+  controller.onAnalyticsEvent(({ timestamp, event, session_id, properties }) => {
+    console.debug('[moveo]', timestamp, event, session_id, properties);
+  });
+});
+```
 
-// Open the chat widget
-controller.open();
+</details>
 
-// Close the chat widget
-controller.close();
+<details>
+<summary>Identify a logged-in user and open the chat</summary>
 
-// Toggle the widget
-controller.toggle();
+```javascript
+MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' }).then((controller) => {
+  controller.updateContext({
+    user: { display_name: 'Jane Doe', email: 'jane@example.com' },
+    tags: ['premium'],
+    plan: 'business', // any other key becomes a context variable
+  });
+
+  document.querySelector('#help-button').addEventListener('click', () => {
+    controller.openWindow();
+  });
+});
+```
 
-// Send a message programmatically
-controller.sendMessage('Hello!');
+</details>
 
-// Update context
-controller.updateContext({ user_id: 'new-user-456' });
+<details>
+<summary>Mirror the unread indicator in your own UI</summary>
 
-// Destroy the widget
-controller.destroy();
+```javascript
+MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' }).then((controller) => {
+  const badge = document.querySelector('#chat-badge');
+
+  controller.onUnreadMessages(() => badge.classList.add('visible'));
+  controller.onNoUnreadMessages(() => badge.classList.remove('visible'));
+});
 ```
 
+</details>
+
 ## API Reference
 
 ### MoveoAI.init(config)
 
 Initializes the chat widget.
 
-| Parameter       | Type     | Required | Description                               |
-| --------------- | -------- | -------- | ----------------------------------------- |
-| `integrationId` | `string` | Yes      | Your Moveo.ai integration ID              |
-| `context`       | `object` | No       | Custom context variables for the AI Agent |
-| `language`      | `string` | No       | Widget language (ISO 639-1 code)          |
+| Parameter       | Type                    | Required | Description                                              |
+| --------------- | ----------------------- | -------- | -------------------------------------------------------- |
+| `integrationId` | `string`                | Yes      | Your Moveo.ai integration ID                             |
+| `host`          | `string`                | No       | Regional channels host, when it differs from the default |
+| `element`       | `HTMLElement \| string` | No       | Embed target, required for the `embed` widget position   |
+| `identityToken` | `string`                | No       | Signed token that verifies the user's identity on the session |
+| `voiceIntegrationId` | `string`           | No       | Voice pairing override for the in-widget call            |
+| `variant`       | `'default' \| 'nbg' \| 'alpha' \| 'fiserv'` | No | Visual variant                       |
+
+Any other key passes through as a widget-config override for the loaded integration.
 
-**Returns:** `WidgetController` - Controller instance for programmatic control
+**Returns:** `Promise<WidgetController>` - resolves once the widget is ready
 
 ### WidgetController Methods
 
-| Method                       | Description                      |
-| ---------------------------- | -------------------------------- |
-| `open()`                     | Opens the chat widget            |
-| `close()`                    | Closes the chat widget           |
-| `toggle()`                   | Toggles the widget open/closed   |
-| `sendMessage(text: string)`  | Sends a message to the agent     |
-| `updateContext(ctx: object)` | Updates the conversation context |
-| `destroy()`                  | Removes the widget from the page |
+| Method                          | Description                                            |
+| ------------------------------- | ------------------------------------------------------ |
+| `openWindow()`                  | Opens the chat window                                  |
+| `closeWindow()`                 | Closes the chat window                                 |
+| `closeConversation({ hide })`   | Ends the conversation; the widget hides unless `hide: false` |
+| `sendMessage({ text })`         | Sends a message to the agent                           |
+| `showTeaserMessage(message?)`   | Shows the teaser bubble                                |
+| `updateContext(ctx)`            | Updates the conversation context                       |
+| `setCSSVariables(vars)`         | Overrides widget CSS variables                         |
+| `setLocale(locale)`             | Switches the widget language                           |
+| `destroy()`                     | Removes the widget from the page                       |
+
+### WidgetController Events
+
+Register a callback per event. Every callback returns nothing and receives the
+payload listed below.
+
+| Method                        | Fires when                                     | Payload                                              |
+| ----------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
+| `onSessionCreated(cb)`        | A new session opens                            | `{ user_id, session_id, display_name }`              |
+| `onSessionReconnected(cb)`    | An existing session reconnects                 | `{ user_id, session_id, display_name }`              |
+| `onSessionClosed(cb)`         | The session closes                             | —                                                    |
+| `onConversationClosed(cb)`    | The user ends the conversation                 | —                                                    |
+| `onWebchatOpened(cb)`         | The user opens the widget                      | `{ isFull, is_mobile? }`                             |
+| `onWebchatClosed(cb)`         | The user closes the widget                     | `{ isFull }`                                         |
+| `onLinkClicked(cb)`           | The user clicks a link inside the chat         | `{ url }`                                            |
+| `onUnreadMessages(cb)`        | Unread messages exist while the widget is shut | —                                                    |
+| `onNoUnreadMessages(cb)`      | The unread indicator clears                    | —                                                    |
+| `onUserActivity(cb)`          | The visitor interacts with the widget          | —                                                    |
+| `onMemberLeave(cb)`           | An agent leaves the conversation               | —                                                    |
+| `onAnalyticsEvent(cb)`        | Any interaction event (see below)              | `{ timestamp, event, session_id?, properties }`      |
+
+`onAnalyticsEvent` receives every interaction the widget tracks, identified by
+the `event` field: `session_start`, `session_end`, `message_sent` (the user sent
+a message — never carries the text), `launcher_clicked`, `rating_submitted`, and
+the rest of the `AnalyticsEvent` enum in `src/hooks/useAnalytics.ts`.
+
+### Forward widget events into your analytics
+
+The widget never writes into your analytics tools. If you want chat activity in
+them, forward the events above from your own page — you control what is sent
+and where. With Quantum Metric, for example:
+
+```javascript
+MoveoAI.init({ integrationId: 'YOUR_INTEGRATION_ID' }).then((controller) => {
+  // Event ids must exist in your Quantum Metric configuration first:
+  // sendEvent() silently drops ids that are not defined for the page.
+  const QM_MOVEO_SESSION = 901; // example ids — define your own
+  const QM_MOVEO_MESSAGE = 902;
+
+  controller.onSessionCreated(({ session_id }) => {
+    // The Moveo session id becomes searchable on the QM session,
+    // joining every replay to its Moveo conversation.
+    window.QuantumMetricAPI?.sendEvent(QM_MOVEO_SESSION, 0, session_id);
+  });
+
+  controller.onAnalyticsEvent(({ event, session_id }) => {
+    if (event === 'message_sent') {
+      window.QuantumMetricAPI?.sendEvent(QM_MOVEO_MESSAGE, 0, session_id);
+    }
+  });
+});
+```
+
+The same pattern works for Tealium (`utag.link(...)`), Google Tag Manager
+(`dataLayer.push(...)`), or any library already on your page. Note that Quantum
+Metric rate-limits `sendEvent` to 50 calls per 200 ms.
 
 ## Configuration
 
@@ -178,7 +278,7 @@ MoveoAI.init({
 
 ### Supported Languages
 
-The widget supports 22 languages including: English, Spanish, French, German, Italian, Portuguese, Dutch, Greek, Arabic, Hebrew, and more.
+The widget supports 26 locales including: English, Spanish, French, German, Italian, Portuguese, Dutch, Greek, Arabic, Hebrew, and more.
 
 ```javascript
 MoveoAI.init({
@@ -189,44 +289,39 @@ MoveoAI.init({
 
 ## TypeScript Support
 
-Full TypeScript definitions are included:
+The package ships type declarations for the documented API surface
+(`web-client.d.ts`):
 
 ```typescript
-import MoveoAI, { WidgetController, WidgetConfig } from '@moveo-ai/web-client';
+import { init, UserConfig, WidgetController } from '@moveo-ai/web-client';
 
-const config: WidgetConfig = {
-  integrationId: 'YOUR_INTEGRATION_ID',
-  context: {
-    user_id: 'user-123',
-  },
-};
+const config: UserConfig = { integrationId: 'YOUR_INTEGRATION_ID' };
+const controller: WidgetController = await init(config);
 
-const controller: WidgetController = MoveoAI.init(config);
+controller.onSessionCreated(({ session_id }) => {
+  console.log('session', session_id);
+});
 ```
 
 ## Browser Support
 
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
-- Mobile browsers (iOS Safari, Android Chrome)
+The widget ships ES2020 and targets the browsers resolved from
+`.browserslistrc` (`defaults`, excluding IE 11, dead browsers, Opera Mini and
+KaiOS 2.5). In practice:
 
-## Local Development
-
-### HTTPS Setup
-
-The dev server runs on HTTPS. To avoid browser security warnings, generate locally-trusted certificates:
-
-```bash
-npm run setup:certs
-```
+- Chrome, Edge, Firefox, Safari: current and recent versions
+- iOS Safari and Android Chrome: current and recent versions
+- Opera Mini and KaiOS 2.5 are not supported; they cannot run the bundle
 
-This generates certificates in `.certs/` and attempts to install the CA into your system trust store (requires `sudo` on macOS/Linux). Restart your browser after running.
+Run `npx browserslist` to print the exact resolved list for the current
+`caniuse-lite` data.
 
-> **Firefox users:** Go to `about:preferences#privacy` → Certificates → View Certificates → Authorities → Import, and add `.certs/ca.crt`.
+## Contributing
 
-If the CA was not auto-installed, run the platform command printed by the script to add it manually.
+Development setup, commands, architecture notes and the full development
+documentation index live in
+[CONTRIBUTING.md](https://github.com/moveo-ai/web-client/blob/main/CONTRIBUTING.md)
+in the GitHub repository.
 
 ## Support