@helpai/elements 0.13.0 → 0.14.0

package/configurator.mjs

@@ -377,108 +377,144 @@ var footerSchema = z12.object({
   ]
 });
 
-// src/schema/widget/i18n.ts
+// src/schema/widget/forms.ts
 import { z as z13 } from "zod";
-var localeStringsSchema = z13.record(z13.string(), z13.string());
-var stringsOverrideSchema = z13.union([localeStringsSchema, z13.record(localeSchema, localeStringsSchema)]).describe(
-  "Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial \u2014 missing keys fall through to built-in defaults."
-).meta({
-  examples: [
-    { send: "Click", stop: "Halt", composerPlaceholder: "Type your question\u2026" },
-    {
-      en: { send: "Send", composerPlaceholder: "Type a message\u2026" },
-      fr: { send: "Envoyer", composerPlaceholder: "Tapez un message\u2026" }
-    }
-  ]
-});
-var i18nSchema = z13.object({
-  locale: localeSchema.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),
-  defaultLocale: z13.union([z13.literal("auto"), localeSchema]).default("auto").describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),
-  availableLocales: z13.array(localeSchema).max(200).optional().describe("BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries."),
-  strings: stringsOverrideSchema.optional()
-}).loose().describe("Locale + i18n overrides.").meta({
-  examples: [
-    { defaultLocale: "auto" },
-    { defaultLocale: "en", availableLocales: ["en", "fr", "de"] },
-    { locale: "fr-CA", strings: { send: "Envoyer" } }
-  ]
-});
-
-// src/schema/widget/intake.ts
-import { z as z14 } from "zod";
-var fieldTypeSchema = z14.enum([
+var fieldTypeSchema = z13.enum([
   "text",
   "email",
   "tel",
   "url",
   "number",
+  "date",
+  "time",
   "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.")
+var fieldOptionSchema = z13.object({
+  value: z13.string().min(1).max(200).describe("The value recorded when this choice is picked."),
+  label: z13.string().min(1).max(200).optional().describe("Display text; falls back to `value`."),
+  description: z13.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`.")
+var fieldValidationSchema = z13.object({
+  pattern: z13.string().max(500).optional().describe("Regex source string \u2014 text-like fields (e.g. `^\\d{5}$`)."),
+  minLength: z13.number().int().min(0).max(1e4).optional(),
+  maxLength: z13.number().int().min(1).max(1e4).optional(),
+  min: z13.number().optional().describe("Minimum \u2014 `number` fields."),
+  max: z13.number().optional().describe("Maximum \u2014 `number` fields."),
+  minSelections: z13.number().int().min(0).max(50).optional().describe("Minimum picks \u2014 `multiselect`."),
+  maxSelections: z13.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`."),
+var formFieldSchema = z13.object({
+  name: z13.string().min(1).max(80).describe("Stable key the answer is recorded under (e.g. `email`)."),
+  label: z13.string().min(1).max(200).describe("Visible field label."),
+  type: fieldTypeSchema.describe("Field renderer + built-in validation (email/tel/url/number/date/time checked)."),
+  placeholder: z13.string().max(200).optional(),
+  required: z13.boolean().optional().default(true).describe("Must be answered to submit. `false` allows skipping."),
+  defaultValue: z13.string().max(2e3).optional().describe("Pre-filled value (comma-join for `multiselect`)."),
+  options: z13.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.")
+  allowOther: z13.boolean().optional().describe("`select`/`radio`/`multiselect` \u2014 allow a free-text 'Other' answer."),
+  validationHint: z13.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."
+var formTriggerSchema = z13.string().regex(
+  /^(pre-chat|conversation-closed|panel-close|manual|after-messages:\d+|idle:\d+|page-area:.+)$/,
+  "Unrecognised form trigger"
+).describe(
+  "When the form fires: `pre-chat`, `after-messages:N`, `conversation-closed`, `panel-close`, `idle:Nseconds`, `page-area:<area>`, or `manual`."
+);
+var formConditionSchema = z13.object({
+  missingContext: z13.array(z13.string().max(80)).max(20).optional().describe("Only show if `userContext` lacks ALL of these keys (progressive profiling)."),
+  pageArea: z13.union([z13.string().max(64), z13.array(z13.string().max(64)).max(20)]).optional().describe("Only on these `pageContext.area` values."),
+  minMessages: z13.number().int().min(0).max(1e3).optional(),
+  maxMessages: z13.number().int().min(0).max(1e3).optional()
+}).loose();
+var formDefSchema = z13.object({
+  id: z13.string().min(1).max(80).describe("Stable id \u2014 persistence dedupe + `manual` openForm(id)."),
+  on: z13.union([formTriggerSchema, z13.array(formTriggerSchema).min(1).max(8)]).describe("Trigger(s) that surface this form."),
+  when: formConditionSchema.optional().describe("Extra eligibility predicate evaluated when a trigger fires."),
+  fields: z13.array(formFieldSchema).max(20).default([]).describe("The questions, in order. \u22651 required to show."),
+  title: z13.string().max(120).optional(),
+  description: z13.string().max(500).optional(),
+  submitLabel: z13.string().max(60).optional(),
+  skippable: z13.boolean().default(false).describe("Show a Skip control."),
+  blocking: z13.boolean().default(false).describe("Gate the composer (honored only for `pre-chat` / `after-messages`); otherwise renders inline."),
+  frequency: z13.enum(["once", "session", "always"]).default("once").describe("`once` (persisted per-device), `session`, or `always`."),
+  mirrorToContext: z13.boolean().default(true).describe(
+    "Mirror the answers into `userContext` so they ride every request. Set `false` for PII (DOB, policy #, symptoms) \u2014 those then go only to the submit endpoint."
+  )
+}).loose();
+var formsSchema = z13.array(formDefSchema).max(20).describe(
+  "Event-driven forms \u2014 an ordered list (order = priority). Each binds to trigger event(s), shows blocking or inline, dedupes by frequency, and records via `endpoints.forms`. Generic across verticals."
 ).meta({
   examples: [
-    { enabled: false },
+    [{ id: "intake", on: "pre-chat", blocking: true, fields: [{ name: "email", label: "Email", type: "email" }] }],
+    [
+      {
+        id: "lead",
+        on: "pre-chat",
+        blocking: true,
+        title: "Before we start",
+        fields: [
+          { name: "name", label: "Your name", type: "text" },
+          { name: "email", label: "Work email", type: "email" }
+        ]
+      },
+      {
+        id: "csat",
+        on: "conversation-closed",
+        frequency: "always",
+        fields: [
+          { name: "rating", label: "How did we do?", type: "radio", options: [{ value: "good" }, { value: "bad" }] }
+        ]
+      },
+      {
+        id: "appointment",
+        on: ["page-area:booking", "manual"],
+        mirrorToContext: false,
+        fields: [
+          {
+            name: "department",
+            label: "Department",
+            type: "select",
+            options: [{ value: "dermatology" }, { value: "cardiology" }]
+          },
+          { name: "date", label: "Preferred date", type: "date" },
+          { name: "consent", label: "I consent to be contacted", type: "checkbox" }
+        ]
+      }
+    ]
+  ]
+});
+
+// src/schema/widget/i18n.ts
+import { z as z14 } from "zod";
+var localeStringsSchema = z14.record(z14.string(), z14.string());
+var stringsOverrideSchema = z14.union([localeStringsSchema, z14.record(localeSchema, localeStringsSchema)]).describe(
+  "Per-instance UI string overrides. Flat = active-locale only; nested = multi-locale map. Both forms are partial \u2014 missing keys fall through to built-in defaults."
+).meta({
+  examples: [
+    { send: "Click", stop: "Halt", composerPlaceholder: "Type your question\u2026" },
     {
-      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" }
-          ]
-        }
-      ]
+      en: { send: "Send", composerPlaceholder: "Type a message\u2026" },
+      fr: { send: "Envoyer", composerPlaceholder: "Tapez un message\u2026" }
     }
   ]
 });
+var i18nSchema = z14.object({
+  locale: localeSchema.optional().describe("BCP-47 locale tag forced for this widget instance (e.g. `fr-CA`). Page-owner explicit override."),
+  defaultLocale: z14.union([z14.literal("auto"), localeSchema]).default("auto").describe("Initial / fallback locale for users who haven't picked one. `auto` sniffs `navigator.language`."),
+  availableLocales: z14.array(localeSchema).max(200).optional().describe("BCP-47 locale tags shown in the runtime language switcher. Hidden when fewer than 2 entries."),
+  strings: stringsOverrideSchema.optional()
+}).loose().describe("Locale + i18n overrides.").meta({
+  examples: [
+    { defaultLocale: "auto" },
+    { defaultLocale: "en", availableLocales: ["en", "fr", "de"] },
+    { locale: "fr-CA", strings: { send: "Envoyer" } }
+  ]
+});
 
 // src/schema/widget/modules.ts
 import { z as z15 } from "zod";
@@ -544,14 +580,14 @@ var modulesSchema = z15.array(moduleSchema).max(4).describe(
 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."
+  submitForm: z16.string().min(1).max(2048).default("/ai/agent/submit-form").describe(
+    "Form submission endpoint. The widget POSTs each completed form's values here (fire-and-forget), keyed by the same visitorId + sessionId as the conversation; the payload carries `formId` + `trigger` so the backend can route. 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" },
-    { intake: "https://crm.acme.com/leads/intake" }
+    { submitForm: "https://crm.acme.com/leads" }
   ]
 });
 var userContextSchema = z16.object({
@@ -633,7 +669,7 @@ var widgetSettingsSchema = z16.object({
   i18n: i18nSchema.optional(),
   footer: footerSchema.optional(),
   features: featureFlagsSchema.optional(),
-  intake: intakeSchema.optional(),
+  forms: formsSchema.optional(),
   modules: modulesSchema.optional()
 }).loose().describe(
   "Portal-configurable widget settings \u2014 thirteen sections, one per dashboard tab. The backend pushes this same shape on `/ai/agent/start-session` under `config`."