@helpai/elements 0.12.3 → 0.13.0

package/configurator.mjs

@@ -20,7 +20,7 @@ var localeSchema = z.string().min(1).max(35).describe("BCP-47 locale tag (e.g. `
 var uuid7Schema = z.uuidv7().describe("UUID v7 (RFC 9562) \u2014 the single id format for visitor / session / message / file / content ids.");
 
 // src/schema/widget.ts
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 
 // src/schema/widget/presentation.ts
 import { z as z3 } from "zod";
@@ -228,6 +228,9 @@ var featureFlagsSchema = z7.object({
   ),
   tools: z7.array(toolRefSchema).max(200).optional().describe(
     "Backend tools the assistant may invoke. Bare codes (`'tool:send-money'`) or rich refs (`{ code, config }`)."
+  ),
+  humanInLoop: z7.boolean().default(true).describe(
+    "Render human-in-the-loop tool UI \u2014 the inline ask-input form + approve/reject controls for gated tools. `true` (default) shows them; `false` suppresses the UI (the wire still carries the signals)."
   )
 }).loose().describe("Capability flags \u2014 file upload, voice mode, and the tools the assistant may invoke.").meta({
   examples: [
@@ -401,45 +404,121 @@ var i18nSchema = z13.object({
   ]
 });
 
-// src/schema/widget/modules.ts
+// src/schema/widget/intake.ts
 import { z as z14 } from "zod";
-var moduleLayoutSchema = z14.enum(["chat", "home", "help", "news"]);
-var moduleSchema = z14.object({
-  label: z14.string().min(1).max(40).describe(
+var fieldTypeSchema = z14.enum([
+  "text",
+  "email",
+  "tel",
+  "url",
+  "number",
+  "textarea",
+  "select",
+  "radio",
+  "checkbox",
+  "multiselect"
+]);
+var fieldOptionSchema = z14.object({
+  value: z14.string().min(1).max(200).describe("The value recorded when this choice is picked."),
+  label: z14.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),
+  description: z14.string().max(280).optional().describe("Optional sub-label under the choice.")
+}).loose();
+var fieldValidationSchema = z14.object({
+  pattern: z14.string().max(500).optional().describe("Regex source string \u2014 text-like fields (e.g. `^\\d{5}$`)."),
+  minLength: z14.number().int().min(0).max(1e4).optional(),
+  maxLength: z14.number().int().min(1).max(1e4).optional(),
+  min: z14.number().optional().describe("Minimum \u2014 `number` fields."),
+  max: z14.number().optional().describe("Maximum \u2014 `number` fields."),
+  minSelections: z14.number().int().min(0).max(50).optional().describe("Minimum picks \u2014 `multiselect`."),
+  maxSelections: z14.number().int().min(1).max(50).optional().describe("Maximum picks \u2014 `multiselect`.")
+}).loose();
+var formFieldSchema = z14.object({
+  name: z14.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`). Sent to the agent as captured context."),
+  label: z14.string().min(1).max(200).describe("Visible field label."),
+  type: fieldTypeSchema.describe("Field renderer + built-in validation (`email`/`tel`/`url`/`number` are checked)."),
+  placeholder: z14.string().max(200).optional(),
+  required: z14.boolean().optional().default(true).describe("Must be answered to submit. Set `false` to allow skipping."),
+  defaultValue: z14.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),
+  options: z14.array(fieldOptionSchema).max(50).optional().describe("Choices for `select` / `radio` / `multiselect`."),
+  validation: fieldValidationSchema.optional(),
+  allowOther: z14.boolean().optional().describe("`select`/`radio`/`multiselect` \u2014 allow a free-text 'Other' answer."),
+  validationHint: z14.string().max(280).optional().describe("Small helper line under the field.")
+}).loose();
+var intakeSchema = z14.object({
+  enabled: z14.boolean().default(false).describe("Turn the pre-chat intake gate on. Off by default."),
+  title: z14.string().max(120).optional().describe("Form heading (e.g. 'Before we start')."),
+  description: z14.string().max(500).optional().describe("Sub-heading under the title."),
+  fields: z14.array(formFieldSchema).max(20).default([]).describe("The questions to ask, in order. The gate is only active when there is \u22651 field."),
+  submitLabel: z14.string().max(60).optional().describe("Submit button label (default 'Start chat')."),
+  skippable: z14.boolean().default(false).describe("Show a Skip control to dismiss the whole form.")
+}).loose().describe(
+  "Pre-chat intake form \u2014 a blocking lead/sales-capture gate of typed, validated fields. The same field shape powers the AI ask-input tool. Off by default."
+).meta({
+  examples: [
+    { enabled: false },
+    {
+      enabled: true,
+      title: "Before we start",
+      description: "Tell us who you are so we can help faster.",
+      submitLabel: "Start chat",
+      fields: [
+        { name: "name", label: "Your name", type: "text", required: true },
+        { name: "email", label: "Work email", type: "email", required: true },
+        { name: "phone", label: "Phone", type: "tel", required: false },
+        {
+          name: "topic",
+          label: "What can we help with?",
+          type: "select",
+          required: true,
+          options: [
+            { value: "sales", label: "Talk to sales" },
+            { value: "support", label: "Get support" }
+          ]
+        }
+      ]
+    }
+  ]
+});
+
+// src/schema/widget/modules.ts
+import { z as z15 } from "zod";
+var moduleLayoutSchema = z15.enum(["chat", "home", "help", "news"]);
+var moduleSchema = z15.object({
+  label: z15.string().min(1).max(40).describe(
     "Tab label \u2014 an i18n key (resolved against the i18n strings, e.g. `tabHome`) or a literal. Translations ride `i18n.strings`."
   ),
   layout: moduleLayoutSchema.describe(
     "UI layout that renders this tab: `chat` (the conversation), `home`, `help`, or `news`."
   ),
-  contentTags: z14.array(z14.string().max(60)).max(20).optional().describe(
+  contentTags: z15.array(z15.string().max(60)).max(20).optional().describe(
     "Content tags this tab scopes to \u2014 the `tags` filter on `GET /ai/agent/content` (matches content tagged with ANY of them). Omit for the `chat` layout."
   ),
-  id: z14.string().max(60).optional().describe(
+  id: z15.string().max(60).optional().describe(
     "Stable id for navigation + last-tab persistence. Defaults to the first `contentTags` entry, else `layout`."
   ),
   // ── `home` layout config (flat feature flags — no block authoring) ──────
-  brandName: z14.string().max(80).optional().describe("`home` \u2014 hero wordmark (e.g. your company name)."),
-  showGreeting: z14.boolean().optional().describe("`home` \u2014 show the greeting hero (default true)."),
-  greetingText: z14.string().max(280).optional().describe("`home` \u2014 override the greeting headline (default 'How can we help?'); supports a `{name}` token."),
-  userAvatars: z14.array(
-    z14.object({
-      name: z14.string().min(1).max(80),
-      avatar: z14.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),
-      role: z14.string().max(80).optional()
+  brandName: z15.string().max(80).optional().describe("`home` \u2014 hero wordmark (e.g. your company name)."),
+  showGreeting: z15.boolean().optional().describe("`home` \u2014 show the greeting hero (default true)."),
+  greetingText: z15.string().max(280).optional().describe("`home` \u2014 override the greeting headline (default 'How can we help?'); supports a `{name}` token."),
+  userAvatars: z15.array(
+    z15.object({
+      name: z15.string().min(1).max(80),
+      avatar: z15.string().max(2048).optional().describe("Image URL; falls back to initials of `name`."),
+      role: z15.string().max(80).optional()
     }).loose()
   ).max(10).optional().describe("`home` \u2014 team/agent avatars shown in the hero."),
-  showSearchBar: z14.boolean().optional().describe("`home` \u2014 show the 'Search for help' bar (default true)."),
-  showRecentMessages: z14.boolean().optional().describe("`home` \u2014 show the visitor's most recent conversation card (default true)."),
-  status: z14.object({
-    text: z14.string().min(1).max(120),
-    level: z14.string().max(40).optional().describe(
+  showSearchBar: z15.boolean().optional().describe("`home` \u2014 show the 'Search for help' bar (default true)."),
+  showRecentMessages: z15.boolean().optional().describe("`home` \u2014 show the visitor's most recent conversation card (default true)."),
+  status: z15.object({
+    text: z15.string().min(1).max(120),
+    level: z15.string().max(40).optional().describe(
       "`home` \u2014 status severity, drives the status icon colour. Free text; `operational` (green, default), `degraded` (amber), and `down` (red) are styled, any other value falls back to the operational style."
     ).meta({ examples: ["operational", "degraded", "down"] }),
-    url: z14.string().max(2048).optional().describe("Opens in an in-widget iframe when tapped.")
+    url: z15.string().max(2048).optional().describe("Opens in an in-widget iframe when tapped.")
   }).optional().describe("`home` \u2014 system-status card. Omit to hide."),
-  contentBlockTitle: z14.string().max(80).optional().describe("`home` \u2014 heading for the content list built from `contentTags` (default 'Popular articles').")
+  contentBlockTitle: z15.string().max(80).optional().describe("`home` \u2014 heading for the content list built from `contentTags` (default 'Popular articles').")
 }).loose();
-var modulesSchema = z14.array(moduleSchema).max(4).describe(
+var modulesSchema = z15.array(moduleSchema).max(4).describe(
   "Messenger tabs \u2014 an ordered list of up to 4 tabs, each picking a `layout` + optional content `contentTags` (the content scope) + a translatable `label`. One tab \u2192 no tab bar (just that content); zero \u2192 an empty state. Floating / drawer / modal only."
 ).meta({
   examples: [
@@ -462,23 +541,27 @@ var modulesSchema = z14.array(moduleSchema).max(4).describe(
 });
 
 // src/schema/widget.ts
-var endpointsSchema = z15.object({
-  upload: z15.string().min(1).max(2048).default("/ai/agent/upload-file"),
-  transcribe: z15.string().min(1).max(2048).default("/ai/agent/transcribe-audio")
+var endpointsSchema = z16.object({
+  upload: z16.string().min(1).max(2048).default("/ai/agent/upload-file"),
+  transcribe: z16.string().min(1).max(2048).default("/ai/agent/transcribe-audio"),
+  intake: z16.string().min(1).max(2048).default("/ai/agent/intake").describe(
+    "Pre-chat intake submission endpoint. The widget POSTs the captured lead values here on completion (fire-and-forget), keyed by the same visitorId + sessionId as the conversation. Optional \u2014 a 404 is ignored."
+  )
 }).loose().describe("HTTP endpoint overrides. Paths are appended to baseUrl; absolute URLs are accepted too.").meta({
   examples: [
     { upload: "/ai/agent/upload-file", transcribe: "/ai/agent/transcribe-audio" },
-    { upload: "https://help.ai/uploads/presign" }
+    { upload: "https://help.ai/uploads/presign" },
+    { intake: "https://crm.acme.com/leads/intake" }
   ]
 });
-var userContextSchema = z15.object({
-  id: z15.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
-  email: z15.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
-  name: z15.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
-  plan: z15.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
-  role: z15.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
-  phone: z15.string().min(1).max(40).optional().describe("Phone number (optional).")
-}).catchall(z15.union([z15.string(), z15.number(), z15.boolean()])).describe(
+var userContextSchema = z16.object({
+  id: z16.string().min(1).max(200).optional().describe("Host's stable id for the user \u2014 informational context the agent/backend can key on (not auth)."),
+  email: z16.string().min(1).max(320).optional().describe("User email \u2014 surfaced to the agent for context (optional)."),
+  name: z16.string().min(1).max(200).optional().describe("Display name \u2014 shown in the Home greeting (`{name}`) and conversation transcripts (optional)."),
+  plan: z16.string().min(1).max(120).optional().describe("Subscription / pricing tier, e.g. `pro` (optional)."),
+  role: z16.string().min(1).max(120).optional().describe("The user's role on the host site, e.g. `admin` (optional)."),
+  phone: z16.string().min(1).max(40).optional().describe("Phone number (optional).")
+}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
   "Host-asserted end-user context (informational, untrusted \u2014 not authentication). Recognised `id` / `email` / `name` / `plan` / `role` / `phone` plus any extra custom scalar fields forwarded to the agent."
 ).meta({
   examples: [{ id: "u_123" }, { id: "u_123", email: "alex@acme.com", name: "Alex Lee", plan: "pro" }]
@@ -494,31 +577,31 @@ var PAGE_AREA_SUGGESTIONS = [
   "account",
   "blog"
 ];
-var pageContextSchema = z15.object({
-  area: z15.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
-  url: z15.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
-  path: z15.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
-  title: z15.string().min(1).max(300).optional().describe("Human-readable page title.")
-}).catchall(z15.union([z15.string(), z15.number(), z15.boolean()])).describe(
+var pageContextSchema = z16.object({
+  area: z16.string().min(1).max(64).optional().describe(`Host-defined surface the visitor is on. Free-form; suggested: ${PAGE_AREA_SUGGESTIONS.join(" | ")}.`),
+  url: z16.string().min(1).max(2048).optional().describe("Full page URL. Auto-filled from the host page when omitted."),
+  path: z16.string().min(1).max(2048).optional().describe("Page path, e.g. `/pricing/enterprise`."),
+  title: z16.string().min(1).max(300).optional().describe("Human-readable page title.")
+}).catchall(z16.union([z16.string(), z16.number(), z16.boolean()])).describe(
   "Host-asserted page/visit context (informational, untrusted). Where the visitor is + the surface (`area`) they're using, plus any custom scalar fields, forwarded to the agent."
 ).meta({ examples: [{ area: "pricing", path: "/pricing" }, { area: "help-desk" }] });
-var connectionConfigSchema = z15.object({
-  widgetId: z15.string().min(1).max(80).default("default").describe(
+var connectionConfigSchema = z16.object({
+  widgetId: z16.string().min(1).max(80).default("default").describe(
     "Stable per-instance id used to namespace localStorage keys. Set this when mounting more than one widget on the same page so their conversation state doesn't collide."
   ),
-  publicKey: z15.string().min(1).max(200).optional().describe(
+  publicKey: z16.string().min(1).max(200).optional().describe(
     "Workspace-scoped public key (`agent_pk_\u2026`) issued from the dashboard. Sent on every API call as the `x-public-key` header."
   ),
-  aiAgentDeploymentId: z15.string().min(1).max(200).optional().describe(
+  aiAgentDeploymentId: z16.string().min(1).max(200).optional().describe(
     "Deployment UUID from the dashboard. Picks which agent / settings bundle answers this mount. Sent as `x-ai-agent-deployment-id`."
   ),
-  baseUrl: z15.string().min(1).max(2048).optional().describe(
+  baseUrl: z16.string().min(1).max(2048).optional().describe(
     "Full backend origin (e.g. `https://help.ai/api`). Set this to point at your staging / self-hosted / custom backend. Default: the brand's `defaultBaseUrl` baked at build time."
   ),
   userContext: userContextSchema.optional(),
   pageContext: pageContextSchema.optional(),
   endpoints: endpointsSchema.optional(),
-  debug: z15.union([z15.boolean(), z15.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
+  debug: z16.union([z16.boolean(), z16.enum(["off", "error", "warn", "info", "debug", "trace"])]).optional().describe(
     'Console log verbosity. `false` / `"off"` silences everything (default in production). `true` \u2192 `"debug"`. Levels `error` / `warn` / `info` / `debug` / `trace` gate output additively. Use `"trace"` to capture per-chunk SSE frames + every state transition. Also toggleable at runtime via `chat.setDebug(level)` or `?<brand>-debug=trace` in the page URL \u2014 the URL beats this option, this option beats the persisted `localStorage` value.'
   )
 }).loose().describe(
@@ -538,7 +621,7 @@ var connectionConfigSchema = z15.object({
     }
   ]
 });
-var widgetSettingsSchema = z15.object({
+var widgetSettingsSchema = z16.object({
   presentation: presentationSchema.optional(),
   behavior: behaviorSchema.optional(),
   theme: themeFieldSchema.default("auto").describe("Theme preference (`auto` follows OS) or a tokens override object (`accent`, `radius`, `fontFamily`)."),
@@ -550,9 +633,10 @@ var widgetSettingsSchema = z15.object({
   i18n: i18nSchema.optional(),
   footer: footerSchema.optional(),
   features: featureFlagsSchema.optional(),
+  intake: intakeSchema.optional(),
   modules: modulesSchema.optional()
 }).loose().describe(
-  "Portal-configurable widget settings \u2014 twelve sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-session` under `config`."
+  "Portal-configurable widget settings \u2014 thirteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-session` under `config`."
 ).meta({
   examples: [
     { presentation: { mode: "floating", position: "bottom-right" }, theme: "auto" },
@@ -570,8 +654,8 @@ var widgetSettingsSchema = z15.object({
 });
 var widgetConfigSchema = connectionConfigSchema.extend({
   ...widgetSettingsSchema.shape,
-  site: z15.unknown().optional().describe('Site config \u2014 applies in `mode: "page"`. Comes from the start-session response, not user-edited.'),
-  blocks: z15.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-session response.')
+  site: z16.unknown().optional().describe('Site config \u2014 applies in `mode: "page"`. Comes from the start-session response, not user-edited.'),
+  blocks: z16.unknown().optional().describe('Blocks (nav + link cards) \u2014 applies in `mode: "page"`. Comes from the start-session response.')
 }).describe(
   "Full client widget config \u2014 connection (where + auth) + widget settings (look + behaviour) + page-mode extras. This is what the runtime parses on `mount()` / `init()`. Mode-specific constraints (e.g. `position` only meaningful in `floating`) are NOT enforced here \u2014 the runtime silently ignores irrelevant fields rather than rejecting them so the same object can flow across mode changes."
 ).meta({
@@ -594,49 +678,49 @@ var widgetSettingsPartialSchema = widgetSettingsSchema.partial();
 var connectionConfigPartialSchema = connectionConfigSchema.partial();
 
 // src/schema/deployment.ts
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var serverConfigSchema = widgetSettingsSchema.partial();
-var siteConfigSchema = z16.object({
-  title: z16.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
+var siteConfigSchema = z17.object({
+  title: z17.string().min(1).max(120).optional().describe("Brand / site name. Used as the logo's alt-text fallback."),
   logo: assetSchema.optional().describe("Brand logo shown at the top of the page-mode sidebar."),
   logoDark: assetSchema.optional().describe(
     "Optional dark-theme logo variant. Falls back to `logo` when the active theme is light or `logoDark` is unset."
   )
 }).loose();
-var blocksConfigSchema = z16.object({
-  navigation: z16.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
-  linkCards: z16.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
+var blocksConfigSchema = z17.object({
+  navigation: z17.array(linkSchema).max(100).optional().describe("Sidebar navigation links (vertical list, primary nav)."),
+  linkCards: z17.array(linkSchema).max(100).optional().describe("Sidebar link cards (richer entries with optional `description`).")
 }).loose();
-var handshakeWelcomeMessageSchema = z16.object({
-  id: z16.string(),
-  role: z16.enum(["assistant", "system"]),
-  text: z16.string()
+var handshakeWelcomeMessageSchema = z17.object({
+  id: z17.string(),
+  role: z17.enum(["assistant", "system"]),
+  text: z17.string()
 }).loose();
-var handshakeWelcomeSuggestionSchema = z16.object({
-  id: z16.string(),
-  label: z16.string(),
-  text: z16.string().optional()
+var handshakeWelcomeSuggestionSchema = z17.object({
+  id: z17.string(),
+  label: z17.string(),
+  text: z17.string().optional()
 }).loose();
-var rebindReasonSchema = z16.enum(["conflict", "expired", "invalid"]);
-var startSessionResponseSchema = z16.object({
-  deployment: z16.object({
-    id: z16.string(),
-    name: z16.string(),
+var rebindReasonSchema = z17.enum(["conflict", "expired", "invalid"]);
+var startSessionResponseSchema = z17.object({
+  deployment: z17.object({
+    id: z17.string(),
+    name: z17.string(),
     // Page URL identifier — present on every deployment; unique per host.
     // Used to mount page deployments via `?slug=…`.
-    slug: z16.string().optional(),
-    publicKey: z16.string().optional()
+    slug: z17.string().optional(),
+    publicKey: z17.string().optional()
     // Deliberately no `type` / `channel` here. Deployment-level
     // taxonomy is a backend categorization concern — the widget's
     // rendering choice flows from `widget.presentation.mode`, not
     // the deployment record's category. `.loose()` lets any such
     // backend field pass through without typing.
   }).loose(),
-  agent: z16.object({
-    id: z16.string(),
-    name: z16.string(),
-    title: z16.string().optional(),
-    status: z16.enum(["online", "away", "offline"]).optional()
+  agent: z17.object({
+    id: z17.string(),
+    name: z17.string(),
+    title: z17.string().optional(),
+    status: z17.enum(["online", "away", "offline"]).optional()
   }).loose(),
   /**
    * Deployment-wide widget configuration the dashboard admin saved
@@ -646,25 +730,25 @@ var startSessionResponseSchema = z16.object({
   config: serverConfigSchema.optional(),
   site: siteConfigSchema.optional(),
   blocks: blocksConfigSchema.optional(),
-  welcome: z16.object({
-    messages: z16.array(handshakeWelcomeMessageSchema).optional(),
-    suggestions: z16.array(handshakeWelcomeSuggestionSchema).optional()
+  welcome: z17.object({
+    messages: z17.array(handshakeWelcomeMessageSchema).optional(),
+    suggestions: z17.array(handshakeWelcomeSuggestionSchema).optional()
   }).loose().optional(),
-  visitorId: z16.string(),
-  sessionId: z16.string(),
-  canContinue: z16.boolean(),
-  messages: z16.array(z16.unknown()),
+  visitorId: z17.string(),
+  sessionId: z17.string(),
+  canContinue: z17.boolean(),
+  messages: z17.array(z17.unknown()),
   /**
    * Per-visitor preferences (locale picker, theme picker, sound
    * mute, dragged panel size). Distinct from `config` — this is
    * what THIS visitor toggled inside the widget, not the
    * deployment's admin-set defaults.
    */
-  userPrefs: z16.record(z16.string(), z16.unknown()).optional(),
+  userPrefs: z17.record(z17.string(), z17.unknown()).optional(),
   // Present only when the server rotated the request `visitorId` /
   // `sessionId`. Purely advisory — client must adopt the response ids
   // verbatim regardless of whether this block is present.
-  rebind: z16.object({
+  rebind: z17.object({
     visitorId: rebindReasonSchema.optional(),
     sessionId: rebindReasonSchema.optional()
   }).loose().optional()
@@ -674,7 +758,7 @@ var startSessionResponseSchema = z16.object({
 import "zod";
 
 // src/schema/json-schema.ts
-import { z as z18 } from "zod";
+import { z as z19 } from "zod";
 
 // src/configurator/field-help.tsx
 import { createPortal } from "preact/compat";