@helpai/elements 0.24.0 → 0.26.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-BP2axIFu.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-2pMWV4oW.js';
 import 'zod';
 
 /**
@@ -113,94 +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 recorded form submission, returned on `/ai/agent/start-conversation`
- * (alongside `messages`) so the widget can re-place the "form submitted /
- * skipped" marker at its chronological spot in the timeline.
- */
-interface FormSubmissionRecord {
-    formId: string;
-    /** The trigger kind that surfaced the form. */
-    trigger: string;
-    /** True when the visitor skipped instead of answering. */
-    skipped?: boolean;
-    /** ISO-8601 — same format + name as {@link WireMessage.createdAt}. */
-    createdAt?: string;
-    /**
-     * The visitor's own answers, echoed back so the submitted marker can offer
-     * a read-only review after a reload. Scoped to the same `visitorId` that
-     * submitted them — this is the visitor seeing their own data, independent
-     * of `submit.toContext` (which governs mirroring into request context).
-     */
-    values?: Record<string, string>;
-}
 /** One-shot bot persona shown in the panel header. */
 interface ConversationAgent {
     name: string;
@@ -229,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 /ai-agent/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
@@ -238,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. */
@@ -261,14 +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[];
-    /**
-     * Form submissions recorded for this conversation (via
-     * `/ai/agent/submit-form`), returned like `messages` so the widget can
-     * reconstruct the timeline on resume — each renders as a collapsed
-     * "form submitted" marker at its chronological position.
-     */
-    formSubmissions?: FormSubmissionRecord[];
     /**
      * Server's authoritative copy of the visitor's preferences. When present,
      * client adopts it (overrides local cache) and re-applies it to the UI
@@ -320,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. */
@@ -590,7 +502,7 @@ interface FormDef {
      * answers. Default `true`. Set `false` to keep the marker plain — e.g.
      * sensitive answers that shouldn't linger on screen (pairs with
      * `mirrorToContext: false`; the backend should also omit `values` from the
-     * `formSubmissions` echo for such forms).
+     * `/activity` records for such forms).
      */
     reviewable?: boolean;
 }
@@ -698,7 +610,7 @@ interface LauncherOptions {
  *
  * `modules` is an ordered list of tabs; each picks a UI `layout`, optional
  * content `contentTags` (the scope passed as the `tags` filter to
- * `GET /ai/agent/content`), and a translatable `label`.
+ * `GET /content`), and a translatable `label`.
  */
 /** The UI layouts a tab can render with. `chat` is the conversation; the rest render content. */
 type ModuleLayout = "chat" | "home" | "help" | "news";
@@ -982,17 +894,19 @@ interface PageContext {
     [key: string]: string | number | boolean | undefined;
 }
 /**
- * Override the HTTP endpoints the widget calls. Paths are appended to
- * `baseUrl`. Absolute URLs also work (useful when the upload endpoint
- * lives on a different origin like a CDN presign service).
+ * Override the HTTP endpoints the widget calls. `upload` / `transcribe`
+ * paths are appended to the agent base (`${baseUrl}/api/agent`);
+ * `submitForm` is appended to the data base (`dataBaseUrl`). Absolute URLs
+ * also work (useful when the upload endpoint lives on a different origin
+ * like a CDN presign service).
  */
 interface Endpoints {
-    /** File upload endpoint. Default: `'/ai/agent/upload-file'`. */
+    /** File upload endpoint. Default: `'/ai-agent/upload-file'`. */
     upload?: string;
-    /** Voice transcription endpoint. Default: `'/ai/agent/transcribe-audio'`. */
+    /** Voice transcription endpoint. Default: `'/ai-agent/transcribe-audio'`. */
     transcribe?: string;
     /**
-     * Form submission endpoint. Default: `'/ai/agent/submit-form'`. When any form
+     * Form submission endpoint. Default: `'/submit-form'`. When any form
      * (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`
@@ -1024,8 +938,8 @@ interface TrackingOptions {
      */
     enabled?: boolean;
     /**
-     * Pixel collector URL. Default: `https://t.<brand domain>/api/ai-elements/px.gif`
-     * (e.g. `https://t.help.ai/api/ai-elements/px.gif`).
+     * Pixel collector URL. Default: `${dataBaseUrl}/elements/px.gif`
+     * (e.g. `https://help.ai/api/data/elements/px.gif`).
      */
     endpoint?: string;
     /**
@@ -1036,7 +950,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.
      */
@@ -1053,7 +967,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
@@ -1090,8 +1004,33 @@ interface ChatWidgetOptions {
     publicKey?: string;
     /** Deployment ID (UUID). Sent as `x-ai-agent-deployment-id`. */
     aiAgentDeploymentId?: string;
-    /** Backend origin (no trailing slash). Defaults to the brand's default. */
+    /**
+     * MAIN site origin (no trailing slash, e.g. `https://help.ai`). The API
+     * 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}/ai-agent/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`).
+     */
+    dataBaseUrl?: string;
     /** Host-asserted, informational end-user context (untrusted; not auth). */
     userContext?: UserContext;
     /** Host-asserted, informational page/visit context (untrusted; `area`, url, …). */
@@ -1146,6 +1085,10 @@ 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;
     pageContext?: PageContext;
     position: Position;
@@ -1232,13 +1175,19 @@ 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.)
  * 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 /forms`). A stale backend still pushing
+ * `config.forms` is ignored.
  */
 interface ServerConfig {
+    /** Data-API base override — adopted only when the host didn't set one. */
+    dataBaseUrl?: string;
     presentation?: PresentationOptions;
     behavior?: BehaviorOptions;
     theme?: ThemePreference | ThemeOverrides;
@@ -1249,7 +1198,6 @@ interface ServerConfig {
     i18n?: I18nOptions;
     footer?: FooterOptions;
     features?: FeatureFlags;
-    forms?: FormsOptions;
     modules?: ModulesOptions;
     tracking?: TrackingOptions;
     endpoints?: Endpoints;
@@ -1401,18 +1349,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.
      */
@@ -1541,7 +1489,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.
@@ -1557,7 +1505,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;
     /**
@@ -1578,7 +1526,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`,
@@ -1592,7 +1540,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"` /