@iterant/site-runtime 3.6.1 → 3.8.0

package/src/lib/submit-form.ts

@@ -0,0 +1,123 @@
+// The page-side half of platform form capture. A submission posts to the same
+// endpoint, in the same body, that the injected runtime and the edge-rewritten
+// native form already use (apps/site-dispatch, iterant-endpoints.ts). There is
+// one protocol: this module reuses its field names and never adds one.
+
+/** The endpoint's own control fields. Everything else in a body is visitor data. */
+export const FORM_HONEYPOT_FIELD = "_hp";
+const FORM_IDEMPOTENCY_FIELD = "_ik";
+const FORM_SID_FIELD = "_sid";
+
+/** The opaque form-key grammar the endpoint routes on; a key outside it is a 404 there. */
+export const FORM_KEY_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+// The direct-origin base. A page served through the platform edge carries the
+// prefix-resolved base in the injected config, which wins.
+const DEFAULT_FORMS_BASE = "/_iterant/forms";
+
+export type SubmitFormResult = { ok: true } | { ok: false; error: string };
+
+export interface SubmitFormOptions {
+  /** Reuse one key across retries of one submission and the platform collapses
+   *  them to a single row. Minted per call when absent. */
+  idempotencyKey?: string;
+}
+
+// What the injected runtime leaves on the window: its config, and the session
+// id it minted, so a lead submitted from page code still joins the visitor's
+// journey without this package learning where the id is stored.
+type SignalsWindow = {
+  __ITERANT_SIGNALS__?: { formsBase?: string };
+  iterantSignals?: { sid?(): string };
+};
+
+function signals(): SignalsWindow {
+  return typeof window === "undefined"
+    ? {}
+    : (window as unknown as SignalsWindow);
+}
+
+function formsBase(): string {
+  return signals().__ITERANT_SIGNALS__?.formsBase || DEFAULT_FORMS_BASE;
+}
+
+function readSid(): string {
+  try {
+    return signals().iterantSignals?.sid?.() ?? "";
+  } catch {
+    return "";
+  }
+}
+
+export function mintIdempotencyKey(): string {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `ik-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+/** A form's fields as the record `submitForm` takes: strings only, so a file
+ *  input contributes nothing, the same read the injected runtime performs. */
+export function readFormFields(form: HTMLFormElement): Record<string, string> {
+  const fields: Record<string, string> = {};
+  new FormData(form).forEach((value, name) => {
+    if (typeof value === "string") fields[name] = value;
+  });
+  return fields;
+}
+
+/** Post one submission for the form key `name`. Resolves to `{ ok: true }` on
+ *  a durable accept and `{ ok: false, error }` otherwise, and never throws:
+ *  `error` is the endpoint's own token (`rate_limited`, `turnstile_failed`,
+ *  `drain_failed`), `http_<status>` for an answer without one, `network` when
+ *  nothing answered, `invalid_name` for a key the endpoint would not route and
+ *  `unsupported_field:<name>` for a value that is not a string. */
+export async function submitForm(
+  name: string,
+  fields: Record<string, string>,
+  options: SubmitFormOptions = {},
+): Promise<SubmitFormResult> {
+  if (!FORM_KEY_PATTERN.test(name)) return { ok: false, error: "invalid_name" };
+  const body: Record<string, string> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    // File inputs are unsupported: only string values are captured.
+    if (typeof value !== "string") {
+      return { ok: false, error: `unsupported_field:${key}` };
+    }
+    body[key] = value;
+  }
+  body[FORM_IDEMPOTENCY_FIELD] = options.idempotencyKey ?? mintIdempotencyKey();
+  const sid = readSid();
+  if (sid) body[FORM_SID_FIELD] = sid;
+
+  let response: Response;
+  try {
+    response = await fetch(`${formsBase()}/${encodeURIComponent(name)}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      credentials: "omit",
+    });
+  } catch {
+    return { ok: false, error: "network" };
+  }
+  if (response.ok) return { ok: true };
+  return {
+    ok: false,
+    error: (await errorToken(response)) ?? `http_${response.status}`,
+  };
+}
+
+// The endpoint refuses with a JSON envelope carrying a token. Anything else
+// (a dev server's HTML 404, a proxy's error page) has no token to read.
+async function errorToken(response: Response): Promise<string | null> {
+  try {
+    const parsed: unknown = await response.json();
+    if (parsed && typeof parsed === "object") {
+      const error = (parsed as { error?: unknown }).error;
+      if (typeof error === "string" && error !== "") return error;
+    }
+  } catch {
+    // not the endpoint's envelope
+  }
+  return null;
+}