@oshara/voice-sdk 0.1.0

package/src/core/forms.ts

@@ -0,0 +1,861 @@
+/**
+ * Agent-driven form support for the chat widget.
+ *
+ * The voice agent can prompt the visitor to fill a structured form (book a
+ * demo, table reservation, lead capture, etc.) by publishing a LiveKit data
+ * message. The widget listens on `RoomEvent.DataReceived`, matches the message
+ * against a registered form definition, prefills any draft fields, and opens
+ * a review screen so the user can confirm and submit.
+ *
+ * Form definitions are generic — `book-demo` ships as the default, but
+ * additional forms (reservation, support ticket, lead capture, etc.) can be
+ * added either by extending DEFAULT_FORM_DEFINITIONS below or by sending them
+ * from the backend through the appearance config (`appearance.forms`).
+ *
+ * ---------------------------------------------------------------------------
+ * Agent → widget protocol (LiveKit data message payload, UTF-8 JSON):
+ *
+ *   1. Topic-based match (preferred):
+ *        topic: "form.book-demo" | "book-demo.form" | "book-demo.review"
+ *        payload: { ...draft fields }
+ *
+ *   2. Form-id field:
+ *        payload: { form_id: "reservation", ...draft fields }
+ *
+ *   3. Event-type field (back-compat with the help-desk-call payload shape):
+ *        payload: { type: "book_demo_form", form: { ...draft fields } }
+ *
+ * Draft fields can live at the payload root or nested under `form`/`payload`/
+ * `data`/`fields`/`values` — extractFormDraft() looks in all of them.
+ */
+
+export type FormFieldType =
+  | "text"
+  | "email"
+  | "tel"
+  | "textarea"
+  | "select"
+  | "number"
+  | "date"
+  | "time"
+  | "checkbox"
+  | "radio"
+  | "display";
+
+/** Option for select/radio/checkbox-group. A plain string is shorthand for { value, label }. */
+export type FormFieldOption = string | { value: string; label?: string };
+
+export interface FormFieldDef {
+  /** Field key — sent in the POST body and matched against incoming drafts.
+   *  Not required for `display` blocks (which render no input). */
+  name?: string;
+  label: string;
+  type: FormFieldType;
+  placeholder?: string;
+  required?: boolean;
+  /** Options for select/radio/checkbox-group. */
+  options?: FormFieldOption[];
+  /** Row count for `type: "textarea"`. */
+  rows?: number;
+  /** Optional default applied when the form is opened with no draft value. */
+  default_value?: string;
+  /** Helper text rendered beneath the input (or as the body of a `display` block). */
+  help_text?: string;
+  /** Optional regex (string form) to validate text-like fields on submit. */
+  pattern?: string;
+  /** Min/max for `type: "number"` (or min/max length for text — not enforced in v1). */
+  min?: number;
+  max?: number;
+  /** Layout width when the form's `field_layout: "grid"`. "full" (default) or "half". */
+  width?: "full" | "half";
+}
+
+export interface FormStep {
+  id: string;
+  title?: string;
+  subtitle?: string;
+  fields: FormFieldDef[];
+  next_label?: string;
+  back_label?: string;
+}
+
+export interface FormLayout {
+  field_layout?: "stack" | "grid";
+  density?: "comfortable" | "compact";
+  label_position?: "top" | "inline";
+}
+
+export interface FormDefinition {
+  /** Stable identifier — used to match topics, event types, and form_id. */
+  id: string;
+  title: string;
+  subtitle?: string;
+  /** Single-page fields. Ignored when `steps` is set. */
+  fields: FormFieldDef[];
+  /** When set, the form renders as a stepper wizard. */
+  steps?: FormStep[];
+  /** Form-level layout knobs. */
+  layout?: FormLayout;
+  /** When true, the auto-derived agent tool is skipped (form is hidden from the LLM). */
+  disabled?: boolean;
+  /**
+   * Where to POST the form on submit. Absolute URL (starts with http) is
+   * used as-is; otherwise treated as a path joined onto BootConfig.apiUrl.
+   * When null, the platform stores the response in managed storage.
+   */
+  submit_url: string | null;
+  submit_method?: "POST" | "PUT" | "PATCH";
+  submit_label?: string;
+  success_message?: string;
+  /** Extra LiveKit topics to match against (in addition to the id-based ones). */
+  topics?: string[];
+  /** Extra event-type aliases to match (e.g. legacy "book_demo_form"). */
+  event_types?: string[];
+  /**
+   * LiveKit topic used when echoing the confirmation back to the agent.
+   * Defaults to "voice.user_text".
+   */
+  confirmation_topic?: string;
+  /**
+   * `type` field on the confirmation payload sent back to the agent.
+   * Defaults to `<id>_submitted`.
+   */
+  confirmation_type?: string;
+}
+
+export interface FormSession {
+  definition: FormDefinition;
+  values: Record<string, string>;
+}
+
+/**
+ * Minimal surface a form controller must expose so the agent can drive it
+ * via data-channel messages (step / submit / close). The widget's
+ * `createFormController` returns an object that satisfies this shape; we
+ * keep the type narrow so the dispatcher below can't accidentally reach
+ * into internals.
+ */
+export interface FormActionTarget {
+  current: () => string | null;
+  step: (direction: "next" | "back" | number) => void;
+  submit: () => void;
+  close: () => void;
+}
+
+/**
+ * Snapshot of the open form that the widget publishes back to the agent on
+ * every meaningful change (field edit, step move, open, close). Lives on
+ * the `form.state` LiveKit topic.
+ */
+/** Compact field descriptor sent to the agent so it can build accurate,
+ *  enum-constrained voice-fill tools for forms that aren't defined in the
+ *  session token (appearance.forms). Mirrors the subset of FormFieldDef the
+ *  agent's _field_to_json_schema needs. */
+export interface FormFieldSchema {
+  name: string;
+  label: string;
+  type: FormFieldType;
+  required: boolean;
+  /** Zero-based step this field lives on (0 for single-page forms). Lets the
+   *  agent guide the visitor through a stepper one step at a time. */
+  step: number;
+  options?: { value: string; label: string }[];
+  /** Validation rules mirrored so the agent can reject malformed input in its
+   *  submit guard — before claiming success — exactly like the widget does. */
+  pattern?: string;
+  min?: number;
+  max?: number;
+}
+
+export interface FormStateSnapshot {
+  type: "form_state";
+  form_id: string;
+  is_open: boolean;
+  step_index: number;
+  total_steps: number;
+  values: Record<string, string>;
+  /** Schema of the form's input fields, so the agent can register
+   *  enum-aware render tools even without appearance.forms in the token. */
+  fields: FormFieldSchema[];
+}
+
+/** Build the compact field schema the agent needs to construct voice-fill
+ *  tools (enum values for select/radio/checkbox, types for the rest) and to
+ *  guide the visitor through a multi-step form one step at a time. */
+export function buildFieldSchema(
+  definition: FormDefinition,
+): FormFieldSchema[] {
+  const toSchema = (f: FormFieldDef, step: number): FormFieldSchema => {
+    const entry: FormFieldSchema = {
+      name: f.name!,
+      label: f.label,
+      type: f.type,
+      required: Boolean(f.required),
+      step,
+    };
+    if (f.options?.length) {
+      entry.options = f.options.map((opt) =>
+        typeof opt === "string"
+          ? { value: opt, label: opt }
+          : { value: opt.value, label: opt.label ?? opt.value },
+      );
+    }
+    if (f.pattern) entry.pattern = f.pattern;
+    if (f.min !== undefined) entry.min = f.min;
+    if (f.max !== undefined) entry.max = f.max;
+    return entry;
+  };
+
+  if (definition.steps?.length) {
+    const out: FormFieldSchema[] = [];
+    definition.steps.forEach((s, idx) => {
+      for (const f of s.fields) {
+        if (f.type !== "display" && f.name) out.push(toSchema(f, idx));
+      }
+    });
+    return out;
+  }
+  return collectInputFields(definition).map((f) => toSchema(f, 0));
+}
+
+/**
+ * Topic pattern the agent uses to drive form actions: `form.{id}.action`.
+ * Payload carries `{type: "form_step"|"form_submit"|"form_close", form_id,
+ * direction?, step_index?}`.
+ *
+ * Returns true if the message was a form-action and was dispatched (so the
+ * caller can short-circuit further matching), false otherwise.
+ */
+export function handleFormAction(
+  topic: string | undefined,
+  value: unknown,
+  target: FormActionTarget,
+): boolean {
+  if (!topic) return false;
+  const normalized = topic.trim().toLowerCase();
+  // Expect "form.<id>.action".
+  if (!normalized.startsWith("form.") || !normalized.endsWith(".action")) {
+    return false;
+  }
+  const formId = normalized.slice("form.".length, -".action".length);
+  if (!formId) return false;
+  if (!value || typeof value !== "object") return false;
+  const payload = value as Record<string, unknown>;
+
+  // Guard: action must target the currently-open form. We don't want a
+  // stale event from a prior form to drive whatever the user opened next.
+  const openId = target.current();
+  if (!openId || openId.trim().toLowerCase() !== formId) return false;
+
+  // Match by payload.form_id when present (belt + suspenders).
+  const payloadFormId = stringField(payload.form_id);
+  if (payloadFormId && payloadFormId.trim().toLowerCase() !== formId) {
+    return false;
+  }
+
+  const eventType = (
+    stringField(payload.type) ?? stringField(payload.event) ?? ""
+  )
+    .trim()
+    .toLowerCase();
+
+  if (eventType === "form_step") {
+    const direction = stringField(payload.direction)?.trim().toLowerCase();
+    if (direction === "next" || direction === "back") {
+      target.step(direction);
+      return true;
+    }
+    const stepIndex = payload.step_index;
+    if (typeof stepIndex === "number" && Number.isFinite(stepIndex)) {
+      target.step(stepIndex);
+      return true;
+    }
+    // Malformed step event — swallow so it doesn't fall through to the
+    // generic form matcher and accidentally re-render.
+    return true;
+  }
+
+  if (eventType === "form_submit") {
+    target.submit();
+    return true;
+  }
+
+  if (eventType === "form_close") {
+    target.close();
+    return true;
+  }
+
+  return false;
+}
+
+/** Flatten a form to its full field list — single-page or stepper. Excludes display blocks. */
+export function collectInputFields(definition: FormDefinition): FormFieldDef[] {
+  const all = definition.steps?.length
+    ? definition.steps.flatMap((s) => s.fields)
+    : definition.fields;
+  return all.filter((f) => f.type !== "display" && Boolean(f.name));
+}
+
+/** Fields for a specific step (or the whole form when no stepper). */
+export function fieldsForStep(
+  definition: FormDefinition,
+  stepIndex: number,
+): FormFieldDef[] {
+  if (definition.steps?.length) {
+    const step = definition.steps[Math.max(0, Math.min(stepIndex, definition.steps.length - 1))];
+    return step?.fields ?? [];
+  }
+  return definition.fields;
+}
+
+export function totalSteps(definition: FormDefinition): number {
+  return definition.steps?.length || 1;
+}
+
+/** A single field that failed local validation. */
+export interface FieldValidationError {
+  name: string;
+  label: string;
+  message: string;
+}
+
+// Loose, intentionally permissive formats — the goal is to catch obvious
+// typos before submit, not to reject every unusual-but-valid value.
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const TEL_ALLOWED_RE = /^[+()\-.\s\d]+$/;
+
+/**
+ * Validate the given values against their field definitions, returning one
+ * error per offending field. Runs entirely in the browser so obvious mistakes
+ * (missing required fields, malformed email/phone, out-of-range numbers, custom
+ * pattern mismatches) are caught before anything is sent to the server/agent.
+ *
+ * Format checks are skipped for empty optional fields — only `required` flags
+ * empties. `display` blocks and unnamed fields are ignored.
+ */
+export function validateFields(
+  fields: FormFieldDef[],
+  values: Record<string, string>,
+): FieldValidationError[] {
+  const errors: FieldValidationError[] = [];
+  for (const field of fields) {
+    if (field.type === "display" || !field.name) continue;
+    const raw = values[field.name];
+    const value = (raw ?? "").trim();
+
+    if (!value) {
+      if (field.required) {
+        errors.push({ name: field.name, label: field.label, message: `${field.label} is required.` });
+      }
+      // Nothing more to validate on an empty optional field.
+      continue;
+    }
+
+    if (field.type === "email" && !EMAIL_RE.test(value)) {
+      errors.push({ name: field.name, label: field.label, message: "Enter a valid email address." });
+      continue;
+    }
+
+    if (field.type === "tel") {
+      const digits = value.replace(/\D/g, "");
+      if (!TEL_ALLOWED_RE.test(value) || digits.length < 7) {
+        errors.push({ name: field.name, label: field.label, message: "Enter a valid phone number." });
+        continue;
+      }
+    }
+
+    if (field.type === "number") {
+      const num = Number(value);
+      if (!Number.isFinite(num)) {
+        errors.push({ name: field.name, label: field.label, message: "Enter a valid number." });
+        continue;
+      }
+      if (field.min !== undefined && num < field.min) {
+        errors.push({ name: field.name, label: field.label, message: `Must be at least ${field.min}.` });
+        continue;
+      }
+      if (field.max !== undefined && num > field.max) {
+        errors.push({ name: field.name, label: field.label, message: `Must be at most ${field.max}.` });
+        continue;
+      }
+    }
+
+    if (field.pattern) {
+      try {
+        if (!new RegExp(field.pattern).test(value)) {
+          errors.push({ name: field.name, label: field.label, message: `Please enter a valid ${field.label.toLowerCase()}.` });
+          continue;
+        }
+      } catch {
+        // A malformed pattern in the form config must never break submission.
+      }
+    }
+  }
+  return errors;
+}
+
+const BOOK_DEMO_INTEREST_OPTIONS = [
+  "Enterprise Voice Platform (OVIP)",
+  "Fine-Tuning Automation (OFTA)",
+  "Consumer / Kids Products",
+  "Investor Relations",
+  "Partnership / Integration",
+];
+
+export const DEFAULT_FORM_DEFINITIONS: FormDefinition[] = [
+  {
+    id: "book-demo",
+    title: "Book a demo",
+    subtitle:
+      "The voice agent filled this from the call. Review and edit before sending.",
+    submit_url: "/api/book-demo/",
+    submit_label: "Confirm & send",
+    success_message:
+      "Thanks! Your demo request has been sent. We'll get back to you soon.",
+    topics: ["book-demo.form", "book-demo.review", "form.book-demo"],
+    event_types: ["book_demo_form", "book-demo-form"],
+    // Match the webapp's help-desk-call echo so the agent sees the same
+    // event type from either surface. Default would have been
+    // "book-demo_submitted" (hyphen).
+    confirmation_type: "book_demo_submitted",
+    fields: [
+      { name: "name", label: "Full name", type: "text", required: true, placeholder: "Your full name" },
+      { name: "organization", label: "Organization", type: "text", required: true, placeholder: "Your company or organization" },
+      { name: "email", label: "Email", type: "email", required: true, placeholder: "you@organization.com" },
+      {
+        name: "interested_in",
+        label: "I'm interested in...",
+        type: "select",
+        required: true,
+        options: BOOK_DEMO_INTEREST_OPTIONS,
+        default_value: BOOK_DEMO_INTEREST_OPTIONS[0],
+      },
+      {
+        name: "description",
+        label: "Why do you want to book a demo?",
+        type: "textarea",
+        required: true,
+        rows: 4,
+        placeholder: "Describe your use case, goals, or questions...",
+      },
+    ],
+  },
+  {
+    id: "reservation",
+    title: "Make a reservation",
+    subtitle:
+      "The voice agent filled this from the call. Review and edit before sending.",
+    submit_url: "/api/reservations/",
+    submit_label: "Confirm reservation",
+    success_message: "Reservation confirmed. We'll send a confirmation email shortly.",
+    topics: ["reservation.form", "form.reservation"],
+    event_types: ["reservation_form", "reservation-form"],
+    fields: [
+      { name: "name", label: "Name", type: "text", required: true, placeholder: "Your name" },
+      { name: "email", label: "Email", type: "email", required: true, placeholder: "you@example.com" },
+      { name: "phone", label: "Phone", type: "tel", placeholder: "+977 98XXXXXXXX" },
+      { name: "party_size", label: "Party size", type: "text", required: true, placeholder: "e.g. 4" },
+      { name: "date", label: "Date", type: "text", required: true, placeholder: "YYYY-MM-DD" },
+      { name: "time", label: "Time", type: "text", required: true, placeholder: "HH:MM" },
+      { name: "notes", label: "Notes", type: "textarea", rows: 3, placeholder: "Allergies, occasion, seating preference…" },
+    ],
+  },
+];
+
+/**
+ * Try to identify which form definition an incoming LiveKit data message is
+ * asking the widget to open. Returns null if no definition matches.
+ */
+export function matchForm(
+  topic: string | undefined,
+  value: unknown,
+  forms: FormDefinition[],
+): FormDefinition | null {
+  if (!value || typeof value !== "object") return null;
+
+  const normalize = (s: string) => s.trim().toLowerCase();
+
+  if (topic) {
+    const t = normalize(topic);
+    for (const form of forms) {
+      if (form.topics?.some((entry) => normalize(entry) === t)) return form;
+      const id = normalize(form.id);
+      if (
+        t === `${id}.form` ||
+        t === `${id}.review` ||
+        t === `form.${id}` ||
+        t === id
+      ) {
+        return form;
+      }
+    }
+  }
+
+  const candidate = value as Record<string, unknown>;
+
+  const explicitId = stringField(candidate.form_id) ?? stringField(candidate.formId);
+  if (explicitId) {
+    const id = normalize(explicitId);
+    const match = forms.find((f) => normalize(f.id) === id);
+    if (match) return match;
+  }
+
+  const eventType = [candidate.type, candidate.event, candidate.kind, candidate.intent]
+    .map(stringField)
+    .find((v): v is string => Boolean(v))
+    ?.toLowerCase();
+
+  if (eventType) {
+    for (const form of forms) {
+      if (form.event_types?.some((entry) => normalize(entry) === eventType)) return form;
+      const id = normalize(form.id);
+      if (
+        eventType === id ||
+        eventType === `${id}_form` ||
+        eventType === `${id}-form` ||
+        eventType === `${id.replace(/-/g, "_")}_form`
+      ) {
+        return form;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Pull a partial field/value draft out of an incoming data message. Looks at
+ * the payload root and common nested keys (`form`, `payload`, `data`,
+ * `fields`, `values`). Returns null when nothing matches the form's fields.
+ */
+export function extractFormDraft(
+  value: unknown,
+  definition: FormDefinition,
+): Record<string, string> | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Record<string, unknown>;
+
+  const nested = ["draft", "form", "payload", "data", "fields", "values"]
+    .map((key) => candidate[key])
+    .find((entry) => entry && typeof entry === "object") as
+    | Record<string, unknown>
+    | undefined;
+
+  const draft: Record<string, string> = {};
+
+  for (const field of collectInputFields(definition)) {
+    if (!field.name) continue;
+    const raw =
+      stringField(nested?.[field.name]) ?? stringField(candidate[field.name]);
+    if (raw) draft[field.name] = raw;
+  }
+
+  return Object.keys(draft).length > 0 ? draft : null;
+}
+
+export function initialFormValues(
+  definition: FormDefinition,
+): Record<string, string> {
+  const values: Record<string, string> = {};
+  for (const field of collectInputFields(definition)) {
+    if (!field.name) continue;
+    values[field.name] = field.default_value ?? "";
+  }
+  return values;
+}
+
+export function mergeFormDraft(
+  current: Record<string, string>,
+  draft: Record<string, string> | null | undefined,
+): Record<string, string> {
+  if (!draft) return current;
+  const next = { ...current };
+  for (const [k, v] of Object.entries(draft)) {
+    if (typeof v === "string" && v.trim()) next[k] = v.trim();
+  }
+  return next;
+}
+
+/** Plain-text summary of a submission — echoed back to the agent on confirm. */
+export function buildSubmissionText(
+  definition: FormDefinition,
+  values: Record<string, string>,
+): string {
+  const parts = collectInputFields(definition)
+    .map((f) => `${f.label.toLowerCase()}: ${(values[f.name!] ?? "").trim()}`)
+    .filter((entry) => !entry.endsWith(": "));
+  return `I have confirmed and submitted the "${definition.title}" form: ${parts.join("; ")}.`;
+}
+
+export interface SubmitFormArgs {
+  definition: FormDefinition;
+  values: Record<string, string>;
+  apiUrl: string;
+  /** Agent slug — required when submit_url is null (managed storage path). */
+  slug: string;
+  /** Active session ID to link the form response to its billing session. */
+  sessionId?: string | null;
+  /** Secret key sent as `x-api-key` on the managed-storage POST. */
+  apiKey?: string;
+  /** Custom fetch (Node <18 / testing). Defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+}
+
+/** Collect all field definitions across steps and top-level fields. */
+function allFields(definition: FormDefinition): FormFieldDef[] {
+  if (definition.steps?.length) {
+    return definition.steps.flatMap((s) => s.fields);
+  }
+  return definition.fields;
+}
+
+export async function submitForm({
+  definition,
+  values,
+  apiUrl,
+  slug,
+  sessionId,
+  apiKey,
+  fetch: fetchImpl,
+}: SubmitFormArgs): Promise<unknown> {
+  const base = apiUrl.replace(/\/+$/, "");
+
+  let url: string;
+  let body: unknown;
+  let method: string;
+  let managed = false;
+
+  if (!definition.submit_url) {
+    // Managed storage path: POST to platform API with question+answer pairs.
+    managed = true;
+    url = `${base}/api/agents/${slug}/form-responses/`;
+    method = "POST";
+    const formData = allFields(definition)
+      .filter((f) => f.name && f.type !== "display")
+      .map((f) => ({
+        name: f.name!,
+        label: f.label,
+        value: values[f.name!] ?? "",
+      }));
+    body = {
+      form_id: definition.id,
+      form_data: formData,
+      ...(sessionId ? { session_id: sessionId } : {}),
+    };
+  } else {
+    // External submit_url path (existing behaviour).
+    url = /^https?:\/\//i.test(definition.submit_url)
+      ? definition.submit_url
+      : `${base}/${definition.submit_url.replace(/^\/+/, "")}`;
+    method = definition.submit_method ?? "POST";
+    body = values;
+  }
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  // Only attach the platform key on the managed-storage path; never leak it to
+  // a third-party submit_url.
+  if (managed && apiKey?.trim()) headers["x-api-key"] = apiKey.trim();
+  const doFetch =
+    fetchImpl ??
+    (typeof globalThis.fetch === "function"
+      ? globalThis.fetch.bind(globalThis)
+      : (() => {
+          throw new Error("[voice-agent] No fetch available; pass config.fetch.");
+        })());
+
+  const response = await doFetch(url, {
+    method,
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  const data = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    throw new Error(
+      data?.error ||
+        data?.detail ||
+        `We couldn't send your request right now (HTTP ${response.status}).`,
+    );
+  }
+
+  return data;
+}
+
+/**
+ * Accept a partial `forms` array from the appearance config (or anywhere
+ * else) and turn it into a clean array of FormDefinitions, dropping entries
+ * that don't have an id + at least one field.
+ */
+export function normalizeFormDefinitions(value: unknown): FormDefinition[] {
+  if (!Array.isArray(value)) return [];
+  const out: FormDefinition[] = [];
+
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Record<string, unknown>;
+    const id = stringField(entry.id);
+    if (!id) continue;
+
+    const steps = normalizeSteps(entry.steps);
+    const fields = normalizeFields(entry.fields);
+    // A form must have either at least one step (with fields) or a fields array.
+    if (!steps.length && !fields.length) continue;
+
+    out.push({
+      id,
+      title: stringField(entry.title) ?? id,
+      subtitle: stringField(entry.subtitle),
+      fields,
+      steps: steps.length ? steps : undefined,
+      layout: normalizeLayout(entry.layout),
+      disabled: entry.disabled === true ? true : undefined,
+      submit_url: stringField(entry.submit_url) ?? null,
+      submit_method: enumField(
+        ["POST", "PUT", "PATCH"] as const,
+        entry.submit_method,
+      ),
+      submit_label: stringField(entry.submit_label),
+      success_message: stringField(entry.success_message),
+      topics: stringArray(entry.topics),
+      event_types: stringArray(entry.event_types),
+      confirmation_topic: stringField(entry.confirmation_topic),
+      confirmation_type: stringField(entry.confirmation_type),
+    });
+  }
+  return out;
+}
+
+function normalizeFields(value: unknown): FormFieldDef[] {
+  if (!Array.isArray(value)) return [];
+  const out: FormFieldDef[] = [];
+  for (const raw of value) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Record<string, unknown>;
+    const type =
+      enumField(
+        [
+          "text",
+          "email",
+          "tel",
+          "textarea",
+          "select",
+          "number",
+          "date",
+          "time",
+          "checkbox",
+          "radio",
+          "display",
+        ] as const,
+        entry.type,
+      ) ?? "text";
+    const name = stringField(entry.name);
+    // Inputs require a name; display blocks don't.
+    if (type !== "display" && !name) continue;
+
+    out.push({
+      name,
+      label: stringField(entry.label) ?? name ?? "",
+      type,
+      placeholder: stringField(entry.placeholder),
+      required: entry.required === true,
+      options: normalizeOptions(entry.options),
+      rows:
+        typeof entry.rows === "number" && Number.isFinite(entry.rows) && entry.rows > 0
+          ? entry.rows
+          : undefined,
+      default_value: stringField(entry.default_value),
+      help_text: stringField(entry.help_text),
+      pattern: stringField(entry.pattern),
+      min: finiteNumber(entry.min),
+      max: finiteNumber(entry.max),
+      width: enumField(["full", "half"] as const, entry.width),
+    });
+  }
+  return out;
+}
+
+function normalizeSteps(value: unknown): FormStep[] {
+  if (!Array.isArray(value)) return [];
+  const out: FormStep[] = [];
+  for (const [index, raw] of value.entries()) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Record<string, unknown>;
+    const fields = normalizeFields(entry.fields);
+    if (!fields.length) continue;
+    out.push({
+      id: stringField(entry.id) ?? `step-${index + 1}`,
+      title: stringField(entry.title),
+      subtitle: stringField(entry.subtitle),
+      fields,
+      next_label: stringField(entry.next_label),
+      back_label: stringField(entry.back_label),
+    });
+  }
+  return out;
+}
+
+function normalizeLayout(value: unknown): FormLayout | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const entry = value as Record<string, unknown>;
+  const layout: FormLayout = {};
+  const fieldLayout = enumField(["stack", "grid"] as const, entry.field_layout);
+  if (fieldLayout) layout.field_layout = fieldLayout;
+  const density = enumField(["comfortable", "compact"] as const, entry.density);
+  if (density) layout.density = density;
+  const labelPos = enumField(["top", "inline"] as const, entry.label_position);
+  if (labelPos) layout.label_position = labelPos;
+  return Object.keys(layout).length ? layout : undefined;
+}
+
+function normalizeOptions(value: unknown): FormFieldOption[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: FormFieldOption[] = [];
+  for (const raw of value) {
+    if (typeof raw === "string") {
+      const trimmed = raw.trim();
+      if (trimmed) out.push(trimmed);
+      continue;
+    }
+    if (raw && typeof raw === "object") {
+      const entry = raw as Record<string, unknown>;
+      const v = stringField(entry.value);
+      if (!v) continue;
+      const label = stringField(entry.label);
+      out.push(label ? { value: v, label } : { value: v });
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Number(value.trim());
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
+}
+
+function stringField(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out = value
+    .map(stringField)
+    .filter((v): v is string => Boolean(v));
+  return out.length ? out : undefined;
+}
+
+function enumField<T extends string>(
+  allowed: readonly T[],
+  value: unknown,
+): T | undefined {
+  return typeof value === "string" && allowed.includes(value as T)
+    ? (value as T)
+    : undefined;
+}