@helpai/elements 0.12.3 → 0.13.1

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-BUakRA3-.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 StartSessionResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-Big98MYV.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" | "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" | "intakeSubmit" | "intakeSkip" | "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>>;
 /**
@@ -111,6 +111,24 @@ interface UserPrefs {
     themeMode?: "auto" | "light" | "dark";
 }
 
+/**
+ * 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;
@@ -141,6 +159,22 @@ type WirePart = {
     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 SessionAgent {
@@ -334,6 +368,12 @@ interface FeatureFlags {
      * format always uses the rich shape.
      */
     tools?: Array<string | ToolRef>;
+    /**
+     * Render human-in-the-loop tool UI — the inline ask-input form and the
+     * approve/reject controls for gated tools. Default `true`. Set `false` to
+     * suppress them (the wire still carries the signals; they just won't show).
+     */
+    humanInLoop?: boolean;
 }
 /**
  * Client-side attachment limits. Server enforcement is still required —
@@ -413,6 +453,83 @@ interface FeedbackOptions {
     haptics?: HapticsOptions;
 }
 
+/**
+ * Intake form + shared form-field runtime config types — framework-free
+ * mirror of `src/schema/widget/intake.ts`. The IIFE runtime path has no
+ * Zod, so these plain interfaces are what the resolver + form engine consume.
+ *
+ * The same {@link FormField} shape powers two surfaces:
+ *   1. the deterministic pre-chat **intake** gate (this section), and
+ *   2. the AI-driven **ask-input tool** (`src/ui/tool-ask-input.tsx`), which
+ *      maps a wire ask-input request onto `FormField[]` and reuses the same
+ *      `<DynamicForm>` renderer.
+ */
+/** A renderable field type. `multiselect` collects an array of values. */
+type FieldType = "text" | "email" | "tel" | "url" | "number" | "textarea" | "select" | "radio" | "checkbox" | "multiselect";
+/** One choice for `select` / `radio` / `multiselect` fields. */
+interface FieldOption {
+    value: string;
+    /** Display text; falls back to `value`. */
+    label?: string;
+    description?: string;
+}
+/** Validation constraints applied client-side (the backend still validates). */
+interface FieldValidation {
+    /** Regex source string (anchored as written) — text-like fields. */
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+    /** Numeric range — `number` fields. */
+    min?: number;
+    max?: number;
+    /** Selection-count bounds — `multiselect` fields. */
+    minSelections?: number;
+    maxSelections?: number;
+}
+/** One field in a form (intake or ask-input). */
+interface FormField {
+    /** Stable key the value is recorded under (e.g. `email`). */
+    name: string;
+    label: string;
+    type: FieldType;
+    placeholder?: string;
+    required?: boolean;
+    /** Pre-filled value (string for scalars; comma-joined for `multiselect`). */
+    defaultValue?: string;
+    /** Choices for `select` / `radio` / `multiselect`. */
+    options?: FieldOption[];
+    validation?: FieldValidation;
+    /** `select`/`radio`/`multiselect` — allow a free-text "Other" answer. */
+    allowOther?: boolean;
+    /** Small helper line under the field. */
+    validationHint?: string;
+}
+/**
+ * Section: pre-chat intake form. A **blocking gate** — when `enabled` and not
+ * yet completed, the user must submit (or skip, if `skippable`) before the
+ * composer unlocks. Captured values are persisted per-device and attached to
+ * the first request. Off by default — existing deployments are unchanged.
+ */
+interface IntakeOptions {
+    enabled?: boolean;
+    title?: string;
+    description?: string;
+    fields?: FormField[];
+    submitLabel?: string;
+    /** Allow dismissing the whole form without answering. Default `false`. */
+    skippable?: boolean;
+}
+/** Fully-resolved intake config exposed on {@link ResolvedOptions}. */
+interface ResolvedIntake {
+    /** Effective only when there is at least one valid field. */
+    enabled: boolean;
+    title?: string;
+    description?: string;
+    fields: FormField[];
+    submitLabel?: string;
+    skippable: boolean;
+}
+
 /**
  * Launcher (floating-mode FAB) + the pre-engagement callout bubble.
  * Inputs are option-bag shaped; the resolved variant lives in `widget.ts`.
@@ -782,6 +899,14 @@ interface Endpoints {
     upload?: string;
     /** Voice transcription endpoint. Default: `'/ai/agent/transcribe-audio'`. */
     transcribe?: string;
+    /**
+     * Pre-chat intake submission endpoint. Default: `'/ai/agent/intake'`. When the
+     * intake gate is completed, the widget POSTs the captured values here
+     * (fire-and-forget) so the lead is recorded immediately — keyed by the same
+     * `visitorId` + `sessionId` the conversation will use. Optional: a backend
+     * that doesn't implement it just 404s and the submission is ignored.
+     */
+    intake?: string;
 }
 
 /**
@@ -852,6 +977,8 @@ interface ChatWidgetOptions {
     footer?: FooterOptions;
     /** Capability flags (file upload, voice mode, tools). Server-pushable. */
     features?: FeatureFlags;
+    /** Pre-chat intake form (lead/sales capture). Blocking gate. Server-pushable. */
+    intake?: IntakeOptions;
     /** Messenger modules (Chat / Home / Messages / Help / News tabs). Server-pushable. */
     modules?: ModulesOptions;
     /**
@@ -899,6 +1026,8 @@ interface ResolvedOptions {
     features: Required<Omit<FeatureFlags, "tools">> & {
         tools?: Array<string | ToolRef>;
     };
+    /** Resolved pre-chat intake form — `enabled` only when it has ≥1 valid field. */
+    intake: ResolvedIntake;
     endpoints: Required<Endpoints>;
     attachments: Required<Pick<AttachmentLimits, "maxBytes" | "maxCount">> & {
         accept: string;
@@ -976,6 +1105,7 @@ interface ServerConfig {
     i18n?: I18nOptions;
     footer?: FooterOptions;
     features?: FeatureFlags;
+    intake?: IntakeOptions;
     modules?: ModulesOptions;
     endpoints?: Endpoints;
 }
@@ -1075,6 +1205,17 @@ interface EventMap {
     toggleHistory: {
         view: "chat" | "history";
     };
+    /** Pre-chat intake form completed (or skipped → empty values). */
+    intakeSubmit: Record<string, string>;
+    /** User answered an ask-input tool request (re-POST follows). */
+    toolResult: {
+        toolCallId: string;
+    };
+    /** User approved / rejected a gated tool call (re-POST follows). */
+    toolDecision: {
+        toolCallId: string;
+        approved: boolean;
+    };
     /** Files attached (drag-drop, file picker, paste). */
     attach: {
         count: number;