@helpai/elements 1.1.14 → 1.1.15

package/index.d.ts

@@ -942,7 +942,7 @@ interface ChatWidgetOptions {
   /**
    * Agent-API base (no trailing slash) — set it when the
    * `module-help-ai-agent-api` service is reached DIRECTLY (a standalone
-   * local module, e.g. `http://localhost:3087`) instead of through the
+   * local module, e.g. `http://localhost:3111`) instead of through the
    * edge. Routes attach as-is (`${agentApiBaseUrl}/pai/handshake`).
    * Precedence: this option > derived from the main origin
    * (`${baseUrl}/api/agent`). Not server-pushable — the handshake already
@@ -953,7 +953,7 @@ interface ChatWidgetOptions {
    * Data-API base (no trailing slash) — the `module-help-ai-data-api`
    * service serving content, form definitions, and form submissions under
    * `/pai/*` (`content`, `bootstrap`, `submit-form`).
-   * Set it for a standalone local module (e.g. `http://localhost:3106`).
+   * Set it for a standalone local module (e.g. `http://localhost:3105`).
    * Precedence: this option > server-pushed `config.dataApiBaseUrl` > derived
    * from the main origin (`${baseUrl}/api/data`, e.g.
    * `https://help.ai/api/data`).
@@ -1110,42 +1110,6 @@ interface ResolvedOptions {
   onClose?: ChatWidgetOptions["onClose"];
   onError?: ChatWidgetOptions["onError"];
 }
-/**
- * Shape of the server-pushed `config` object in `HandshakeResponse`.
- *
- * Matches a subset of {@link ChatWidgetOptions} — anything the server can
- * reasonably dictate (UI, behaviour, routing). Callbacks (`onMessage` etc.)
- * and the public key are deliberately excluded — those are client concerns.
- *
- * Form definitions no longer ride this config: the widget fetches them from
- * the data-API (`GET /pai/bootstrap`). A stale backend still pushing
- * `config.forms` is ignored.
- */
-interface ServerConfig$1 {
-  /** Data-API base override — adopted only when the host didn't set one. */
-  dataApiBaseUrl?: string;
-  /**
-   * Storage-schema version — the deployment-owned force-reset lever, pushed ONLY
-   * via the handshake (deliberately not an embed attribute / `init` option).
-   * Pushing a new value abandons every client's prior storage namespace
-   * (visitor id, conversation, prefs, panel state, caches) on next load. The
-   * widget stashes it and the next mount folds `.v<version>` into every key.
-   */
-  storageVersion?: string;
-  presentation?: PresentationOptions;
-  behavior?: BehaviorOptions;
-  theme?: ThemePreference | ThemeOverrides;
-  launcher?: LauncherOptions;
-  header?: HeaderOptions;
-  composer?: ComposerOptions;
-  feedback?: FeedbackOptions;
-  i18n?: I18nOptions;
-  footer?: FooterOptions;
-  features?: FeatureFlags;
-  modules?: ModulesOptions;
-  tracking?: TrackingOptions;
-  endpoints?: Endpoints;
-}
 //#endregion
 //#region src/core/logger.d.ts
 /**
@@ -1181,362 +1145,6 @@ interface LogEntry {
   payload?: unknown;
 }
 //#endregion
-//#region src/core/persistence.d.ts
-/** Drag-resized panel dimensions. Persisted only when resize is enabled. */
-interface WidgetSize {
-  width: number;
-  height: number;
-}
-/**
- * User-changeable preferences. Sent to the backend on every request as a
- * `userPrefs` field so the server can detect drift (e.g. user changed
- * locale on another tab) and reconcile.
- *
- * Every field is optional — an unset key inherits the server / page-owner
- * default. Empty object `{}` means "no preference recorded yet."
- */
-interface UserPrefs {
-  /** BCP-47 tag picked from the language switcher. */
-  locale?: string;
-  /** Drag-resized panel dimensions. */
-  widgetSize?: WidgetSize;
-  /** Sound on/off toggle (icon button). */
-  soundMuted?: boolean;
-  /** Theme picked from the theme switcher. */
-  themeMode?: "auto" | "light" | "dark";
-  /** Text size picked from the text-size switcher. */
-  textSize?: "small" | "normal" | "large";
-}
-//#endregion
-//#region src/stream/types.d.ts
-/** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
-type FeedbackValue = "up" | "down" | null;
-//#endregion
-//#region src/stream/protocol.d.ts
-/**
- * Who is driving replies in a conversation — the widget mirrors the backend `controlMode`.
- *   - `ai-agent`: the AI agent answers (normal operation).
- *   - `awaiting_operator`: operator-control requested, the AI no longer answers — the turn routes to the
- *      operator — while waiting in the operator queue.
- *   - `operator`: a workspace operator took over and is replying.
- *
- * Carried on `HandshakeResponse.controlState`, `LoadConversationResponse.controlState` (resume +
- * history-switch), and the `data-control-state` stream part (on the reply stream). Absent / unknown →
- * treated as `"ai-agent"`.
- */
-type ControlMode = "ai-agent" | "awaiting_operator" | "operator";
-/**
- * The control-state snapshot the widget reads to render composer/typing/banner state. The optional
- * `operatorAvailable` (set on the operator-request response + the awaiting terminal part) tells the
- * widget whether to show "connecting…" or the async-capture ("leave your details") copy.
- */
-interface ControlState {
-  controlMode: ControlMode;
-  /** Monotonic state version: orders received snapshots and fences request/cancel retries to their observed cycle. */
-  controlRevision?: number;
-  /**
-   * The operator's 2-letter initials (operator mode only) — shown in the bubble chrome + banner. The
-   * visitor never sees the full name (privacy); the backend derives the initials. `assignedOperatorId`
-   * also rides the wire but the widget doesn't render it, so it isn't modeled here.
-   */
-  assignedOperatorInitials?: string;
-  /** Whether anyone was in the operator pool when operator-control was requested (awaiting mode advisory). */
-  operatorAvailable?: boolean;
-}
-/** One-shot bot persona shown in the panel header. */
-interface ConversationAgent {
-  name: string;
-  /** Image URL or data URI. When omitted, initials render from `name`. */
-  avatar?: string;
-  /** Subtitle ("AI Assistant", "Support team", …). */
-  title?: string;
-  /** Presence indicator. Default: `'online'`. */
-  status?: "online" | "away" | "offline";
-}
-/** A clickable quick-reply chip. */
-interface ConversationSuggestion {
-  id: string;
-  /** What the chip displays. */
-  label: string;
-  /** What actually gets sent when clicked. Defaults to `label`. */
-  text?: string;
-}
-/** Welcome payload pushed into the message list on first open. */
-interface ConversationWelcome {
-  messages?: Array<{
-    id: string;
-    role: "assistant" | "system";
-    text: string;
-  }>;
-  suggestions?: ConversationSuggestion[];
-}
-/**
- * Response from `POST /pai/handshake` — the widget's one mount-time
- * round-trip. Deliberately LIGHT: identity + deployment surface only
- * (config, agent persona, welcome, page-mode site/blocks, userPrefs).
- * The conversation THREAD is a separate, lazily-fetched read
- * (`GET /conversation`) that only runs once the widget is activated
- * (opened) — a closed launcher costs the page exactly one request.
- *
- * 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 conversation — out of scope for v1).
- */
-interface HandshakeResponse$1 {
-  /**
-   * Public runtime conversation id. The widget mints this UUIDv7 and the backend
-   * validates that it belongs to the public deployment + visitor.
-   */
-  conversationId: string;
-  visitorId?: string;
-  /** Bot persona in the panel header (name, avatar, status). */
-  agent?: ConversationAgent;
-  /** Initial assistant messages + quick-reply chips. */
-  welcome?: ConversationWelcome;
-  /**
-   * Deployment-wide widget configuration the dashboard admin saved
-   * (mode / theme / launcher / actions / composer / features / …).
-   * Client adopts as defaults; customer's `init({...})` still wins
-   * per-field. Same for every visitor of this deployment.
-   */
-  config?: ServerConfig$1;
-  /** Page-mode site config (logo, title). Backend ships it whenever the deployment renders the page-shell sidebar. */
-  site?: Record<string, unknown>;
-  /** Page-mode sidebar blocks (navigation, link cards). Backend ships it whenever the deployment renders the page-shell sidebar. */
-  blocks?: Record<string, unknown>;
-  /** Current control state — seeds the composer/typing/banner state on connect. Absent → `ai-agent`. */
-  controlState?: ControlState;
-  /**
-   * Server's authoritative copy of the visitor's preferences. When present,
-   * client adopts it (overrides local cache) and re-applies it to the UI
-   * (locale, panel size, sound mute). Absent → client keeps its cache.
-   */
-  userPrefs?: UserPrefs;
-  /**
-   * Optional rebind metadata. When the server returns a `visitorId` /
-   * `conversationId` different from what the client sent, this block tells
-   * the client WHY — useful for telemetry and the `visitorRebound` /
-   * `conversationRebound` events fired into the host page. Server is free to
-   * omit it: the client detects rebinding by comparing request vs
-   * response ids regardless.
-   *
-   * Common reasons: `"conflict"` (the id collided with an existing
-   * record), `"expired"` (the id is too old to be re-used), `"invalid"`
-   * (malformed / not a UUIDv7). Custom strings are passed through to
-   * listeners verbatim.
-   */
-  rebind?: {
-    visitorId?: string;
-    conversationId?: string;
-  };
-}
-//#endregion
-//#region src/core/events.d.ts
-/**
- * Payload shape per event. Keyed by event name; use `void` for events that
- * carry no data.
- *
- * **Every user-visible action fires here.** Subscribe via
- * `chat.on("eventName", fn)` to add analytics, side effects, or audit
- * trails without forking the widget. The same names also stream to the
- * structured logger at `info` level when `debug` is enabled.
- */
-interface EventMap {
-  /** Panel opened (floating / modal / drawer). */
-  open: void;
-  /** Panel closed. */
-  close: void;
-  /** Expanded mode toggled (1.5× size). Payload is the new state. */
-  expand: boolean;
-  /** Fullscreen mode toggled. Payload is the new state. */
-  fullscreen: boolean;
-  /** End-user dragged the resize grip — payload is the resolved size. */
-  resize: {
-    width: number;
-    height: number;
-  };
-  /** A message was exchanged. Fires for user, assistant, and operator messages. */
-  message: {
-    role: string;
-    text: string;
-  };
-  /** User submitted a message (fires before the request is sent). */
-  send: {
-    text: string;
-    attachmentCount: number;
-  };
-  /** User cancelled an in-flight stream. */
-  stop: void;
-  /** Clear / new-conversation requested. */
-  clear: void;
-  /** User picked a chat from the history pane / sidebar. */
-  selectConversation: {
-    conversationId: string;
-  };
-  /** User clicked a suggested-message chip. */
-  suggestion: {
-    text: string;
-  };
-  /** History pane toggled. Payload is the resulting view. */
-  toggleHistory: {
-    view: "chat" | "history";
-  };
-  /** A form (intake, CSAT, …) was completed or skipped. */
-  formSubmit: {
-    formId: string;
-    values: Record<string, string>;
-    skipped: boolean;
-  };
-  /** User answered an ask-questions tool request (re-POST follows). */
-  toolResult: {
-    toolCallId: string;
-  };
-  /** User approved / rejected a gated tool call (re-POST follows). */
-  toolDecision: {
-    toolCallId: string;
-    approved: boolean;
-  };
-  /**
-   * User gave feedback on a rateable reply (AI or operator). `value` is `"up"` / `"down"`, or
-   * `null` when they cleared a prior choice. `messageId` is the backend message
-   * id. Also POSTed best-effort to `/pai/message-feedback`; a host listener can
-   * mirror it to analytics.
-   */
-  messageFeedback: {
-    messageId: string;
-    value: FeedbackValue;
-  };
-  /** A content list (news / help / home block) rendered. */
-  contentView: {
-    section: string;
-    tags?: string;
-    count: number;
-  };
-  /** An article / content item was opened. */
-  contentOpen: {
-    contentId: string;
-    tags?: string;
-  };
-  /** The help search ran. Length + hit count only — never the query text. */
-  contentSearch: {
-    queryLength: number;
-    hitCount: number;
-  };
-  /** An opened article was read (dwell threshold passed). Fires once per open. */
-  contentRead: {
-    contentId: string;
-  };
-  /** A link inside an opened article was followed. */
-  contentLinkClick: {
-    contentId: string;
-  };
-  /** Files attached (drag-drop, file picker, paste). */
-  attach: {
-    count: number;
-    totalBytes: number;
-  };
-  /** An attachment was removed before send. */
-  removeAttachment: {
-    id: string;
-  };
-  /** Voice recording started. */
-  voiceStart: void;
-  /** Voice recording stopped and was sent for transcription. */
-  voiceStop: {
-    durationMs: number;
-  };
-  /** Voice recording cancelled (e.g. user released outside the button). */
-  voiceCancel: void;
-  /** End-user picked a different UI locale. Payload is the new BCP-47 tag. */
-  localeChange: string;
-  /** End-user picked a different theme mode (`auto` / `light` / `dark`). */
-  themeChange: ThemePreference;
-  /** End-user picked a different text size (`small` / `normal` / `large`). */
-  textSizeChange: TextSize;
-  /** End-user toggled the global sound mute. */
-  soundToggle: {
-    muted: boolean;
-  };
-  /** Page-mode sidebar collapsed / expanded. */
-  sidebarToggle: {
-    collapsed: boolean;
-  };
-  /** Pre-engagement launcher callout dismissed. */
-  calloutDismiss: void;
-  /** An unhandled error occurred somewhere in the transport or UI. */
-  error: unknown;
-  /** Connect bootstrap succeeded. Payload is the typed server response. */
-  handshake: HandshakeResponse$1;
-  /**
-   * 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
-   * `/handshake` 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 handshake response). Common values:
-   * `"conflict"` / `"expired"` / `"invalid"`. May be `undefined` if
-   * the server didn't include a `rebind` block.
-   */
-  visitorRebound: {
-    previous: string;
-    current: string;
-    reason?: string;
-  };
-  /**
-   * 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 `conversationId` than the
-   * client sent.
-   */
-  conversationRebound: {
-    previous: string;
-    current: string;
-    reason?: string;
-  };
-}
-type EventName = keyof EventMap;
-//#endregion
-//#region src/ui/host-mode.d.ts
-type HostMode = "page" | "standalone" | "inline" | "modal" | "drawer" | "fullscreen" | "expanded" | "open" | "closed";
-//#endregion
-//#region src/boot.d.ts
-/**
- * Determine what `data-mode` the host should start at — matching what App's
- * mount-time `useEffect` will produce on its first render. Used for the initial
- * paint in both entry points (and `mount()`'s iframe sizing); after that, App
- * owns `data-mode` for the lifetime of the instance.
- *
- * `resolveInitialPanelState` is the one source of truth for "what does the first
- * render look like" — App.tsx uses it too. If these two paths ever pick
- * different initial states, an iframe physically resizes between mount and App's
- * first effect (the closed→open→closed flicker this pins against).
- */
-declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
-//#endregion
-//#region src/core/hooks.d.ts
-/** Wildcard that matches every widget id / every event name. */
-declare const HOOK_WILDCARD = "*";
-/**
- * Unified lifecycle callback signature. `data` is `unknown` — narrow it
- * via the `event` discriminator using {@link EventMap} if needed:
- *
- * ```ts
- * HelpAI.hook("*", "*", (inst, event, data) => {
- *   if (event === "message") {
- *     const msg = data as EventMap["message"]; // { role, text }
- *     // ...
- *   }
- * });
- * ```
- */
-type HookListener = (instance: ChatWidgetInstance, event: EventName, data: unknown) => void;
-//#endregion
 //#region src/schema/primitives.d.ts
 /** A single image asset (logo, hero, icon). */
 declare const assetSchema: z.ZodObject<{
@@ -3484,20 +3092,194 @@ declare const handshakeResponseSchema: z.ZodObject<{
   conversationId: z.ZodString;
   userPrefs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   rebind: z.ZodOptional<z.ZodObject<{
-    visitorId: z.ZodOptional<z.ZodEnum<{
-      conflict: "conflict";
-      expired: "expired";
-      invalid: "invalid";
-    }>>;
-    conversationId: z.ZodOptional<z.ZodEnum<{
-      conflict: "conflict";
-      expired: "expired";
-      invalid: "invalid";
-    }>>;
-  }, z.core.$loose>>;
+    conversationId: z.ZodString;
+  }, z.core.$strict>>;
 }, z.core.$loose>;
 type HandshakeResponse = z.infer<typeof handshakeResponseSchema>;
 //#endregion
+//#region src/stream/types.d.ts
+/** A 👍/👎 reaction on a rateable (assistant/operator) message; `null` clears a prior choice. */
+type FeedbackValue = "up" | "down" | null;
+//#endregion
+//#region src/core/events.d.ts
+/**
+ * Payload shape per event. Keyed by event name; use `void` for events that
+ * carry no data.
+ *
+ * **Every user-visible action fires here.** Subscribe via
+ * `chat.on("eventName", fn)` to add analytics, side effects, or audit
+ * trails without forking the widget. The same names also stream to the
+ * structured logger at `info` level when `debug` is enabled.
+ */
+interface EventMap {
+  /** Panel opened (floating / modal / drawer). */
+  open: void;
+  /** Panel closed. */
+  close: void;
+  /** Expanded mode toggled (1.5× size). Payload is the new state. */
+  expand: boolean;
+  /** Fullscreen mode toggled. Payload is the new state. */
+  fullscreen: boolean;
+  /** End-user dragged the resize grip — payload is the resolved size. */
+  resize: {
+    width: number;
+    height: number;
+  };
+  /** A message was exchanged. Fires for user, assistant, and operator messages. */
+  message: {
+    role: string;
+    text: string;
+  };
+  /** User submitted a message (fires before the request is sent). */
+  send: {
+    text: string;
+    attachmentCount: number;
+  };
+  /** User cancelled an in-flight stream. */
+  stop: void;
+  /** Clear / new-conversation requested. */
+  clear: void;
+  /** User picked a chat from the history pane / sidebar. */
+  selectConversation: {
+    conversationId: string;
+  };
+  /** User clicked a suggested-message chip. */
+  suggestion: {
+    text: string;
+  };
+  /** History pane toggled. Payload is the resulting view. */
+  toggleHistory: {
+    view: "chat" | "history";
+  };
+  /** A form (intake, CSAT, …) was completed or skipped. */
+  formSubmit: {
+    formId: string;
+    values: Record<string, string>;
+    skipped: boolean;
+  };
+  /** User answered an ask-questions tool request (re-POST follows). */
+  toolResult: {
+    toolCallId: string;
+  };
+  /** User approved / rejected a gated tool call (re-POST follows). */
+  toolDecision: {
+    toolCallId: string;
+    approved: boolean;
+  };
+  /**
+   * User gave feedback on a rateable reply (AI or operator). `value` is `"up"` / `"down"`, or
+   * `null` when they cleared a prior choice. `messageId` is the backend message
+   * id. Also POSTed best-effort to `/pai/message-feedback`; a host listener can
+   * mirror it to analytics.
+   */
+  messageFeedback: {
+    messageId: string;
+    value: FeedbackValue;
+  };
+  /** A content list (news / help / home block) rendered. */
+  contentView: {
+    section: string;
+    tags?: string;
+    count: number;
+  };
+  /** An article / content item was opened. */
+  contentOpen: {
+    contentId: string;
+    tags?: string;
+  };
+  /** The help search ran. Length + hit count only — never the query text. */
+  contentSearch: {
+    queryLength: number;
+    hitCount: number;
+  };
+  /** An opened article was read (dwell threshold passed). Fires once per open. */
+  contentRead: {
+    contentId: string;
+  };
+  /** A link inside an opened article was followed. */
+  contentLinkClick: {
+    contentId: string;
+  };
+  /** Files attached (drag-drop, file picker, paste). */
+  attach: {
+    count: number;
+    totalBytes: number;
+  };
+  /** An attachment was removed before send. */
+  removeAttachment: {
+    id: string;
+  };
+  /** Voice recording started. */
+  voiceStart: void;
+  /** Voice recording stopped and was sent for transcription. */
+  voiceStop: {
+    durationMs: number;
+  };
+  /** Voice recording cancelled (e.g. user released outside the button). */
+  voiceCancel: void;
+  /** End-user picked a different UI locale. Payload is the new BCP-47 tag. */
+  localeChange: string;
+  /** End-user picked a different theme mode (`auto` / `light` / `dark`). */
+  themeChange: ThemePreference;
+  /** End-user picked a different text size (`small` / `normal` / `large`). */
+  textSizeChange: TextSize;
+  /** End-user toggled the global sound mute. */
+  soundToggle: {
+    muted: boolean;
+  };
+  /** Page-mode sidebar collapsed / expanded. */
+  sidebarToggle: {
+    collapsed: boolean;
+  };
+  /** Pre-engagement launcher callout dismissed. */
+  calloutDismiss: void;
+  /** An unhandled error occurred somewhere in the transport or UI. */
+  error: unknown;
+  /** Connect bootstrap succeeded. Payload is the typed server response. */
+  handshake: HandshakeResponse;
+  /** Server replaced the requested conversationId and the widget adopted it. */
+  conversationRebound: {
+    previous: string;
+    current: string;
+  };
+}
+type EventName = keyof EventMap;
+//#endregion
+//#region src/ui/host-mode.d.ts
+type HostMode = "page" | "standalone" | "inline" | "modal" | "drawer" | "fullscreen" | "expanded" | "open" | "closed";
+//#endregion
+//#region src/boot.d.ts
+/**
+ * Determine what `data-mode` the host should start at — matching what App's
+ * mount-time `useEffect` will produce on its first render. Used for the initial
+ * paint in both entry points (and `mount()`'s iframe sizing); after that, App
+ * owns `data-mode` for the lifetime of the instance.
+ *
+ * `resolveInitialPanelState` is the one source of truth for "what does the first
+ * render look like" — App.tsx uses it too. If these two paths ever pick
+ * different initial states, an iframe physically resizes between mount and App's
+ * first effect (the closed→open→closed flicker this pins against).
+ */
+declare function resolveInitialHostMode(options: ResolvedOptions): HostMode;
+//#endregion
+//#region src/core/hooks.d.ts
+/** Wildcard that matches every widget id / every event name. */
+declare const HOOK_WILDCARD = "*";
+/**
+ * Unified lifecycle callback signature. `data` is `unknown` — narrow it
+ * via the `event` discriminator using {@link EventMap} if needed:
+ *
+ * ```ts
+ * HelpAI.hook("*", "*", (inst, event, data) => {
+ *   if (event === "message") {
+ *     const msg = data as EventMap["message"]; // { role, text }
+ *     // ...
+ *   }
+ * });
+ * ```
+ */
+type HookListener = (instance: ChatWidgetInstance, event: EventName, data: unknown) => void;
+//#endregion
 //#region src/index.d.ts
 /**
  * Handle returned by {@link mount} / {@link init}. All methods are safe to call