@accurix/centrinfo-widget 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,7 @@
 # @accurix/centrinfo-widget
 
 The embeddable **Centrinfo public chat widget** — a style-isolated chat client
-that drops onto any website. The current standalone CDN bundle is about 35 KB
-gzipped and can dock bottom-right or bottom-left.
+that drops onto any website and can dock bottom-right or bottom-left.
 
 Built with Preact inside a **Shadow DOM** web component, so it can't break the
 host site's CSS and the host's CSS can't break it. It talks to the Centrinfo
@@ -18,7 +17,7 @@ Zero-JS, via `data-*` on the script:
 
 ```html
 <script
-  src="https://cdn.accurix.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
+  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
   data-token="pub_8f3k…"
   defer
 ></script>
@@ -28,7 +27,7 @@ Or call `init` yourself:
 
 ```html
 <script
-  src="https://cdn.accurix.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
+  src="https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js"
   defer
 ></script>
 <script>
@@ -53,40 +52,144 @@ const widget = init({ token: 'pub_8f3k…' });
 | 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.                                                                                                                        |
 
+```ts
+init({
+  token: 'pub_8f3k...',
+  themeTokens: {
+    accent: '#176b45',
+    accentStrong: '#0f5134',
+    background: '#f8fafc',
+    surface: '#ffffff',
+    surfaceMuted: '#f1f5f9',
+    text: '#0f172a',
+    mutedText: '#64748b',
+    border: '#cbd5e1',
+    radius: '10px',
+    fontFamily: 'Inter, system-ui, sans-serif',
+  },
+});
+```
+
 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.
+from the snippet. Open widgets refresh that bootstrap data every 30 seconds, so
+saved dashboard settings reach visitors without a page reload.
+
+## Authenticated history
+
+For a logged-in customer, mint a short-lived identity token on the host
+backend and supply `getIdentityToken`. Keep the signing private key on the
+server, and use a stable external user ID for that customer.
+
+```ts
+const widget = init({
+  token: 'pub_8f3k...',
+  getIdentityToken: async () => {
+    const response = await fetch('/api/centrinfo/token', {
+      credentials: 'include',
+    });
+    if (!response.ok) throw new Error('Sign in is required.');
+    return response.json();
+  },
+});
+```
+
+Authenticated conversations are restored from Centrinfo's backend in a new
+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.
+
+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
+verified customer signs in again.
+
+When business data chat is enabled for a widget token, responses follow a
+visitor-safe presentation contract:
+
+- 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;
+- charts with more than two points include Zoom out, Reset, and Zoom in
+  controls with an exact visible-range announcement; the controls do not take
+  over browser zoom or page scrolling;
+- result tables and their row values are never rendered in the public widget;
+  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.
+
+For customer-specific analytics, create the signed context on the host
+application's server and pass only the resulting short-lived token as
+`analyticsContextToken`. Values such as `userId`, `businessId`, or `tenantId`
+must be checked by the published data model before they are applied.
+
+The signed token payload must contain issued-at and expiry times, an expiry no
+more than 15 minutes after issue, the widget-specific audience, and the
+governed context:
+
+```json
+{
+  "iat": 1784304000,
+  "exp": 1784304900,
+  "aud": "centrinfo-public-chat:<widget-token-id>",
+  "context": {
+    "userId": "customer-user-id",
+    "businessId": "customer-business-id"
+  }
+}
+```
+
+Replace `<widget-token-id>` with the backend-issued ID associated with the
+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-accent`, `data-theme`, `data-open`, `data-demo`,
+`data-config-refresh`.
 
 ## Environment
 
 The default API origin is baked from `VITE_API_BASE_URL` (see `.env.example`).
-Copy `.env.example` → `.env` (gitignored) to override locally; unset falls back
-to production (`https://api.accurixtech.com`). Local default is the local API
-(`http://api.accurixtech.com/`). A per-`init` `apiBaseUrl` always wins at runtime.
-Restart the dev server after editing `.env`.
+Copy `.env.example` → `.env` (gitignored) to override locally; when it is unset,
+the package uses the managed production service. A per-`init` `apiBaseUrl`
+overrides it for development, staging, dedicated-cloud, private-cloud, or
+on-premises environments. Restart the dev server after editing `.env`.
 
 ## Develop
 
 ```bash
-pnpm --filter @accurix/centrinfo-widget dev      # playground host site @ :3005 (demo mode)
+pnpm --filter @accurix/centrinfo-widget dev      # playground host site @ :3005
 pnpm --filter @accurix/centrinfo-widget build    # → dist/index.{mjs,cjs,d.ts} + dist/cdn/*
 pnpm --filter @accurix/centrinfo-widget check-types
 pnpm --filter @accurix/centrinfo-widget test-unit
 pnpm --filter @accurix/centrinfo-widget verify:release
 ```
 
+### Test analytics without a backend
+
+Open `http://localhost:3005/?demo`, open the widget, and use any of these starter prompts:
+
+- `Show a demo chart` — renders an expandable three-line order-status chart.
+- `Show a demo KPI` — renders an active-accounts KPI.
+- `Test the hidden table response` — confirms that the explanation appears but public table rows do not enter the DOM.
+
+Remove `?demo` to test the real public-chat API and the organization’s published analytics configuration.
+
 ## Release Artifacts
 
 `build:npm` uses tsdown to emit the npm package entrypoints:
@@ -103,7 +206,7 @@ pnpm --filter @accurix/centrinfo-widget verify:release
 Canonical v1 CDN URL:
 
 ```text
-https://cdn.accurix.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js
+https://cdn.accurixtech.com/centrinfo/js/sdk-centrinfo-widget-v1.0.0/centrinfo-widget.js
 ```
 
 ## Status