@burdenoff/website-sdk 2026.1101.4 → 2026.1102.2

package/README.md

@@ -298,8 +298,9 @@ publishes audio, video or data, and it sends the avatar nothing to say.
       live: {
         site: 'healthybowl',
         load: () => import('@burdenoff/website-sdk/avatar-live'),
-        turnstileSiteKey: TURNSTILE_SITE_KEY,
         manifestVersion: 'hb-en-1', // the version of `suggestedQuestions`
+        // Optional: used only where the server checks for bots (see "The bot check is the server's setting").
+        turnstileSiteKey: TURNSTILE_SITE_KEY,
       },
     }}
   />
@@ -339,7 +340,24 @@ publishes audio, video or data, and it sends the avatar nothing to say.
 - **Needs the panel under an `ExploreChatProvider`.** The live avatar reads the
   provider's conversation. Without a provider, on a shared (read-only)
   conversation, in a locale whose strings have not been reviewed yet (English
-  only, for now), or with an incomplete `live`, the Avatar view stays as it was.
+  only, for now), or with an incomplete `live` (no `site`, `load` or
+  `manifestVersion`, or a `turnstileSiteKey` or `allowTestSiteKey` of the wrong
+  shape), the Avatar view stays as it was.
+- **The bot check is the server's setting (web API contract v1.2, additive).**
+  The availability answer says whether the server checks for bots when a
+  session is created: `"botCheck": {"mode": "off"}` or
+  `{"mode": "turnstile"}`. With `off`, Start loads the room module and creates
+  the session, and nothing else: no Cloudflare script, no widget, no WebCrypto
+  needed and no `x-web-avatar-bot-token` header; the server's own guards and
+  caps decide. With `turnstile`, Start runs the Cloudflare Turnstile check with
+  the page's own `turnstileSiteKey`, as before; without a key the page may use
+  (none, or one of Cloudflare's test keys where `allowTestSiteKey` is `false`)
+  the Avatar view stays as it was. A server older than v1.2 sends no `botCheck`
+  and always checks, so it is read as `turnstile`. Any other `botCheck` (an
+  unknown mode, another field, another shape) leaves the view as it was. So
+  turning the bot check on or off is a server config change: a site needs no
+  new build for it, as long as its build carries a site key for `turnstile` and
+  its CSP allows Cloudflare (below).
 - **One answer: the first, to a suggested question.** The avatar service
   accepts a conversation only when it holds exactly two messages: the first user
   message (a suggested question) and the first assistant answer, completed. The
@@ -350,14 +368,23 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   asked again without Retry), it asks the visitor to start a new chat and choose
   a suggested question. Whether the first question really is one of the
   suggested ones is the service's to judge (`not_eligible`).
+- **A fresh answer only.** The service also refuses an answer more than fifteen
+  minutes old (from the answer's `createdAt`): a conversation restored from the
+  browser's history, say. The view stops offering an answer fourteen minutes
+  after its `createdAt` (a minute's margin; a missing or unreadable time counts
+  as too old), also while the visitor is on the consent card: one timer moves
+  the card to the start-over step at that moment. The start-over step and the
+  `not_eligible` refusal both have a **New chat** button, which is the chat's
+  own New chat (the shared conversation's `reset`) followed by the Chat tab; no
+  host prop is needed for it.
 - **What the visitor sees.** Opening the Avatar view asks the gateway (the
   origin of your configured `gatewayUrl`, at `/api/web-avatar/v1/availability`)
   whether the live avatar is offered for this site and locale. When it is and
   the conversation has its first answer, a consent card explains what happens
   and links to `/privacy#live-avatar`; with no answer yet, the view asks the
   visitor to choose a suggested question in Chat first. Start runs a
-  Cloudflare Turnstile check (action `avatar_start`), creates the session and
-  joins its room: the video, the captions, an "AI avatar · not a real person"
+  Cloudflare Turnstile check (action `avatar_start`) where the server checks
+  for bots, creates the session and joins its room: the video, the captions, an "AI avatar · not a real person"
   badge, a countdown, Stop and Continue in Chat. Where a browser holds sound
   back (Safari, iOS), a "Tap to turn on sound" button appears. A refusal (busy,
   limits, region, language, paused, a question the avatar cannot read) is one
@@ -379,6 +406,14 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   digest for all of them (the card's title, intro, processing, storage and
   privacy-link lines, each ending with a line feed: 760 bytes, SHA-256
   `2e02b051ceb1163c14bc58fa63a954a12c0d1f2695029a6d4805922d74c793f7`).
+  `web-consent-2026-11-03` is the same card without "When you start,
+  Cloudflare checks for bots.", for a server whose bot check is `off` (716
+  bytes, SHA-256
+  `bb7516df3cf3a910c6ec1623391f859e6c48e7e7d305d4fb333f18d4115da203`).
+  Each version says which bot check its words describe, and the card is shown
+  only where the server's `botCheck` is the same: a server that runs no bot
+  check must name `web-consent-2026-11-03`, and one that checks must name a
+  version that says so, or the view stays as it was.
   `web-consent-2026-10-31` (which names the product, "a suggested Healthy Bowl
   question") and `web-consent-2026-11` stay, unchanged, for servers that still
   name them.
@@ -389,22 +424,24 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   apps-first hand-over, so it does not say which.
 - **Requests.** All three go to the gateway without credentials. The create
   request carries `content-type: application/json`, `idempotency-key` (a UUID
-  v4) and `x-web-avatar-bot-token` (the Turnstile token, which the gateway
-  verifies and does not forward); the availability request and the end request
-  carry no header of the SDK's own. The conversation token is sent in the create
+  v4) and, only where the server checks for bots, `x-web-avatar-bot-token` (the
+  Turnstile token, which the gateway verifies and does not forward); the
+  availability request and the end request carry no header of the SDK's own. The conversation token is sent in the create
   body only. Neither it, nor the session's end secret, nor the room token, nor
   the bot check's token is ever written into the page, the console or storage by
   the live avatar (the chat keeps its own copy of the conversation in
   `localStorage`, as it always has).
-- **Bot-check binding (web API contract v1.1, additive).** The Turnstile widget
+- **Bot-check binding (web API contract v1.1, additive; `turnstile` mode
+  only).** The Turnstile widget
   is rendered with `cData` set to
   `base64url_nopad(SHA-256(UTF-8("boff-web-avatar-cdata/v1\n" + site + "\n" + locale + "\n" + conversationToken + "\n" + messageId)))`,
   made with WebCrypto from the exact values the create body then carries, before
   the widget is rendered, so the gateway can check that the token was minted for
   this request. The action stays `avatar_start`, and nothing else in v1
-  changes. A browser without WebCrypto (a page that is not a secure context)
-  cannot start the live avatar: Start loads neither the room module nor the bot
-  check's script there, and shows the view as it was. Pinned vector: site
+  changes. Where the server checks for bots, a browser without WebCrypto (a
+  page that is not a secure context) cannot start the live avatar: Start loads
+  neither the room module nor the bot check's script there, and shows the view
+  as it was. Pinned vector: site
   `healthybowl`, locale `en`, conversation token
   `ct_vector_0123456789abcdefghijklmnopqrstuvwx`, message id
   `11111111-2222-4333-8444-555555555555` give
@@ -418,7 +455,9 @@ publishes audio, video or data, and it sends the avatar nothing to say.
   preflight.
 - **Your page's headers.** A site with a Content Security Policy must allow:
   - `script-src` and `frame-src`: `https://challenges.cloudflare.com` (the
-    Turnstile bot check);
+    Turnstile bot check). Only needed where the server's bot check is
+    `turnstile`; keep it anyway, so that turning the bot check on later is a
+    server change and not a new release of the site;
   - `connect-src`, the gateway origin (the three requests);
   - `connect-src`, the media room: `wss://<project>.livekit.cloud`. For a
     LiveKit Cloud room the media library also asks
@@ -587,14 +626,23 @@ A site adds these lines.
    usual place whenever the banner is not on screen.
 
 4. **The build env var** `VITE_AVATAR_TURNSTILE_SITE_KEY`: the site's
-   Cloudflare Turnstile site key. `websiteAvatarLive` returns `undefined` (the
-   still picture and "Live avatar coming soon", no live avatar) when it is
-   unset or empty; on alpha (`VITE_DEPLOY_ENV=alpha`) it accepts Cloudflare's
-   always-pass test key `1x00000000000000000000AA` (the alpha gateway runs
-   Turnstile in dummy mode) or a real key; everywhere else, production
-   included, only a real-looking key (`0x…`, letters, digits, `_` and `-`, 18
-   to 64 characters) that is not one of Cloudflare's test keys (`1x…AA`,
-   `2x…AB`, `1x…BB`, `2x…BB`, `3x…FF`, or anything of their shape). Install
+   Cloudflare Turnstile site key, used only where the server checks for bots
+   (its availability's `botCheck` is `turnstile`). The server decides whether
+   the live avatar is offered on the site (its reviewed site list, its pause,
+   its caps) and whether it checks for bots, so the key is no longer the
+   opt-in: when it is unset or empty, `websiteAvatarLive` returns the live
+   config without a key, which runs where the server's bot check is `off` and
+   stays the still picture where it is `turnstile`. On alpha
+   (`VITE_DEPLOY_ENV=alpha`) it accepts Cloudflare's always-pass test key
+   `1x00000000000000000000AA` (the alpha gateway runs Turnstile in dummy mode)
+   or a real key; everywhere else, production included, only a real-looking key
+   (`0x…`, letters, digits, `_` and `-`, 18 to 64 characters) that is not one of
+   Cloudflare's test keys (`1x…AA`, `2x…AB`, `1x…BB`, `2x…BB`, `3x…FF`, or
+   anything of their shape). A key that is set but refused returns `undefined`
+   (the still picture and "Live avatar coming soon"), never a live avatar
+   without it. It also sets `allowTestSiteKey` (true on alpha only), so the
+   view itself refuses a test key on any other build. Pass `enabled: false` to
+   keep the still picture on a build whatever the server offers. Install
    `livekit-client` on the site (see [Live avatar](#live-avatar-opt-in-receive-only)),
    and declare the variable in `vite-env.d.ts`.
    `websiteAvatarLive` trusts `VITE_DEPLOY_ENV`, so a production build must

package/dist/avatar-live-view/index.d.mts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { E as ExplorePanelAvatarLive, a as ExploreLocale, A as AvatarConversation } from '../explore-avatar-live-config-BGsGwbcq.mjs';
+import { E as ExplorePanelAvatarLive, a as ExploreLocale, A as AvatarConversation } from '../explore-avatar-live-config-Bp3kQbU2.mjs';
 import '../types-CndbmBK-.mjs';
 import '../use-explore-chat-zRuoAin6.mjs';
 import '../explore-types-Bb2Ih3d8.mjs';
@@ -23,6 +23,11 @@ interface AvatarLiveViewProps {
     onContinueInChat: () => void;
     /** "Continue in Chat" in the panel's language: the panel's own word for it, so this chunk carries none of the panel's. */
     continueInChat: string;
+    /**
+     * "New chat" in the panel's language, the panel's own word for it: the button that starts over (the conversation's
+     * `reset`, as the chat's own New chat button does, then the Chat tab) where this conversation can never be read.
+     */
+    newChat: string;
     /**
      * Nothing to ask the server about: an incomplete config, no gateway, no shared conversation to read (no provider, or a
      * read-only shared one), or a locale whose strings have not been reviewed. The tab stays as it was. Decided by
@@ -37,6 +42,6 @@ interface AvatarLiveViewProps {
     /** The panel's conversation, null when there is no provider. */
     conversation: AvatarConversation | null;
 }
-declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
+declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, newChat, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
 
 export { AvatarLiveView, type AvatarLiveViewProps };

package/dist/avatar-live-view/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { E as ExplorePanelAvatarLive, a as ExploreLocale, A as AvatarConversation } from '../explore-avatar-live-config-B171o1Yo.js';
+import { E as ExplorePanelAvatarLive, a as ExploreLocale, A as AvatarConversation } from '../explore-avatar-live-config-Cetx8-Zu.js';
 import '../types-CndbmBK-.js';
 import '../use-explore-chat-DunjG-3p.js';
 import '../explore-types-Bb2Ih3d8.js';
@@ -23,6 +23,11 @@ interface AvatarLiveViewProps {
     onContinueInChat: () => void;
     /** "Continue in Chat" in the panel's language: the panel's own word for it, so this chunk carries none of the panel's. */
     continueInChat: string;
+    /**
+     * "New chat" in the panel's language, the panel's own word for it: the button that starts over (the conversation's
+     * `reset`, as the chat's own New chat button does, then the Chat tab) where this conversation can never be read.
+     */
+    newChat: string;
     /**
      * Nothing to ask the server about: an incomplete config, no gateway, no shared conversation to read (no provider, or a
      * read-only shared one), or a locale whose strings have not been reviewed. The tab stays as it was. Decided by
@@ -37,6 +42,6 @@ interface AvatarLiveViewProps {
     /** The panel's conversation, null when there is no provider. */
     conversation: AvatarConversation | null;
 }
-declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
+declare function AvatarLiveView({ live, active, locale, productName, still, fallback, onContinueInChat, continueInChat, newChat, off, base, headers, conversation, }: AvatarLiveViewProps): react.JSX.Element;
 
 export { AvatarLiveView, type AvatarLiveViewProps };