Server-side validation

function parseSubmission(
  config: FormConfig,
  rawBody: unknown,
  opts?: {
    otpVerified?: OtpVerifiedChecker;   // required if a visible otp field exists
    messages?: Partial<Messages>;       // i18n overrides, merged over defaultMessages
    maxStringLength?: number;           // default 10_000
  },
):
  | { ok: true; values: FormValues; unvalidated: string[] }
  | { ok: false; code: ParseSubmissionErrorCode; errors: ServerErrorResult; unvalidated: string[] };

// app/api/signup/route.ts
import { parseSubmission } from "@/form-builder";
import { signupConfig } from "./config";
import { createAccount } from "@/lib/accounts"; // your own persistence

export async function POST(request: Request) {
  const result = parseSubmission(signupConfig, await request.json());
  if (!result.ok) return Response.json(result.errors, { status: 400 });

  // result.values is the validated payload — create the account, etc.
  await createAccount(result.values);
  return Response.json({ ok: true });
}

"use client";
// FormRenderer's onSubmit may return a ServerErrorResult (or resolve to
// one) — returning it maps fieldErrors -> setError per field and
// formError -> the form's root error slot, via applyServerErrors
// internally. No extra client-side glue needed.
import { FormRenderer } from "@/form-builder";
import { signupConfig } from "./config";

export function SignupForm() {
  return (
    <FormRenderer
      config={signupConfig}
      onSubmit={async (values) => {
        const res = await fetch("/api/signup", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(values),
        });
        if (res.ok) return;
        // res.body IS the ServerErrorResult parseSubmission returned as
        // `result.errors` on the server — return it as-is.
        return res.json();
      }}
    />
  );
}

// app/signup/actions.ts
"use server";
import { parseSubmission } from "@/form-builder";
import type { FormValues } from "@/form-builder";
import { signupConfig } from "./config";
import { createAccount } from "@/lib/accounts"; // your own persistence

export async function submitSignup(values: FormValues) {
  const result = parseSubmission(signupConfig, values);
  if (!result.ok) return result.errors; // matches onSubmit's return contract
  await createAccount(result.values);
}

"use client";
// A Server Action is just an async function once "use server" marks its
// module — pass it straight to onSubmit, no fetch/route glue at all.
import { FormRenderer } from "@/form-builder";
import { signupConfig } from "./config";
import { submitSignup } from "./actions";

export function SignupForm() {
  return <FormRenderer config={signupConfig} onSubmit={submitSignup} />;
}

// A non-Next host — same two-line core, wired to Express instead of a Route Handler.
import express from "express";
import { parseSubmission } from "@form-builder/engine"; // published headless entry
import { signupConfig } from "./signupConfig";
import { createAccount } from "./accounts"; // your own persistence

const app = express();
app.use(express.json());

app.post("/api/signup", async (req, res) => {
  const result = parseSubmission(signupConfig, req.body);
  if (!result.ok) return res.status(400).json(result.errors);

  await createAccount(result.values);
  res.json({ ok: true });
});

// app/api/signup/route.ts
import { timingSafeEqual } from "node:crypto";
import { parseSubmission } from "@/form-builder";
import { signupConfig } from "./config";
import { getSession } from "@/lib/session";
import { otpStore } from "@/lib/otpStore"; // your own store — Redis, a DB table, whatever
import { createAccount } from "@/lib/accounts"; // your own persistence

export async function POST(request: Request) {
  const session = await getSession(request); // a session/challenge id — never a body field
  const rawBody = await request.json();

  // Rate-limit attempts BEFORE spending a lookup.
  if (await otpStore.tooManyAttempts(session.id)) {
    return Response.json({ formError: "Too many attempts. Try again later." }, { status: 429 });
  }

  // Phase 1: ONE await against your own store, building a synchronous
  // lookup. parseSubmission is synchronous end to end — it can never await
  // your store mid-call, so this Map has to exist before you call it.
  const challenge = await otpStore.get(session.id); // keyed by session, never rawBody
  const issuedCode = challenge?.fieldName === "otp" ? challenge.code : undefined;

  // Phase 2: a sync closure over what phase 1 fetched — a PURE comparison,
  // no side effects. The checker may run independent of whether the rest
  // of the submission ultimately validates, so it must never consume/expire
  // the code itself (that would burn a correct code on, e.g., a submission
  // that fails only because the password is too short).
  const result = parseSubmission(signupConfig, rawBody, {
    otpVerified: (fieldName, code) => {
      if (fieldName !== "otp" || issuedCode === undefined) return false;
      const submitted = Buffer.from(code);
      const issued = Buffer.from(issuedCode);
      return submitted.length === issued.length && timingSafeEqual(submitted, issued);
    },
  });

  if (!result.ok) return Response.json(result.errors, { status: 400 });

  // Consume/expire the code only now — AFTER the whole submission is known
  // to be valid, not inside the checker. Single-use, correctly enforced.
  await otpStore.consume(session.id);
  await createAccount(result.values);
  return Response.json({ ok: true });
}

// The client uploads directly to storage and submits a storage
// reference, never the file bytes, over the JSON body parseSubmission sees.
{ type: "file", name: "resume" } // omitted from schema validation, always

// A typical presigned-upload shape the host validates on its own:
{ "resume": { "key": "uploads/abc123.pdf", "size": 214532, "contentType": "application/pdf" } }

const result = parseSubmission(config, rawBody, { otpVerified });
if (!result.ok) return Response.json(result.errors, { status: 400 });

// result.unvalidated names every field the schema skipped — files, and
// custom registered types. Validate the ones you care about yourself:
const gizmo = z.object({ widgetId: z.string(), qty: z.number().int().min(1) });
const parsedGizmo = gizmo.safeParse(result.values.gizmo);
if (!parsedGizmo.success) {
  return Response.json({ fieldErrors: { gizmo: "Invalid widget selection" } }, { status: 400 });
}

{
  // hidden: value is re-injected from config BEFORE visibility is computed,
  // on every parse, unconditionally. The body's own "plan" key is discarded.
  type: "hidden",
  name: "plan",
  value: "pro",
},
{
  // disabled: a purely presentational flag. It carries no config value to
  // re-inject, so parseSubmission has nothing to enforce here — the body's
  // "discountPercent" is trusted as submitted, same as any other field.
  type: "number",
  name: "discountPercent",
  disabled: true,
}

{
  type: "group",
  name: "team",
  fields: [
    { type: "checkbox", name: "hasRole" },
    // Still validated as required server-side even when hasRole is false —
    // identical to the client's known v1 limitation, not a server-only bug.
    { type: "text", name: "role", required: true, visibleWhen: { field: "hasRole", equals: true } },
  ],
}

// A malformed config THROWS — parseSubmission does not catch it for you.
try {
  const result = parseSubmission(config, rawBody, { otpVerified });
  // ...
} catch {
  // A broken config is an authoring error, not bad user input. Let this
  // surface as a 500 (or don't catch it at all) — folding it into a 400
  // would hide a real outage from monitoring behind ordinary form noise.
}