@accurix/centrinfo-widget 5.0.0 → 5.1.1

package/README.md

@@ -17,7 +17,7 @@ Zero-JS, via `data-*` on the script:
 
 ```html
 <script
-  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
+  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v5.0.0/centrinfo-widget.js"
   data-token="pub_8f3k…"
   defer
 ></script>
@@ -27,7 +27,7 @@ Or call `init` yourself:
 
 ```html
 <script
-  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
+  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v5.0.0/centrinfo-widget.js"
   defer
 ></script>
 <script>
@@ -45,26 +45,30 @@ pnpm add @accurix/centrinfo-widget
 import { init } from '@accurix/centrinfo-widget';
 const widget = init({ token: 'pub_8f3k…' });
 // widget.open() / .close() / .toggle() / .destroy()
+// widget.show() / .hide() (aliases) / .identify(user) / .update(user) / .clear()
+// widget.shutdown() (alias .logout()) on host-app logout
 ```
 
 ## Config
 
-| Option                                                        | Type                          | Default     | Notes                                                                                                                               |
-| ------------------------------------------------------------- | ----------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `token` **(required)**                                        | string                        | —           | The org's `pub_*` token. It _is_ the org identity.                                                                                  |
-| `analyticsContextToken`                                       | string                        | —           | Server-signed governed analytics context. It must expire within 15 minutes and be scoped to this public widget token.               |
-| `identityToken`                                               | string                        | —           | Short-lived customer identity JWT. Authenticated history is scoped to its verified external user ID.                                |
-| `getIdentityToken`                                            | function                      | —           | Returns a fresh customer identity JWT before authenticated requests. Prefer this for expiring tokens.                               |
-| `apiBaseUrl`                                                  | string                        | prod API    | Override for staging / self-host.                                                                                                   |
-| `accentColor`                                                 | string                        | brand green | Any CSS color — drives the launcher, header, user bubbles & send button (a darker shade for the gradient is derived automatically). |
-| `themeTokens`                                                 | object                        | —           | Enterprise theme tokens for chat surfaces: accent, background, surface, text, muted text, border, shadow, radius, and font family.  |
-| `launcherIcon`                                                | string                        | chat glyph  | Image URL (e.g. the org's logo) shown in the launcher bubble.                                                                       |
-| `theme`                                                       | `'light' \| 'dark' \| 'auto'` | `'auto'`    | `auto` follows the host's `prefers-color-scheme`; `light`/`dark` force it.                                                          |
-| `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.                                       |
-| `onOpen` / `onClose` / `onMessage` / `onAction` / `onHandoff` | function                      | —           | Event hooks.                                                                                                                        |
+| Option                                                        | Type                                | Default            | Notes                                                                                                                               |
+| ------------------------------------------------------------- | ----------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `token` **(required)**                                        | string                              | —                  | The org's `pub_*` token. It _is_ the org identity.                                                                                  |
+| `analyticsContextToken`                                       | string                              | —                  | Server-signed governed analytics context. It must expire within 15 minutes and be scoped to this public widget token.               |
+| `identityToken`                                               | string                              | —                  | Short-lived customer identity JWT. Authenticated history is scoped to its verified external user ID.                                |
+| `getIdentityToken`                                            | function                            | —                  | Returns a fresh customer identity JWT before authenticated requests. Prefer this for expiring tokens.                               |
+| `apiBaseUrl`                                                  | string                              | prod API           | Override for staging / self-host.                                                                                                   |
+| `accentColor`                                                 | string                              | brand green        | Any CSS color — drives the launcher, header, user bubbles & send button (a darker shade for the gradient is derived automatically). |
+| `themeTokens`                                                 | object                              | —                  | Enterprise theme tokens for chat surfaces: accent, background, surface, text, muted text, border, shadow, radius, and font family.  |
+| `launcherIcon`                                                | string                              | chat glyph         | Image URL (e.g. the org's logo) shown in the launcher bubble.                                                                       |
+| `theme`                                                       | `'light' \| 'dark' \| 'auto'`       | `'auto'`           | `auto` follows the host's `prefers-color-scheme`; `light`/`dark` force it.                                                          |
+| `locale` / `dir`                                              | string / `'ltr' \| 'rtl' \| 'auto'` | browser / `'auto'` | `dir` follows the locale (Arabic, Hebrew, Persian, Urdu... render right-to-left) unless forced.                                     |
+| `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.                                       |
+| `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.            |
 
 ```ts
 init({
@@ -84,6 +88,60 @@ init({
 });
 ```
 
+### Analytics labels
+
+Analytics answers (KPI, chart, table, details, explanation) read their wording
+from `labels.analytics`, also available per locale in `translations`. Any subset
+overrides the English defaults; `{count}`-style placeholders are kept.
+
+```ts
+init({
+  token: 'pub_8f3k...',
+  locale: 'fr',
+  labels: {
+    analytics: {
+      liveMetric: 'Indicateur',
+      resultDetails: 'Détails du résultat',
+      chartType: 'Type de graphique',
+      chooseChartType: 'Choisir le type de graphique',
+      download: 'Télécharger',
+      downloadData: 'Télécharger ces données',
+      expandChart: 'Agrandir le graphique',
+      expandTable: 'Agrandir le tableau',
+      restoreView: 'Revenir à l’assistant',
+      aboutResult: 'À propos de ce résultat',
+      notSet: 'Non défini',
+      noValue: 'Aucune valeur',
+      rowMany: '{count} lignes',
+      zoomIn: 'Zoom avant',
+      zoomOut: 'Zoom arrière',
+      zoomReset: 'Réinitialiser le zoom',
+      explanation: { feedbackPrompt: 'Cette réponse vous a-t-elle aidé ?', evidence: 'Preuve' },
+    },
+  },
+});
+```
+
+Keys: `resultDetails`, `liveMetric`, `currentValue`, `noMatchTitle`, `noMatchBody`,
+`chartType`, `chooseChartType`, `aggregate`, `aggregateTitle`, `aggregateCharge`,
+`chartFallback`, `chartLine`/`chartBar`/`chartStackedBar` (+ `...Hint`),
+`aggregationSum`/`Avg`/`Min`/`Max`/`Count`/`CountDistinct`, `download`,
+`downloadData`, `expandTable`, `expandChart`, `restoreView`, `aboutResult`,
+`aboutPeriod`/`aboutResults`/`aboutChecked`/`aboutTimezone`/`aboutSourceData`/`aboutFilters`,
+`rowOne`/`rowMany`, `filtersOne`/`filtersMany`/`filtersApplied`, `notSet`, `noValue`,
+`yes`, `no`, `chartValues`, `chartTitle`, `seriesLimited`, `summaryLatest`,
+`summaryNoTrend`, `summaryHighest`, `summaryNoComparison`, `zoomControls`,
+`zoomIn`, `zoomOut`, `zoomReset`, `zoomResetShort`, `zoomNone`, `zoomAllOne`,
+`zoomAllMany`, `zoomRange`, `inProgress`, `inProgressLegend`, `updatedAt`,
+`liveData`, `viewData`, `hideData`, `newContent`, `governedResult`, and
+`explanation` (the explanation panel's copy: `eyebrow`, `limits`, `evidence`,
+`feedbackPrompt`, `region`, `expand`, `collapse`, ...). Not yet translatable: the
+wording of the comparison-basis badge, the sentences the explanation builder
+derives from data, and the table toolbar.
+
+Numbers, currency, percent and dates are formatted with `locale`, the column
+metadata (`currencyCode`, `formatPattern`, `grain`) and the result `timezone`.
+
 Persona (agent name/avatar/greeting), the voice toggle, and which lead-gen
 actions appear all come from the token via `GET /public-chat/bootstrap` — not
 from the snippet. Open widgets refresh that bootstrap data every 30 seconds, so
@@ -113,6 +171,17 @@ browser or device after the identity token is verified. Anonymous history is
 stored only according to the widget's `persistence` option and cannot be
 loaded through authenticated history.
 
+If an authenticated analytics answer carries a cited insight or tile ID, pass
+`onOpenAnalyticsSource` to show **Open source Liveboard** next to an answer
+with one cited source, and **Open source** inside its citation. Resolve the
+target with `centrinfo.liveboards.resolveSource({ kind, id })` before opening
+it. That method returns only published boards assigned to the signed SDK
+application; the destination checks the viewer's row access again. Current
+general questions and anonymous answers do not show a source link. The
+callback also receives `appliedFilters`; a host can restore only those
+matching the board's published templates, using
+`centrinfo.liveboards.createViewToken(boardId, state)`.
+
 Call `widget.shutdown()` on host-app logout when the page may be shared. It
 removes the local transcript and resets the mounted widget to an anonymous
 session. Retained server history is not deleted and returns only when the same
@@ -121,6 +190,10 @@ verified customer signs in again.
 When business data chat is enabled for a widget token, responses follow a
 visitor-safe presentation contract:
 
+The chart's **Aggregate** menu asks a new governed follow-up for the chosen
+measure and calculation. The answer appears in the conversation and may incur
+normal query charges.
+
 - a normal knowledge, RAG, or web-search answer remains text;
 - a single live value may add a KPI and a comparison or timeline may add an
   expandable chart;
@@ -131,6 +204,9 @@ visitor-safe presentation contract:
   the written answer remains available instead;
 - charts include a visible text summary, contained tap/hover details, and an
   accessible expanded view that restores the conversation when closed.
+- when the result includes it, a collapsed **About this result** panel shows
+  the reporting period, row count, checked time, timezone, freshness, and
+  number of active filters without exposing internal model or query IDs.
 
 For customer-specific analytics, create the signed context on the host
 application's server and pass only the resulting short-lived token as
@@ -158,9 +234,42 @@ matching public widget token. Sign this payload only on the host application's
 server; never expose the signing secret or mint analytics context tokens in
 browser code.
 
-`data-*` attributes for the script install: `data-token`, `data-api-base`,
-`data-accent`, `data-theme`, `data-open`, `data-demo`,
-`data-config-refresh`.
+### Other options
+
+`persistence` (`local` | `session` | `none`), `attachments`, `sound`, `starters`,
+`labels`, `translations`, `agentName`, `agentAvatarUrl`, `gifApiKey`,
+`styleNonce`, `preview`, `user`, `alignment`, `horizontalPadding`,
+`verticalPadding`, `hideDefaultLauncher`, `customLauncherSelector`,
+`sessionDurationMinutes`, `proactiveMessage`, `proactiveDelaySeconds`,
+`proactiveOnPaths`, `csat`. See `src/types.ts` (`WidgetConfig`) for each.
+
+### Events
+
+- `onOpen()` / `onClose()` (aliases `onShow` / `onHide`)
+- `onMessage({ role: 'user' | 'assistant', content })`
+- `onAction(actionId: string)`
+- `onHandoff()` (a live person was offered)
+- `onUnreadChange(count)`
+- `onOpenAnalyticsSource({ kind, id, appliedFilters? })`
+
+### Script attributes
+
+`data-token`, `data-api-base`, `data-accent`, `data-agent-name`,
+`data-agent-avatar-url`, `data-launcher-icon`, `data-gif-api-key`,
+`data-theme`, `data-sound` (`false` disables), `data-open`, `data-demo`,
+`data-preview`, `data-alignment` (`left`), `data-horizontal-padding`,
+`data-vertical-padding`, `data-hide-launcher`, `data-custom-launcher-selector`,
+`data-style-nonce`, `data-session-duration`, `data-config-refresh`,
+`data-proactive-message`, `data-proactive-delay`, `data-csat` (`false`
+disables), `data-user` (JSON). Source: `src/cdn/data-attributes.ts`.
+
+### Identity tokens, rate limits, explanations
+
+`getIdentityToken` is called single-flight and its token is reused until 60
+seconds before `exp`; issue short-lived tokens with a readable `exp`. API `429`
+responses carry `Retry-After` and CORS headers. Analytics explanations that are
+still `pending` are polled via `GET /public-chat/analytics-explanations/:id`
+for up to about 45 seconds (`EXPLANATION_POLL_CAP_MS`) with a retry path.
 
 ## Environment
 
@@ -190,6 +299,41 @@ Open `http://localhost:3005/?demo`, open the widget, and use any of these starte
 
 Remove `?demo` to test the real public-chat API and the organization’s published analytics configuration.
 
+## What is stored locally
+
+With the default `persistence: 'local'` the widget keeps, per token and visitor
+(`centrinfo:session:*`, `centrinfo:visitor:*`, `centrinfo:chat:*`,
+`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.
+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.
+
+## Lazy files and CSP
+
+The CDN script is ~100 KB gzip. Two sibling files are fetched on demand,
+relative to the script's own URL, and are published next to it by `publish:cdn`:
+
+| File                         | Loaded when                           | ~gzip  |
+| ---------------------------- | ------------------------------------- | ------ |
+| `centrinfo-widget-charts.js` | the first chart is drawn (ECharts)    | 190 KB |
+| `centrinfo-widget-dev.js`    | only with `demo` or `preview` enabled | 5 KB   |
+
+The existing embed snippet is unchanged. Requirements: the files must be served
+from the same origin as the script with `Access-Control-Allow-Origin` (they load
+as ES modules), and a strict CSP needs that origin in `script-src` (already
+there for the script itself). `connect-src` is unchanged (your API base only).
+If the chart file is blocked, charts degrade to their text summary. The npm
+package splits the same code into dynamic-import chunks that your bundler
+handles automatically.
+
 ## Release Artifacts
 
 `build:npm` uses tsdown to emit the npm package entrypoints:
@@ -201,23 +345,31 @@ Remove `?demo` to test the real public-chat API and the organization’s publish
 `build:cdn` uses Vite to emit the browser script and then writes a manifest:
 
 - `dist/cdn/centrinfo-widget.js`
-- `dist/cdn/manifest.json`
+- `dist/cdn/centrinfo-widget-charts.js` and `dist/cdn/centrinfo-widget-dev.js` (lazy)
+- `dist/cdn/manifest.json` (sizes and SRI for all files)
 
-Canonical v1 CDN URL:
+Canonical CDN URL (version from `dist/cdn/manifest.json` `cdnPath`):
 
 ```text
-https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js
+https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v<version>/centrinfo-widget.js
 ```
 
 ### Publishing CDN assets
 
 `publish:cdn` uploads `dist/cdn/*` to R2 under a version-scoped path and then
-verifies three things: the object read back from R2, the origin response (with a
-cache-busting query string), and the canonical URL customers load. Objects go
+verifies the object read back from R2 and the canonical URL customers load.
+Overwrites also check the origin response with a cache-busting query string
+and purge the canonical URL before verifying it. Objects go
 out as `public, max-age=31536000, immutable`, so **prefer publishing a new
 version over overwriting a released one** — `--force` replaces bytes that
 browsers and the edge may hold for a year.
 
+If publishing reports that an object already exists with different content,
+add a patch Changeset with `pnpm changeset` and merge the generated version PR.
+Run the publishing workflow from that updated branch. Re-running an older
+failed workflow uses its original commit and version; it does not pick up the
+new release. Read the new CDN URL from the rebuilt `dist/cdn/manifest.json`.
+
 Required environment: `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_API_TOKEN`,
 `CLOUDFLARE_R2_BUCKET`, and `CENTRINFO_CDN_DRY_RUN=false` (the script dry-runs
 unless this is exactly `false`).
@@ -233,7 +385,7 @@ Optional environment:
 
 ## Status
 
-v1 in progress — chat, streaming (SSE), citations, suggested-reply chips,
-session memory, handoff CTA, lead-gen actions, voice input, theming.
-Backend `GET /public-chat/bootstrap` is pending (the only backend work);
-the client falls back to sensible defaults until it lands.
+Chat, streaming (SSE), citations, suggested-reply chips, session memory,
+handoff and live human takeover, lead-gen actions, voice, attachments,
+analytics answers and theming are implemented. Persona, voice and actions
+come from `GET /public-chat/bootstrap`.