@helpai/elements 0.13.0 → 0.14.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 StartSessionResponse, W as WidgetConfig, d as WidgetConfigPartial, e as WidgetSettings, f as WidgetSettingsPartial } from './deployment-BJD1aESw.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-Rtrqo8-b.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" | "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";
+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";
 /** A partial map for one locale — what overrides look like on the wire. */
 type LocaleStrings = Partial<Record<StringKey, string>>;
 /**
@@ -454,18 +454,20 @@ interface FeedbackOptions {
 }
 
 /**
- * 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.
+ * Event-driven forms engine — framework-free runtime types (mirror of
+ * `src/schema/widget/forms.ts`). The IIFE path has no Zod, so these plain
+ * interfaces are what the resolver, controller, and form UI 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 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.
+ *
+ * The same {@link FormField} shape powers the AI-driven ask-input tool.
  */
 /** A renderable field type. `multiselect` collects an array of values. */
-type FieldType = "text" | "email" | "tel" | "url" | "number" | "textarea" | "select" | "radio" | "checkbox" | "multiselect";
+type FieldType = "text" | "email" | "tel" | "url" | "number" | "date" | "time" | "textarea" | "select" | "radio" | "checkbox" | "multiselect";
 /** One choice for `select` / `radio` / `multiselect` fields. */
 interface FieldOption {
     value: string;
@@ -486,7 +488,7 @@ interface FieldValidation {
     minSelections?: number;
     maxSelections?: number;
 }
-/** One field in a form (intake or ask-input). */
+/** One field in a form. */
 interface FormField {
     /** Stable key the value is recorded under (e.g. `email`). */
     name: string;
@@ -505,29 +507,79 @@ interface FormField {
     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.
+ * Trigger that surfaces a form. Terse string with an optional `:param` so it's
+ * serializable + server-pushable. `after-messages:3`, `idle:30`,
+ * `page-area:pricing`.
  */
-interface IntakeOptions {
-    enabled?: boolean;
+type FormTrigger = "pre-chat" | `after-messages:${number}` | "conversation-closed" | "panel-close" | `idle:${number}` | `page-area:${string}` | "manual";
+/** The trigger kinds, parsed out from the {@link FormTrigger} string. */
+type TriggerKind = "pre-chat" | "after-messages" | "conversation-closed" | "panel-close" | "idle" | "page-area" | "manual";
+/** A {@link FormTrigger} parsed into kind + optional param. */
+interface ParsedTrigger {
+    kind: TriggerKind;
+    /** Numeric for `after-messages` / `idle`; string area for `page-area`. */
+    param?: number | string;
+}
+/**
+ * Extra eligibility predicate, evaluated when a trigger fires. Small and
+ * declarative on purpose — richer routing belongs to the agent / backend.
+ */
+interface FormCondition {
+    /** Only show if `userContext` lacks ALL of these keys (progressive profiling). */
+    missingContext?: string[];
+    /** Only on these page areas (`pageContext.area`). */
+    pageArea?: string | string[];
+    minMessages?: number;
+    maxMessages?: number;
+}
+/** How often a form may show. */
+type FormFrequency = "once" | "session" | "always";
+/** One form as authored in config (raw input). */
+interface FormDef {
+    /** Stable id — persistence dedupe + `manual` `openForm(id)`. */
+    id: string;
+    on: FormTrigger | FormTrigger[];
+    when?: FormCondition;
+    fields: FormField[];
     title?: string;
     description?: string;
-    fields?: FormField[];
     submitLabel?: string;
-    /** Allow dismissing the whole form without answering. Default `false`. */
     skippable?: boolean;
+    /** Gate the composer. Honored only for `pre-chat` / `after-messages`. */
+    blocking?: boolean;
+    /** Default `once`. */
+    frequency?: FormFrequency;
+    /**
+     * Mirror the submitted answers into `userContext` so they ride every
+     * subsequent request (the agent sees them in-conversation). Default `true`.
+     * Set `false` for PII (DOB, policy #, symptoms) — those then go ONLY to the
+     * submit endpoint, never onto the always-on context envelope.
+     */
+    mirrorToContext?: boolean;
 }
-/** Fully-resolved intake config exposed on {@link ResolvedOptions}. */
-interface ResolvedIntake {
-    /** Effective only when there is at least one valid field. */
-    enabled: boolean;
+/** The `forms` block is an ordered list (max 20); order = priority. */
+type FormsOptions = FormDef[];
+/** A fully-resolved form exposed on {@link ResolvedOptions}. */
+interface ResolvedForm {
+    id: string;
+    triggers: ParsedTrigger[];
+    when?: FormCondition;
+    fields: FormField[];
     title?: string;
     description?: string;
-    fields: FormField[];
     submitLabel?: string;
     skippable: boolean;
+    blocking: boolean;
+    frequency: FormFrequency;
+    /** Mirror answers into `userContext` (false → PII, endpoint only). */
+    mirrorToContext: boolean;
+}
+/** Fully-resolved forms block: ordered list + an event→forms index. */
+interface ResolvedForms {
+    /** Forms in declared order (= priority). */
+    list: ResolvedForm[];
+    /** Forms keyed by trigger kind, for fast event lookup. */
+    byTrigger: Partial<Record<TriggerKind, ResolvedForm[]>>;
 }
 
 /**
@@ -900,13 +952,14 @@ interface Endpoints {
     /** 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.
+     * 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`
+     * so the backend can route. Optional: a backend that doesn't implement it just
+     * 404s and the submission is ignored.
      */
-    intake?: string;
+    submitForm?: string;
 }
 
 /**
@@ -977,8 +1030,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;
+    /** Event-driven forms (lead capture, CSAT, intake, consent…). Server-pushable. */
+    forms?: FormsOptions;
     /** Messenger modules (Chat / Home / Messages / Help / News tabs). Server-pushable. */
     modules?: ModulesOptions;
     /**
@@ -1026,8 +1079,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;
+    /** Resolved event-driven forms — ordered list + trigger index. */
+    forms: ResolvedForms;
     endpoints: Required<Endpoints>;
     attachments: Required<Pick<AttachmentLimits, "maxBytes" | "maxCount">> & {
         accept: string;
@@ -1105,7 +1158,7 @@ interface ServerConfig {
     i18n?: I18nOptions;
     footer?: FooterOptions;
     features?: FeatureFlags;
-    intake?: IntakeOptions;
+    forms?: FormsOptions;
     modules?: ModulesOptions;
     endpoints?: Endpoints;
 }
@@ -1205,8 +1258,12 @@ interface EventMap {
     toggleHistory: {
         view: "chat" | "history";
     };
-    /** Pre-chat intake form completed (or skipped → empty values). */
-    intakeSubmit: Record<string, string>;
+    /** A form (intake, CSAT, …) was completed or skipped. */
+    formSubmit: {
+        formId: string;
+        values: Record<string, string>;
+        skipped: boolean;
+    };
     /** User answered an ask-input tool request (re-POST follows). */
     toolResult: {
         toolCallId: string;
@@ -1396,6 +1453,12 @@ interface ChatWidgetInstance {
      * URL is empty.
      */
     popOut: () => void;
+    /**
+     * Surface a configured form by id (a form with a `manual` trigger). Lets the
+     * host open, say, an appointment or feedback form from its own button. No-op
+     * if no form with that id + a `manual` trigger exists.
+     */
+    openForm: (id: string) => void;
     /**
      * Subscribe to a lifecycle event. Returns an `off` function. See
      * {@link EventMap} for the full set + payload shapes — currently