@oshara/voice-sdk 0.1.0

package/src/core/formController.ts

@@ -0,0 +1,317 @@
+/**
+ * Headless form controller.
+ *
+ * Lifted from the widget's `createFormController`, with every DOM touch
+ * (`renderForm`, `readFormValues`, `setFieldErrors`, `setScreen`) replaced by
+ * typed events. The controller now owns the form `values` model; consumers
+ * (custom or prebuilt UI) push on-screen edits in via `updateValues()` — this
+ * replaces the old `readFormValues(refs)` reads.
+ *
+ * The agent round-trip (form.state publishing, form_submit_failed and
+ * confirmation messages) is preserved exactly.
+ */
+
+import type { Emit } from "./events";
+import {
+  FormDefinition,
+  FormStateSnapshot,
+  buildFieldSchema,
+  buildSubmissionText,
+  collectInputFields,
+  fieldsForStep,
+  initialFormValues,
+  mergeFormDraft,
+  submitForm,
+  totalSteps,
+  validateFields,
+} from "./forms";
+import type { VoiceController } from "./voice";
+
+export interface FormControllerOptions {
+  emit: Emit;
+  voice: VoiceController;
+  apiUrl: string;
+  agentSlug: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+}
+
+export interface FormController {
+  open: (definition: FormDefinition, draft?: Record<string, string>) => void;
+  merge: (draft: Record<string, string>) => void;
+  close: () => void;
+  current: () => string | null;
+  step: (direction: "next" | "back" | number) => void;
+  submit: () => void;
+  /** Push on-screen edits into the values model (replaces readFormValues). */
+  updateValues: (values: Record<string, string>) => void;
+  /** Snapshot of the active form, or null. */
+  getActive: () => {
+    definition: FormDefinition;
+    values: Record<string, string>;
+    stepIndex: number;
+  } | null;
+}
+
+/** Index of the first stepper step containing one of the named (invalid)
+ *  fields, or -1 if none match (or the form isn't a stepper). */
+function firstStepWithError(
+  definition: FormDefinition,
+  errorNames: Set<string>,
+): number {
+  const steps = definition.steps;
+  if (!steps?.length) return -1;
+  for (let i = 0; i < steps.length; i++) {
+    const hit = steps[i].fields.some((f) => f.name && errorNames.has(f.name));
+    if (hit) return i;
+  }
+  return -1;
+}
+
+export function createFormController(
+  opts: FormControllerOptions,
+): FormController {
+  const { emit, voice, apiUrl, agentSlug, apiKey, fetch: fetchImpl } = opts;
+  let active: FormDefinition | null = null;
+  let values: Record<string, string> = {};
+  let stepIndex = 0;
+  let stateTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const buildSnapshot = (isOpen: boolean): FormStateSnapshot | null => {
+    if (!active) return null;
+    const definition = active;
+    return {
+      type: "form_state",
+      form_id: definition.id,
+      is_open: isOpen,
+      step_index: stepIndex,
+      total_steps: totalSteps(definition),
+      values: { ...values },
+      // Ship the field schema (incl. select/radio/checkbox options) so the
+      // agent can register enum-constrained voice-fill tools even when the
+      // session token has no appearance.forms entry for this form.
+      fields: buildFieldSchema(definition),
+    };
+  };
+
+  const flushState = (isOpen: boolean) => {
+    if (stateTimer !== null) {
+      clearTimeout(stateTimer);
+      stateTimer = null;
+    }
+    if (!voice.isActive()) return;
+    const snapshot = isOpen
+      ? buildSnapshot(true)
+      : ({
+          type: "form_state",
+          form_id: "",
+          is_open: false,
+          step_index: 0,
+          total_steps: 0,
+          values: {},
+          fields: [],
+        } satisfies FormStateSnapshot);
+    if (!snapshot) return;
+    void voice.publishData(snapshot, "form.state");
+  };
+
+  const scheduleStatePublish = () => {
+    if (stateTimer !== null) clearTimeout(stateTimer);
+    stateTimer = setTimeout(() => {
+      stateTimer = null;
+      flushState(active !== null);
+    }, 250);
+  };
+
+  const emitUpdate = () => {
+    emit("form:update", { values: { ...values }, stepIndex });
+  };
+
+  const close = () => {
+    if (stateTimer !== null) {
+      clearTimeout(stateTimer);
+      stateTimer = null;
+    }
+    const wasOpen = active !== null;
+    active = null;
+    values = {};
+    stepIndex = 0;
+    emit("form:close", {});
+    if (wasOpen) flushState(false);
+  };
+
+  const open = (definition: FormDefinition, draft?: Record<string, string>) => {
+    active = definition;
+    stepIndex = 0;
+    values = mergeFormDraft(initialFormValues(definition), draft ?? null);
+    emit("form:show", {
+      definition,
+      draft: { ...values },
+      stepIndex,
+      inCall: voice.isActive(),
+      transcriptionEnabled:
+        voice.isActive() && voice.getAudioState().prefs.transcriptionEnabled,
+    });
+    flushState(true);
+  };
+
+  const merge = (draft: Record<string, string>) => {
+    if (!active) return;
+    // `values` is kept current by updateValues() on every keystroke, so the
+    // agent's draft overlays only the fields it set without wiping manual edits.
+    values = mergeFormDraft(values, draft);
+    emitUpdate();
+    flushState(true);
+  };
+
+  const updateValues = (next: Record<string, string>) => {
+    if (!active) return;
+    Object.assign(values, next);
+    scheduleStatePublish();
+  };
+
+  const goToStep = (target: number) => {
+    if (!active) return;
+    const steps = totalSteps(active);
+    const clamped = Math.max(0, Math.min(target, steps - 1));
+    if (clamped === stepIndex) return;
+    stepIndex = clamped;
+    emitUpdate();
+    flushState(true);
+  };
+
+  const stepBack = () => {
+    if (!active || stepIndex === 0) return;
+    goToStep(stepIndex - 1);
+  };
+
+  const attemptSubmit = async () => {
+    if (!active) return;
+    const definition = active;
+    const steps = totalSteps(definition);
+    const isFinalStep = stepIndex >= steps - 1;
+
+    // While navigating, validate just the current step. On the final step
+    // (actual submit) validate every required field across all steps so a
+    // skipped or agent-jumped step can't slip an empty required field past.
+    const fieldsToCheck = isFinalStep
+      ? collectInputFields(definition)
+      : fieldsForStep(definition, stepIndex);
+    const errors = validateFields(fieldsToCheck, values);
+    if (errors.length) {
+      // If an offending field lives on an earlier step, jump there so the
+      // visitor can actually see and fix it.
+      if (isFinalStep && totalSteps(definition) > 1) {
+        const targetStep = firstStepWithError(
+          definition,
+          new Set(errors.map((e) => e.name)),
+        );
+        if (targetStep >= 0 && targetStep !== stepIndex) {
+          stepIndex = targetStep;
+          emitUpdate();
+        }
+      }
+      emit("form:validation", { errors });
+      // Tell the agent the submit was rejected so it doesn't claim success.
+      if (voice.isActive()) {
+        void voice.publishData(
+          {
+            type: "form_submit_failed",
+            form_id: definition.id,
+            text:
+              `(System: the "${definition.title}" form was NOT submitted — ` +
+              `these fields need attention: ` +
+              `${errors.map((e) => `${e.label} (${e.message})`).join(", ")}. ` +
+              `Ask the visitor to correct them and do not say it was submitted.)`,
+          },
+          "voice.user_text",
+        );
+      }
+      return;
+    }
+
+    if (!isFinalStep) {
+      stepIndex += 1;
+      emitUpdate();
+      flushState(true);
+      return;
+    }
+
+    // Final step — submit.
+    emit("form:submitting", {});
+    try {
+      await submitForm({
+        definition,
+        values,
+        apiUrl,
+        slug: agentSlug,
+        sessionId: voice.sessionId(),
+        apiKey,
+        fetch: fetchImpl,
+      });
+      const successMessage =
+        definition.success_message ?? "Submitted. We'll be in touch shortly.";
+      emit("form:submitted", {
+        formId: definition.id,
+        values: { ...values },
+        successMessage,
+      });
+
+      if (voice.isActive()) {
+        void voice.publishData(
+          {
+            type: definition.confirmation_type ?? `${definition.id}_submitted`,
+            form_id: definition.id,
+            text: buildSubmissionText(definition, values),
+            form: { ...values },
+          },
+          definition.confirmation_topic ?? "voice.user_text",
+        );
+      }
+
+      // Let the success message breathe, then close the form so the user is
+      // dropped back on the call (or welcome if the call has ended).
+      setTimeout(() => {
+        if (active === definition) close();
+      }, 1500);
+    } catch (err) {
+      const message =
+        err instanceof Error
+          ? err.message
+          : "We couldn't send your request right now. Please try again.";
+      emit("form:error", { message });
+      if (voice.isActive()) {
+        void voice.publishData(
+          {
+            type: "form_submit_failed",
+            form_id: definition.id,
+            text:
+              `(System: the "${definition.title}" form submission failed: ` +
+              `${message} Tell the visitor it didn't go through and offer ` +
+              `to try again.)`,
+          },
+          "voice.user_text",
+        );
+      }
+    }
+  };
+
+  return {
+    open,
+    merge,
+    close,
+    updateValues,
+    current: () => active?.id ?? null,
+    getActive: () =>
+      active ? { definition: active, values: { ...values }, stepIndex } : null,
+    step: (direction) => {
+      if (!active) return;
+      if (direction === "next") goToStep(stepIndex + 1);
+      else if (direction === "back") stepBack();
+      else if (typeof direction === "number") goToStep(direction);
+    },
+    submit: () => {
+      void attemptSubmit();
+    },
+  };
+}