@helpai/elements 0.14.0 → 0.14.2

package/index.d.ts

@@ -1,4 +1,4 @@
-export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartSessionResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-Rtrqo8-b.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, L as Link, S as ServerConfig, b as SiteConfig, c as StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-CWyouRob.js';
 import 'zod';
 
 /**
@@ -40,7 +40,7 @@ interface ClientStorage {
  * populated {@link Strings} map. UI components then read `strings.send` as a
  * normal property access — no per-render lookup, no per-render allocation.
  */
-type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyNewChat" | "historyBack" | "messagesLoading" | "chatClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formDismiss" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputSubmit" | "inputSkip" | "inputSubmitted" | "approvalRequired" | "approve" | "reject" | "approved" | "rejected" | "approvalReason" | "stepNoLongerActive" | "tabHome" | "tabMessages" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
+type StringKey = "launcherOpen" | "panelTitle" | "composerPlaceholder" | "send" | "stop" | "attach" | "micStart" | "micStop" | "micUnsupported" | "expand" | "collapse" | "fullscreen" | "exitFullscreen" | "resizeHandle" | "scrollToBottom" | "popOut" | "close" | "moreActions" | "soundOn" | "soundOff" | "language" | "theme" | "themeAuto" | "themeLight" | "themeDark" | "history" | "historyTitle" | "historyEmpty" | "historyLoading" | "historyNewChat" | "historyBack" | "messagesLoading" | "chatClosed" | "startNewConversation" | "dateToday" | "dateYesterday" | "dateLastWeek" | "dateOlder" | "newConversation" | "dropZone" | "attachmentTooLarge" | "attachmentTooMany" | "attachmentMimeRejected" | "errorRetry" | "errorGeneric" | "errorRateLimited" | "loading" | "thinking" | "thoughts" | "usedTool" | "collapseSidebar" | "expandSidebar" | "formSubmit" | "formSkip" | "formRequired" | "formInvalidEmail" | "formInvalidTel" | "formInvalidUrl" | "formInvalidNumber" | "formTooShort" | "formTooLong" | "formNumberTooSmall" | "formNumberTooLarge" | "formPatternMismatch" | "formChooseAtLeast" | "formChooseAtMost" | "formOther" | "formOtherPlaceholder" | "inputRequired" | "inputSubmit" | "inputSkip" | "inputSubmitted" | "approvalRequired" | "approve" | "reject" | "approved" | "rejected" | "approvalReason" | "stepNoLongerActive" | "tabHome" | "tabMessages" | "tabHelp" | "tabNews" | "modulesEmpty" | "moduleBack" | "contentLoading" | "homeGreeting" | "homeGreetingNamed" | "homeGreetingLead" | "homeSearchPlaceholder" | "homeContentTitle" | "helpTitle" | "helpSearchPlaceholder" | "helpEmpty" | "helpLoading" | "helpSearchEmpty" | "newsTitle" | "newsEmpty" | "newsLoading" | "newsBack" | "newsPublishedAt";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -73,9 +73,9 @@ type StringsOverride = LocaleStrings | Partial<Record<string, LocaleStrings>>;
  * 1. **`visitorId`** — anonymous browser-level identifier, minted once per
  *    widget instance and reused forever. Sent on every backend request so
  *    the server can attach per-visitor settings, history, etc.
- * 2. **`sessionId`** — the active conversation thread. The backend is the
+ * 2. **`conversationId`** — the active conversation thread. The backend is the
  *    source of truth for messages; we store only the id and re-fetch on
- *    reload via `transport.loadSession()`.
+ *    reload via `transport.loadConversation()`.
  * 3. **`userPrefs`** — user preferences (locale, panel size from drag,
  *    sound mute). Cached locally for instant render-before-network, then
  *    reconciled with the server's copy on each `connect()`.
@@ -177,7 +177,7 @@ type WirePart = {
     approval?: ToolApproval;
 };
 /** One-shot bot persona shown in the panel header. */
-interface SessionAgent {
+interface ConversationAgent {
     name: string;
     /** Image URL or data URI. When omitted, initials render from `name`. */
     avatar?: string;
@@ -187,7 +187,7 @@ interface SessionAgent {
     status?: "online" | "away" | "offline";
 }
 /** A clickable quick-reply chip. */
-interface SessionSuggestion {
+interface ConversationSuggestion {
     id: string;
     /** What the chip displays. */
     label: string;
@@ -195,36 +195,36 @@ interface SessionSuggestion {
     text?: string;
 }
 /** Welcome payload pushed into the message list on first open. */
-interface SessionWelcome {
+interface ConversationWelcome {
     messages?: Array<{
         id: string;
         role: "assistant" | "system";
         text: string;
     }>;
-    suggestions?: SessionSuggestion[];
+    suggestions?: ConversationSuggestion[];
 }
 /**
- * Response from `POST /ai/agent/start-session`. Every field is optional so the
+ * Response from `POST /ai/agent/start-conversation`. Every field is optional so the
  * backend can opt into surfaces incrementally.
  *
  * The `userPrefs` field (when present) is the server's authoritative
  * copy of per-visitor preferences — the client should adopt it and update
  * its local cache. Lets a user picking French on their phone see the
  * widget in French when they open it on their laptop (assuming the same
- * `visitorId`, e.g. via authenticated session — out of scope for v1).
+ * `visitorId`, e.g. via authenticated conversation — out of scope for v1).
  */
-interface StartSessionResponse {
+interface StartConversationResponse {
     /**
-     * Public runtime session id. The widget mints this UUIDv7 and the backend
+     * Public runtime conversation id. The widget mints this UUIDv7 and the backend
      * validates that it belongs to the public deployment + visitor.
      */
-    sessionId: string;
+    conversationId: string;
     visitorId?: string;
     canContinue?: boolean;
     /** Bot persona in the panel header (name, avatar, status). */
-    agent?: SessionAgent;
+    agent?: ConversationAgent;
     /** Initial assistant messages + quick-reply chips. */
-    welcome?: SessionWelcome;
+    welcome?: ConversationWelcome;
     /**
      * Deployment-wide widget configuration the dashboard admin saved
      * (mode / theme / launcher / actions / composer / features / …).
@@ -245,9 +245,9 @@ interface StartSessionResponse {
     userPrefs?: UserPrefs;
     /**
      * Optional rebind metadata. When the server returns a `visitorId` /
-     * `sessionId` different from what the client sent, this block tells
+     * `conversationId` different from what the client sent, this block tells
      * the client WHY — useful for telemetry and the `visitorRebound` /
-     * `sessionRebound` events fired into the host page. Server is free to
+     * `conversationRebound` events fired into the host page. Server is free to
      * omit it: the client detects rebinding by comparing request vs
      * response ids regardless.
      *
@@ -258,7 +258,7 @@ interface StartSessionResponse {
      */
     rebind?: {
         visitorId?: string;
-        sessionId?: string;
+        conversationId?: string;
     };
 }
 
@@ -288,7 +288,7 @@ type Position = "bottom-right" | "bottom-left" | "top-right" | "top-left";
  *                  `"12px"` horizontal — restore the legacy full-edge
  *                  slab with `size: { width: "100vw", height: "100vh", inset: "0" }`.
  *
- * Page mode reads `site` and `blocks` from the start-session response.
+ * Page mode reads `site` and `blocks` from the start-conversation response.
  */
 type Mode = "floating" | "inline" | "standalone" | "page" | "modal" | "drawer";
 /** Theme preference. `auto` follows `prefers-color-scheme`. */
@@ -459,10 +459,11 @@ interface FeedbackOptions {
  * interfaces are what the resolver, controller, and form UI consume.
  *
  * A deployment declares an array of {@link FormDef}s; each is bound to trigger
- * event(s), shown blocking (composer gate) or inline (in the transcript), and
- * its answers are recorded via one shared submit endpoint. Generic across
- * verticals — there is NO industry logic; a clinic intake, an insurance claim
- * form, a CSAT survey, and a sales lead capture are all just different config.
+ * event(s) and shown as a gate that replaces the composer (locking the chat
+ * until submit/skip). Its answers are recorded via one shared submit endpoint.
+ * Generic across verticals — there is NO industry logic; a clinic intake, an
+ * insurance claim form, a CSAT survey, and a sales lead capture are all just
+ * different config.
  *
  * The same {@link FormField} shape powers the AI-driven ask-input tool.
  */
@@ -532,8 +533,11 @@ interface FormCondition {
     minMessages?: number;
     maxMessages?: number;
 }
-/** How often a form may show. */
-type FormFrequency = "once" | "session" | "always";
+/**
+ * How often a form may show: `once` per device (persisted), once per
+ * `conversation` (re-eligible when a new conversation starts), or `always`.
+ */
+type FormFrequency = "once" | "conversation" | "always";
 /** One form as authored in config (raw input). */
 interface FormDef {
     /** Stable id — persistence dedupe + `manual` `openForm(id)`. */
@@ -545,8 +549,6 @@ interface FormDef {
     description?: string;
     submitLabel?: string;
     skippable?: boolean;
-    /** Gate the composer. Honored only for `pre-chat` / `after-messages`. */
-    blocking?: boolean;
     /** Default `once`. */
     frequency?: FormFrequency;
     /**
@@ -569,7 +571,6 @@ interface ResolvedForm {
     description?: string;
     submitLabel?: string;
     skippable: boolean;
-    blocking: boolean;
     frequency: FormFrequency;
     /** Mirror answers into `userContext` (false → PII, endpoint only). */
     mirrorToContext: boolean;
@@ -953,9 +954,9 @@ interface Endpoints {
     transcribe?: string;
     /**
      * Form submission endpoint. Default: `'/ai/agent/submit-form'`. When any form
-     * (a blocking gate, an inline CSAT, etc.) is completed, the widget POSTs the
-     * captured values here (fire-and-forget), keyed by the same `visitorId` +
-     * `sessionId` the conversation uses; the payload carries `formId` + `trigger`
+     * (a pre-chat lead capture, a CSAT survey, etc.) is completed, the widget POSTs
+     * the captured values here (fire-and-forget), keyed by the same `visitorId` +
+     * `conversationId` the conversation uses; the payload carries `formId` + `trigger`
      * so the backend can route. Optional: a backend that doesn't implement it just
      * 404s and the submission is ignored.
      */
@@ -965,7 +966,7 @@ interface Endpoints {
 /**
  * The three composing roots: raw input ({@link ChatWidgetOptions}),
  * post-normalisation runtime shape ({@link ResolvedOptions}), and the
- * subset the server can push back via `/start-session` ({@link
+ * subset the server can push back via `/start-conversation` ({@link
  * ServerConfig}).
  *
  * Internal modules always depend on `ResolvedOptions`. The raw shape
@@ -994,7 +995,7 @@ interface ChatWidgetOptions {
     /**
      * Stable identifier for this widget instance. Use when mounting more
      * than one widget on the same page (different deployments, different
-     * targets). Isolates client-storage namespaces (visitorId, active sessionId,
+     * targets). Isolates client-storage namespaces (visitorId, active conversationId,
      * cached userPrefs). Default: `"default"`.
      */
     widgetId?: string;
@@ -1140,7 +1141,7 @@ interface ResolvedOptions {
     onError?: ChatWidgetOptions["onError"];
 }
 /**
- * Shape of the server-pushed `widget` object in `StartSessionResponse`.
+ * Shape of the server-pushed `widget` object in `StartConversationResponse`.
  *
  * Matches a subset of {@link ChatWidgetOptions} — anything the server can
  * reasonably dictate (UI, behaviour, routing). Callbacks (`onMessage` etc.)
@@ -1248,7 +1249,7 @@ interface EventMap {
     clear: void;
     /** User picked a chat from the history pane / sidebar. */
     selectChat: {
-        sessionId: string;
+        conversationId: string;
     };
     /** User clicked a suggested-message chip. */
     suggestion: {
@@ -1307,18 +1308,18 @@ interface EventMap {
     /** An unhandled error occurred somewhere in the transport or UI. */
     error: unknown;
     /** Connect bootstrap succeeded. Payload is the typed server response. */
-    sessionStarted: StartSessionResponse;
+    conversationStarted: StartConversationResponse;
     /**
      * Server rebound the `visitorId` — e.g. the client-minted id
      * conflicted with an existing record, was expired, or otherwise
      * rejected, and the server returned a fresh one in the
-     * `/start-session` response. The widget has already adopted the new
+     * `/start-conversation` response. The widget has already adopted the new
      * id and persisted it; this event is informational so host pages
      * can re-link analytics / external systems that pinned the
      * previous value.
      *
      * `reason` is the server's explanation, when provided
-     * (`rebind.visitorId` in the start-session response). Common values:
+     * (`rebind.visitorId` in the start-conversation response). Common values:
      * `"conflict"` / `"expired"` / `"invalid"`. May be `undefined` if
      * the server didn't include a `rebind` block.
      */
@@ -1328,12 +1329,12 @@ interface EventMap {
         reason?: string;
     };
     /**
-     * Server rebound the `sessionId` — same shape and semantics as
+     * Server rebound the `conversationId` — same shape and semantics as
      * `visitorRebound` but for the conversation-thread id. Fires when
-     * the server's response carries a different `sessionId` than the
+     * the server's response carries a different `conversationId` than the
      * client sent.
      */
-    sessionRebound: {
+    conversationRebound: {
         previous: string;
         current: string;
         reason?: string;
@@ -1447,7 +1448,7 @@ interface ChatWidgetInstance {
     expand: () => void;
     /**
      * Open the widget in a new browser tab at `behavior.popOutUrl`
-     * (mount option / start-session-pushable), or the brand's
+     * (mount option / start-conversation-pushable), or the brand's
      * `BRAND.standaloneUrl` build-time default. Carries the active
      * `chat` + `widgetId` as query params. No-ops when the resolved
      * URL is empty.
@@ -1463,7 +1464,7 @@ interface ChatWidgetInstance {
      * Subscribe to a lifecycle event. Returns an `off` function. See
      * {@link EventMap} for the full set + payload shapes — currently
      * `open | close | message | error | expand | fullscreen | popOut |
-     * sessionStarted | localeChange`.
+     * conversationStarted | localeChange`.
      */
     on: <E extends EventName>(name: E, fn: (payload: EventMap[E]) => void) => () => void;
     /**
@@ -1484,7 +1485,7 @@ interface ChatWidgetInstance {
      * ```
      */
     setUserContext: (userContext: UserContext) => void;
-    /** Clear the end-user context (e.g. on logout) and re-start-session anonymously. */
+    /** Clear the end-user context (e.g. on logout) and re-start-conversation anonymously. */
     clearUserContext: () => void;
     /**
      * Set / merge the host-asserted page/visit context (`area`, `url`, `path`,
@@ -1498,7 +1499,7 @@ interface ChatWidgetInstance {
      * ```
      */
     setPageContext: (pageContext: PageContext) => void;
-    /** Clear the page/visit context and re-start-session. */
+    /** Clear the page/visit context and re-start-conversation. */
     clearPageContext: () => void;
     /**
      * Set the runtime log level. Accepts `"off"` / `"error"` / `"warn"` /