@helpai/elements 0.25.0 → 0.27.0

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 StartConversationResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-B0uvvJYK.js';
+export { A as Asset, B as BlocksConfig, C as ConnectionConfig, a as ConnectionConfigPartial, H as HandshakeResponse, L as Link, S as ServerConfig, b as SiteConfig, W as WidgetConfig, c as WidgetConfigPartial, d as WidgetSettings, e as WidgetSettingsPartial } from './deployment-CcW_mx_i.js';
 import 'zod';
 
 /**
@@ -113,73 +113,11 @@ interface UserPrefs {
     textSize?: "small" | "normal" | "large";
 }
 
-/**
- * A human-in-the-loop approval decision on a tool call. Mirrors AI SDK v6's
- * `ToolUIPart.approval`: `id` correlates the request ↔ response; `approved`
- * is filled once the user decides; `reason` is an optional note.
- */
-interface ToolApproval {
-    id: string;
-    approved?: boolean;
-    reason?: string;
-}
-/**
- * Lifecycle of a tool part. `input` — args streaming. `awaiting` —
- * server-executed tool waiting on output. `awaiting-input` — the ask-input
- * tool waiting on the user's inline-form answer. `awaiting-approval` — a gated
- * action waiting on approve/reject. `output` — resolved. `error` — failed.
- */
-type ToolState = "input" | "awaiting" | "awaiting-input" | "awaiting-approval" | "output" | "error";
-
 /** A tool reference on the wire: `{ code, config }`. `config` is opaque. */
 interface ToolRef {
     code: string;
     config?: Record<string, unknown>;
 }
-interface WireMessage {
-    id: string;
-    role: "user" | "assistant" | "system";
-    parts: WirePart[];
-    /**
-     * ISO-8601 timestamp the message was created (a serialized Mongo ISODate,
-     * e.g. `2026-06-10T07:50:55.816Z`) — every wire date uses this format.
-     * Optional so older backends still parse; when present, the widget shows
-     * the real send time (and groups messages by day) on reload instead of
-     * falling back to "now". Parse with {@link parseWireDate}.
-     */
-    createdAt?: string;
-}
-type WirePart = {
-    type: "text";
-    text: string;
-} | {
-    type: "file";
-    /** Canonical URL. May be a custom scheme (e.g. `library-id://<id>`). */
-    url: string;
-    mediaType: string;
-    /** Original filename as uploaded. */
-    filename?: string;
-    /** Opaque id from the upload response — lets the backend dedupe + cache. */
-    fileId?: string;
-    /** Size in bytes. */
-    fileSize?: number;
-} | {
-    /**
-     * A tool call on the wire. Carries the resolved result up to the backend
-     * on a HITL re-POST: the ask-input answer rides in `output`, an approval
-     * decision in `approval`. Sent up only for parts the user has acted on
-     * (state `output`/`error`/`awaiting-approval` with a decision); in-flight
-     * tool parts are not re-serialized. Aligns with AI SDK v6 tool parts.
-     */
-    type: "tool";
-    toolCallId: string;
-    toolName: string;
-    state: ToolState;
-    input?: unknown;
-    output?: unknown;
-    errorText?: string;
-    approval?: ToolApproval;
-};
 /** One-shot bot persona shown in the panel header. */
 interface ConversationAgent {
     name: string;
@@ -208,8 +146,12 @@ interface ConversationWelcome {
     suggestions?: ConversationSuggestion[];
 }
 /**
- * Response from `POST /ai/agent/start-conversation`. Every field is optional so the
- * backend can opt into surfaces incrementally.
+ * 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
@@ -217,14 +159,13 @@ interface ConversationWelcome {
  * 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 StartConversationResponse {
+interface HandshakeResponse {
     /**
      * 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;
-    canContinue?: boolean;
     /** Bot persona in the panel header (name, avatar, status). */
     agent?: ConversationAgent;
     /** Initial assistant messages + quick-reply chips. */
@@ -240,7 +181,6 @@ interface StartConversationResponse {
     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>;
-    messages?: WireMessage[];
     /**
      * Server's authoritative copy of the visitor's preferences. When present,
      * client adopts it (overrides local cache) and re-applies it to the UI
@@ -292,7 +232,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-conversation response.
+ * Page mode reads `site` and `blocks` from the handshake response.
  */
 type Mode = "floating" | "inline" | "standalone" | "page" | "modal" | "drawer";
 /** End-user text-size preference — scales the whole type ramp. */
@@ -961,9 +901,9 @@ interface PageContext {
  * like a CDN presign service).
  */
 interface Endpoints {
-    /** File upload endpoint. Default: `'/ai/agent/upload-file'`. */
+    /** File upload endpoint. Default: `'/pai/upload-file'`. */
     upload?: string;
-    /** Voice transcription endpoint. Default: `'/ai/agent/transcribe-audio'`. */
+    /** Voice transcription endpoint. Default: `'/pai/transcribe-audio'`. */
     transcribe?: string;
     /**
      * Form submission endpoint. Default: `'/submit-form'`. When any form
@@ -993,13 +933,14 @@ interface Endpoints {
 /** Section: anonymous owner-facing usage tracking. */
 interface TrackingOptions {
     /**
-     * Master switch. Default `false` — tracking stays off until the
-     * deployment (or the embedding page) explicitly turns it on.
+     * Master switch. Default `true` — the widget always fires; the data
+     * module gates ingestion per deployment server-side. Set `false`
+     * (deployment config or init) to silence the client entirely.
      */
     enabled?: boolean;
     /**
-     * Pixel collector URL. Default: `${dataBaseUrl}/elements/px.gif`
-     * (e.g. `https://help.ai/api/data/elements/px.gif`).
+     * Pixel collector URL. Default: `${dataBaseUrl}/pai/elements-px.gif`
+     * (e.g. `https://help.ai/api/data/pai/elements-px.gif`).
      */
     endpoint?: string;
     /**
@@ -1010,7 +951,7 @@ interface TrackingOptions {
     /**
      * Anti-forgery token, echoed as `tk=` on every hit. **Server-issued,
      * never set by hand** — the backend mints it in the
-     * `/start-conversation` response (HMAC over `pk`/`vid`/expiry with a
+     * `/handshake` response (HMAC over `pk`/`vid`/expiry with a
      * server-side secret; see `docs/api/tracking-collector.md`) and the
      * collector verifies it statelessly. Opaque to the client.
      */
@@ -1027,7 +968,7 @@ interface ResolvedTracking {
 /**
  * The three composing roots: raw input ({@link ChatWidgetOptions}),
  * post-normalisation runtime shape ({@link ResolvedOptions}), and the
- * subset the server can push back via `/start-conversation` ({@link
+ * subset the server can push back via `/handshake` ({@link
  * ServerConfig}).
  *
  * Internal modules always depend on `ResolvedOptions`. The raw shape
@@ -1066,14 +1007,26 @@ interface ChatWidgetOptions {
     aiAgentDeploymentId?: string;
     /**
      * MAIN site origin (no trailing slash, e.g. `https://help.ai`). The API
-     * modules derive from it: the agent API lives at `${baseUrl}/api/agent`,
-     * the data API at `${baseUrl}/api/data`. Defaults to the brand's origin.
+     * modules derive from it — the production edge mounts the agent API at
+     * `${baseUrl}/api/agent` and the data API at `${baseUrl}/api/data`.
+     * Defaults to the brand's origin.
      */
     baseUrl?: string;
+    /**
+     * 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
+     * edge. Routes attach as-is (`${agentBaseUrl}/pai/handshake`).
+     * Precedence: this option > derived from the main origin
+     * (`${baseUrl}/api/agent`). Not server-pushable — the handshake already
+     * travelled over it.
+     */
+    agentBaseUrl?: string;
     /**
      * Data-API base (no trailing slash) — the `module-help-ai-data-api`
      * service serving content, form definitions, and form submissions at
      * root-level paths (`/content`, `/forms`, `/activity`, `/submit-form`).
+     * Set it for a standalone local module (e.g. `http://localhost:3106`).
      * Precedence: this option > server-pushed `config.dataBaseUrl` > derived
      * from the main origin (`${baseUrl}/api/data`, e.g.
      * `https://help.ai/api/data`).
@@ -1133,6 +1086,8 @@ interface ResolvedOptions {
     publicKey?: string;
     aiAgentDeploymentId?: string;
     baseUrl: string;
+    /** Resolved agent-API base — see {@link ChatWidgetOptions.agentBaseUrl}. */
+    agentBaseUrl: string;
     /** Resolved data-API base — see {@link ChatWidgetOptions.dataBaseUrl}. */
     dataBaseUrl: string;
     userContext?: UserContext;
@@ -1221,7 +1176,7 @@ interface ResolvedOptions {
     onError?: ChatWidgetOptions["onError"];
 }
 /**
- * Shape of the server-pushed `widget` object in `StartConversationResponse`.
+ * Shape of the server-pushed `widget` object in `HandshakeResponse`.
  *
  * Matches a subset of {@link ChatWidgetOptions} — anything the server can
  * reasonably dictate (UI, behaviour, routing). Callbacks (`onMessage` etc.)
@@ -1395,18 +1350,18 @@ interface EventMap {
     /** An unhandled error occurred somewhere in the transport or UI. */
     error: unknown;
     /** Connect bootstrap succeeded. Payload is the typed server response. */
-    conversationStarted: StartConversationResponse;
+    handshake: HandshakeResponse;
     /**
      * 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-conversation` response. The widget has already adopted the new
+     * `/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 start-conversation response). Common values:
+     * (`rebind.visitorId` in the handshake response). Common values:
      * `"conflict"` / `"expired"` / `"invalid"`. May be `undefined` if
      * the server didn't include a `rebind` block.
      */
@@ -1535,7 +1490,7 @@ interface ChatWidgetInstance {
     expand: () => void;
     /**
      * Open the widget in a new browser tab at `behavior.popOutUrl`
-     * (mount option / start-conversation-pushable), or the brand's
+     * (mount option / handshake-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.
@@ -1551,7 +1506,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 |
-     * conversationStarted | localeChange`.
+     * handshake | localeChange`.
      */
     on: <E extends EventName>(name: E, fn: (payload: EventMap[E]) => void) => () => void;
     /**
@@ -1572,7 +1527,7 @@ interface ChatWidgetInstance {
      * ```
      */
     setUserContext: (userContext: UserContext) => void;
-    /** Clear the end-user context (e.g. on logout) and re-start-conversation anonymously. */
+    /** Clear the end-user context (e.g. on logout) and re-handshake anonymously. */
     clearUserContext: () => void;
     /**
      * Set / merge the host-asserted page/visit context (`area`, `url`, `path`,
@@ -1586,7 +1541,7 @@ interface ChatWidgetInstance {
      * ```
      */
     setPageContext: (pageContext: PageContext) => void;
-    /** Clear the page/visit context and re-start-conversation. */
+    /** Clear the page/visit context and re-handshake. */
     clearPageContext: () => void;
     /**
      * Set the runtime log level. Accepts `"off"` / `"error"` / `"warn"` /