@accurix/centrinfo-widget 1.0.0 → 1.0.1

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
@@ -53,6 +52,7 @@ 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.               |
 | `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). |
 | `launcherIcon`                                                | string                        | chat glyph  | Image URL (e.g. the org's logo) shown in the launcher bubble.                                                                       |
@@ -60,33 +60,86 @@ 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.                                       |
 | `onOpen` / `onClose` / `onMessage` / `onAction` / `onHandoff` | function                      | —           | Event hooks.                                                                                                                        |
 
 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.
+
+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: