@accurix/centrinfo-widget 5.1.1 → 5.2.0

package/README.md

@@ -9,6 +9,55 @@ public chat API (see [`.claude/PUBLIC_CHAT.md`](../../../../.claude/PUBLIC_CHAT.
 for the backend, and [`.claude/PUBLIC_WIDGET_LIBRARY.md`](../../../../.claude/PUBLIC_WIDGET_LIBRARY.md)
 for the design).
 
+## Simple customization
+
+Use `branding` and `composer` for common changes. The same options work in the
+floating widget, full-page chat and unified SDK chat mounts.
+
+```ts
+import { createWidget } from '@accurix/centrinfo-widget';
+
+const widget = createWidget({
+  token: 'pub_...',
+  branding: {
+    name: 'ShopCo Assistant',
+    logo: '/shopco-logo.png',
+    color: '#2563eb',
+  },
+  composer: {
+    placeholder: 'Ask about your ShopCo orders...',
+    attachments: false,
+    voice: false,
+    modelSelector: true,
+  },
+});
+```
+
+| Option                   | What it changes                                                       |
+| ------------------------ | --------------------------------------------------------------------- |
+| `branding.name`          | The displayed assistant name                                          |
+| `branding.logo`          | Assistant avatar and floating launcher image                          |
+| `branding.color`         | Main accent color                                                     |
+| `composer.placeholder`   | Message-box prompt                                                    |
+| `composer.attachments`   | Show or hide the attachment button; default `true`                    |
+| `composer.voice`         | Set `false` to hide microphone input; default allows configured voice |
+| `composer.modelSelector` | Show or hide the model picker; default `true`                         |
+
+Omit any option to keep the existing behavior. Voice still requires the
+application's voice configuration; the model picker requires permitted models.
+These display options do not change data access or conversation retention.
+In the floating widget, a separately configured voice assistant/call experience
+is independent of the composer's microphone button.
+
+For more control, use existing `themeTokens`, `labels`, `locale`, `dir`,
+`theme`, placement and launcher options. Explicit advanced options take priority:
+`agentName`, `agentAvatarUrl`, `launcherIcon`, `accentColor`, `attachments`,
+`showAnalyticsModelSelector` and `labels.composerPlaceholder` override their simple
+equivalents. `themeTokens.accent` also takes priority over `branding.color`.
+Full-page `fullPageLabels.composerPlaceholder` takes priority over the shared
+placeholder. The built-in component arrangement remains fixed; arbitrary
+message renderers, button ordering and custom CSS injection are not provided.
+
 ## Install
 
 ### Script tag (any site — WordPress / Webflow / plain HTML)
@@ -51,6 +100,16 @@ const widget = init({ token: 'pub_8f3k…' });
 
 ## Config
 
+Authenticated chat shows a **Data** dropdown by default when analytics models
+are available to the customer's application role. `Automatic` keeps automatic
+routing; selecting a model pins analytics turns and follow-ups to that model.
+Switching models opens a fresh conversation and retains the previous history.
+The backend validates the selected model on every turn.
+
+Set `showAnalyticsModelSelector: false` to hide it. Set `analyticsModelId` to
+provide an initial selection; a remembered customer choice takes precedence.
+These options work in both the floating widget and full-page chat SDK.
+
 | Option                                                        | Type                                | Default            | Notes                                                                                                                               |
 | ------------------------------------------------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
 | `token` **(required)**                                        | string                              | —                  | The org's `pub_*` token. It _is_ the org identity.                                                                                  |
@@ -66,10 +125,12 @@ const widget = init({ token: 'pub_8f3k…' });
 | `openByDefault`                                               | boolean                             | `false`            | Open the panel on load.                                                                                                             |
 | `zIndex`                                                      | number                              | very high          | Stacking against the host page.                                                                                                     |
 | `demo`                                                        | boolean                             | `false`            | Use the built-in mock transport — **no backend/token needed**.                                                                      |
-| `configRefreshSeconds`                                        | number                              | `30`               | While the panel is open, refresh token branding/actions from `bootstrap`; set `0` to disable.                                       |
+| `configRefreshSeconds`                                        | number                              | `300`              | While the panel is open, refresh token branding/actions from `bootstrap`; set `0` to disable.                                       |
 | `onOpen` / `onClose` / `onMessage` / `onAction` / `onHandoff` | function                            | —                  | Event hooks.                                                                                                                        |
 | `onOpenAnalyticsSource`                                       | function                            | —                  | Receives a cited insight or Liveboard tile from a signed analytics answer. The host must check access before opening it.            |
 
+The widget loads `bootstrap` once on mount. An open panel does not poll live events until the session has conversation activity, and it does not send presence until the visitor has sent a message. During ordinary AI chat it checks for staff events every 30 seconds; during a queued or active human handoff it checks about every 2.2 seconds. Presence renews every 20 seconds only for an open conversation in a visible tab. Closing the panel or hiding the tab stops these checks. `configRefreshSeconds` controls only the separate branding/action refresh.
+
 ```ts
 init({
   token: 'pub_8f3k...',
@@ -306,15 +367,29 @@ With the default `persistence: 'local'` the widget keeps, per token and visitor
 `centrinfo:history:*`):
 
 - the session id, the visitor's name/email/phone once given, and a history index;
-- a **lean transcript**: message text, ids, sources, suggested replies and
-  feedback, capped by the token's message cap and retention (30 days by default).
-
-Analytics results are **not** stored: rows, filters, explanations and chart
-data are dropped before writing, and a reloaded answer shows a short "ask again"
-note instead. Entries written by older versions are slimmed on the next load.
+- a transcript with message text, analytics answers, chart data, sources, and
+  feedback. Anonymous transcripts follow the token's message cap and retention
+  (30 days by default). Signed-in transcripts have no automatic local expiry;
+  the local cache remains bounded by the message cap and browser storage quota.
+
+Conversations bound to a verified signed customer identity do not auto-end
+after inactivity. Their server messages are retained without the anonymous
+TTL or message-cap deletion. A display-only `user` value does not establish
+verified identity: supply `identityToken` or `getIdentityToken`. Explicitly
+ending a conversation, removing it from history, and host logout still work.
+Authentication tokens still expire and must be refreshed normally. The AI
+receives only a bounded recent-message context, not the entire stored history.
+
+Analytics answers, including their chart data and explanation, are kept with
+the local transcript so reopening a conversation does not run the query again.
+Authenticated history also restores the retained answer from the backend on a
+new device. Ask the question again when you want current data. Older SDK
+versions may have stored only a result marker; those entries cannot be restored.
 Writes happen at most once per second (plus on tab hide), and a full or blocked
 storage only costs the local copy of the chat. Use `persistence: 'none'` to
-store nothing.
+keep no transcript on the device. Server retention follows the anonymous
+conversation settings for anonymous sessions; verified customer messages do
+not expire automatically. Previously deleted messages cannot be recovered.
 
 ## Lazy files and CSP