@synap-core/sdk 1.1.0 → 1.3.0

package/src/testing/index.ts

@@ -0,0 +1,359 @@
+/**
+ * @synap-core/sdk/testing — a mock pod: a fake `fetch` that answers the pod's
+ * public doors (forms, shares, sites) from fixtures, with no network. Inject
+ * it into the REAL client (`createPublicClient({ podUrl, fetch: pod.fetch })`)
+ * so everything above the wire — status handling, typed errors, the models —
+ * is the production path. For unit tests, a site's mock mode and a kit's
+ * states gallery.
+ *
+ * Wire behaviour mirrors the backend doors: the uniform 404 for every miss,
+ * the constant 202 on a submit, the site doors' query bounds (400), weak
+ * ETags with If-None-Match → 304. Like a browser against the real doors, a
+ * `credentials: "include"` request is refused (it rejects, as a CORS failure
+ * does); with `{ browser: true }` a non-safelisted request header is too.
+ *
+ *   tokens MOCK_TOKENS.form / .share / .site   the demo form, share and site
+ *   tokens MOCK_FAILURE_TOKENS.*                one failure on every door
+ *   anything else                               the uniform 404
+ *
+ * Pod-app sign-in (`@synap-core/sdk/connect`): `createMockAuthServer()`, see
+ * ./auth-server.ts.
+ */
+import type {
+  PublicCollectionPage,
+  PublicForm,
+  PublicRecord,
+  PublicRecordSummary,
+  PublicShare,
+  PublicSite,
+} from "../public/client";
+import { MOCK_FORM, MOCK_SHARE, MOCK_SITE, type MockSite } from "./fixtures";
+
+export { MOCK_FORM, MOCK_SHARE, MOCK_SITE };
+export type { MockCollection, MockSite } from "./fixtures";
+// Pod-app sign-in: a mock authorization server + Hub REST doors.
+export * from "./auth-server";
+
+/** A placeholder origin; never contacted. */
+export const MOCK_POD_URL = "https://mock.synap.invalid";
+
+export const MOCK_TOKENS = { form: "demo-form", share: "demo", site: "demo-site" } as const;
+
+/** The `Retry-After` the `rateLimitedRetryAfter` token sends. */
+export const MOCK_RETRY_AFTER_SEC = 30;
+
+/** Tokens that make every door answer one failure, so each UI state can be rendered. */
+export const MOCK_FAILURE_TOKENS = {
+  /** 429 with no `Retry-After` (what the pod's public doors send today). */
+  rateLimited: "mock-rate-limited",
+  /** 429 with `Retry-After: 30`. */
+  rateLimitedRetryAfter: "mock-rate-limited-retry-after",
+  /** 403 `public_doors_disabled`: the owner switched public pages off. */
+  doorsDisabled: "mock-doors-disabled",
+  /** 500. */
+  serverError: "mock-server-error",
+  /** 503 (a read: `pod_unreachable` / `server`; a submit: `unavailable`). */
+  unavailable: "mock-unavailable",
+  /** No answer: the fetch rejects (`network` / `pod_unreachable`). */
+  unreachable: "mock-unreachable",
+} as const;
+
+export interface MockPodOptions {
+  /** Forms by token (default: the demo form under `MOCK_TOKENS.form`). */
+  forms?: Record<string, PublicForm>;
+  /** Shares by token (default: the demo share under `MOCK_TOKENS.share`). */
+  shares?: Record<string, PublicShare>;
+  /** Sites by token (default: the demo site under `MOCK_TOKENS.site`). */
+  sites?: Record<string, MockSite>;
+  /** Refuse non-safelisted request headers, as a browser's CORS preflight would. */
+  browser?: boolean;
+}
+
+export interface MockRequest {
+  method: string;
+  url: string;
+  /** Lower-cased header names. */
+  headers: Record<string, string>;
+  credentials: RequestCredentials | undefined;
+}
+
+export interface MockSubmission {
+  token: string;
+  /** The parsed envelope (`fields`, `ticket`, `hp`, …). */
+  body: unknown;
+  /** The answer the mock gave. */
+  status: 202 | 422;
+}
+
+export interface MockPod {
+  podUrl: string;
+  fetch: typeof fetch;
+  /** Every request seen, in order (assert credentials and headers on it). */
+  requests: MockRequest[];
+  /** Every submit seen, in order. */
+  submissions: MockSubmission[];
+  /** Forget `requests` and `submissions`. */
+  reset(): void;
+}
+
+const NOT_FOUND = { error: "Not found" };
+const DOORS_DISABLED = {
+  error: "The owner has not turned on public pages and forms for this workspace.",
+  code: "public_doors_disabled",
+};
+/** Request headers a browser sends cross-origin without a preflight. */
+const SAFELISTED = new Set(["accept", "accept-language", "content-language", "content-type"]);
+/** The only request header the real doors allow on a preflight. */
+const PREFLIGHT_ALLOWED = new Set(["content-type"]);
+
+const PUBLIC_ID_RE = /^p_[A-Za-z0-9]{16}$/;
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SLUG_MAX_LENGTH = 96;
+const DIGITS = /^\d{1,9}$/;
+const SORT_TERM = /^(-?)([A-Za-z][A-Za-z0-9_]{0,63})$/;
+const MAX_OFFSET = 10_000;
+const MAX_LIMIT = 100;
+const MAX_SORT_KEYS = 3;
+const PUBLISHED_AT = "publishedAt";
+
+function json(status: number, body: unknown, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json", "Cache-Control": "no-cache", ...headers },
+  });
+}
+
+/** FNV-1a, 32 bits: a stable weak validator, no crypto needed. */
+function weakEtag(value: unknown): string {
+  let h = 0x811c9dc5;
+  for (const ch of JSON.stringify(value)) {
+    h ^= ch.charCodeAt(0);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `W/"${h.toString(16).padStart(8, "0")}"`;
+}
+
+function etagMatches(header: string | null, etag: string): boolean {
+  if (!header) return false;
+  if (header.trim() === "*") return true;
+  const strip = (t: string) => t.trim().replace(/^W\//, "");
+  return header.split(",").some((t) => strip(t) === strip(etag));
+}
+
+function failure(token: string): Response | "reject" | null {
+  switch (token) {
+    case MOCK_FAILURE_TOKENS.rateLimited:
+      return json(429, { error: "Too many requests", retryAfter: "5 minutes" });
+    case MOCK_FAILURE_TOKENS.rateLimitedRetryAfter:
+      return json(429, { error: "Too many requests" }, { "Retry-After": String(MOCK_RETRY_AFTER_SEC) });
+    case MOCK_FAILURE_TOKENS.doorsDisabled:
+      return json(403, DOORS_DISABLED);
+    case MOCK_FAILURE_TOKENS.serverError:
+      return json(500, { error: "Internal error" });
+    case MOCK_FAILURE_TOKENS.unavailable:
+      return json(503, { received: false });
+    case MOCK_FAILURE_TOKENS.unreachable:
+      return "reject";
+    default:
+      return null;
+  }
+}
+
+function summary(record: PublicRecord): PublicRecordSummary {
+  const { body: _body, ...rest } = record;
+  return rest;
+}
+
+function manifest(site: MockSite): PublicSite {
+  return {
+    ...(site.title !== undefined ? { title: site.title } : {}),
+    ...(site.description !== undefined ? { description: site.description } : {}),
+    publishedOn: site.publishedOn,
+    collections: Object.keys(site.collections)
+      .sort()
+      .map((key) => {
+        const c = site.collections[key];
+        return { key, count: c.records.length, sort: [...c.sort], pageSize: c.pageSize, addressing: c.addressing };
+      }),
+  };
+}
+
+type Sort = Array<{ key: string; desc: boolean }>;
+
+/** The door's `parseCollectionQuery`: the same bounds, the same 400s. */
+function parseQuery(params: URLSearchParams, c: { sort: string[]; pageSize: number }): { offset: number; limit: number; sort: Sort } | string {
+  for (const name of params.keys()) {
+    if (name === "embed") return "embed is not available";
+    if (name === "ref" || name.startsWith("ref[")) return "ref filter is not available";
+  }
+  const one = (name: string): string | undefined | null => {
+    const all = params.getAll(name);
+    return all.length === 0 ? undefined : all.length === 1 ? all[0] : null;
+  };
+  const rawOffset = one("offset");
+  if (rawOffset === null || (rawOffset !== undefined && !DIGITS.test(rawOffset))) return "invalid offset";
+  const offset = rawOffset === undefined ? 0 : Number(rawOffset);
+  if (offset > MAX_OFFSET) return "offset too large";
+  const rawLimit = one("limit");
+  if (rawLimit === null || (rawLimit !== undefined && !DIGITS.test(rawLimit))) return "invalid limit";
+  const limit = Math.min(MAX_LIMIT, Math.max(1, rawLimit === undefined ? c.pageSize : Number(rawLimit)));
+  const rawSort = one("sort");
+  if (rawSort === null) return "invalid sort";
+  const terms =
+    rawSort !== undefined ? rawSort.split(",") : c.sort.length > 0 ? [...c.sort] : [`-${PUBLISHED_AT}`];
+  if (terms.length > MAX_SORT_KEYS) return "invalid sort";
+  const allowed = new Set([PUBLISHED_AT, ...c.sort.map((s) => s.replace(/^-/, ""))]);
+  const sort: Sort = [];
+  for (const term of terms) {
+    const m = SORT_TERM.exec(term);
+    if (!m || !allowed.has(m[2]) || sort.some((s) => s.key === m[2])) return "invalid sort";
+    sort.push({ key: m[2], desc: m[1] === "-" });
+  }
+  return { offset, limit, sort };
+}
+
+/** jsonb-like order within a type (strings < numbers < booleans); a missing value sorts last. */
+function compareRecords(sort: Sort) {
+  const rank = (v: unknown) => (typeof v === "string" ? 0 : typeof v === "number" ? 1 : 2);
+  const valueOf = (r: PublicRecord, key: string) => (key === PUBLISHED_AT ? r.publishedOn : r.properties[key]);
+  return (a: PublicRecord, b: PublicRecord): number => {
+    for (const { key, desc } of sort) {
+      const va = valueOf(a, key);
+      const vb = valueOf(b, key);
+      if (va === undefined || vb === undefined) {
+        if (va !== vb) return va === undefined ? 1 : -1;
+        continue;
+      }
+      let d = rank(va) - rank(vb);
+      if (d === 0) d = va < vb ? -1 : va > vb ? 1 : 0;
+      if (d !== 0) return desc ? -d : d;
+    }
+    if (a.publishedOn !== b.publishedOn) return a.publishedOn < b.publishedOn ? 1 : -1;
+    return a.publicId < b.publicId ? -1 : a.publicId > b.publicId ? 1 : 0;
+  };
+}
+
+/** 200 with a weak ETag, or 304 when If-None-Match already holds it. */
+function cached(view: unknown, ifNoneMatch: string | null): Response {
+  const etag = weakEtag(view);
+  if (etagMatches(ifNoneMatch, etag)) {
+    return new Response(null, { status: 304, headers: { ETag: etag, "Cache-Control": "no-cache" } });
+  }
+  return json(200, view, { ETag: etag });
+}
+
+function siteDoor(site: MockSite, rest: string[], params: URLSearchParams, ifNoneMatch: string | null): Response {
+  if (rest.length === 0) return cached(manifest(site), ifNoneMatch);
+  if (rest[0] !== "collections" || rest.length > 3 || !Object.hasOwn(site.collections, rest[1])) {
+    return json(404, NOT_FOUND);
+  }
+  const c = site.collections[rest[1]];
+  if (rest.length === 2) {
+    const q = parseQuery(params, c);
+    if (typeof q === "string") return json(400, { error: q });
+    const sorted = [...c.records].sort(compareRecords(q.sort));
+    const page: PublicCollectionPage = {
+      items: sorted.slice(q.offset, q.offset + q.limit).map(summary),
+      total: sorted.length,
+      offset: q.offset,
+      limit: q.limit,
+    };
+    return cached(page, ifNoneMatch);
+  }
+  const address = rest[2];
+  const byPublicId = PUBLIC_ID_RE.test(address);
+  if (!byPublicId && !(address.length <= SLUG_MAX_LENGTH && SLUG_RE.test(address))) return json(404, NOT_FOUND);
+  const record = c.records.find((r) => (byPublicId ? r.publicId === address : r.slug === address));
+  if (!record) return json(404, NOT_FOUND);
+  if (params.has("embed")) return json(400, { error: "embed is not available" });
+  return cached(record, ifNoneMatch);
+}
+
+/** The door's 422 for answers that do not satisfy the form (required, enum). */
+function invalidKeys(form: PublicForm, body: unknown): string[] {
+  const fields = (body as { fields?: unknown } | null)?.fields;
+  if (typeof fields !== "object" || fields === null) return [];
+  const answers = fields as Record<string, unknown>;
+  return form.fields
+    .filter((f) => {
+      const v = answers[f.key];
+      if (v === undefined || v === "" || v === null) return f.required === true;
+      if (f.type === "boolean") return typeof v !== "boolean" || (f.required === true && v !== true);
+      const allowed = f.constraints?.enum;
+      return allowed !== undefined && !allowed.includes(String(v));
+    })
+    .map((f) => f.key);
+}
+
+export function createMockPod(options: MockPodOptions = {}): MockPod {
+  const forms = options.forms ?? { [MOCK_TOKENS.form]: MOCK_FORM };
+  const shares = options.shares ?? { [MOCK_TOKENS.share]: MOCK_SHARE };
+  const sites = options.sites ?? { [MOCK_TOKENS.site]: MOCK_SITE };
+  const requests: MockRequest[] = [];
+  const submissions: MockSubmission[] = [];
+
+  const mockFetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const request = typeof input === "object" && "method" in input ? input : null;
+    const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
+    const method = (init?.method ?? request?.method ?? "GET").toUpperCase();
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers ?? request?.headers).forEach((value, name) => {
+      headers[name.toLowerCase()] = value;
+    });
+    const credentials = init?.credentials ?? request?.credentials;
+    requests.push({ method, url: url.href, headers, credentials });
+
+    // What a browser does against the real doors (`Access-Control-Allow-Origin: *`).
+    if (credentials === "include") throw new TypeError("Failed to fetch: credentialed request to a public door");
+    if (options.browser) {
+      const preflighted = Object.keys(headers).filter((h) => !SAFELISTED.has(h) && !PREFLIGHT_ALLOWED.has(h));
+      if (preflighted.length > 0) throw new TypeError(`Failed to fetch: preflight refuses ${preflighted.join(", ")}`);
+    }
+
+    const m = url.pathname.match(/^\/api\/hub\/public\/(forms|shares|sites)\/(.+)$/);
+    if (!m) return json(404, NOT_FOUND);
+    let segments: string[];
+    try {
+      segments = m[2].split("/").map(decodeURIComponent);
+    } catch {
+      return json(404, NOT_FOUND);
+    }
+    const [token, ...rest] = segments;
+    const failed = failure(token);
+    if (failed === "reject") throw new TypeError("Failed to fetch: mock pod unreachable");
+    if (failed) return failed;
+
+    const door = m[1];
+    if (door === "forms" && method === "POST" && rest.length === 0) {
+      let body: unknown = null;
+      try {
+        body = JSON.parse(typeof init?.body === "string" ? init.body : "null");
+      } catch {
+        body = null;
+      }
+      const form = Object.hasOwn(forms, token) ? forms[token] : undefined;
+      const invalid = form ? invalidKeys(form, body) : [];
+      const status = invalid.length > 0 ? 422 : 202;
+      submissions.push({ token, body, status });
+      return status === 422 ? json(422, { received: false, invalid }) : json(202, { received: true });
+    }
+    if (method !== "GET") return json(404, NOT_FOUND);
+    if (door === "forms" && rest.length === 0 && Object.hasOwn(forms, token)) return json(200, forms[token]);
+    if (door === "shares" && rest.length === 0 && Object.hasOwn(shares, token)) return json(200, shares[token]);
+    if (door === "sites" && Object.hasOwn(sites, token)) {
+      return siteDoor(sites[token], rest, url.searchParams, headers["if-none-match"] ?? null);
+    }
+    return json(404, NOT_FOUND);
+  };
+
+  return {
+    podUrl: MOCK_POD_URL,
+    fetch: mockFetch as typeof fetch,
+    requests,
+    submissions,
+    reset() {
+      requests.length = 0;
+      submissions.length = 0;
+    },
+  };
+}

package/src/public.ts

@@ -1,262 +0,0 @@
-/**
- * @synap-core/sdk/public — a thin, CREDENTIALLESS fetch client for the pod's
- * public doors (Sites W3/W4):
- *
- *   GET  <pod>/api/hub/public/shares/:token   read a published share
- *   GET  <pod>/api/hub/public/forms/:token    a form's public definition + ticket
- *   POST <pod>/api/hub/public/forms/:token    a guest submission (202 / 422 / 503)
- *
- * Invariants (pinned by src/__tests__/public.guard.test.ts):
- *  - every request is `credentials: 'omit'`; no Authorization / Cookie / session
- *    header is ever set (only `Accept`, and `Content-Type` on POST);
- *  - imports NOTHING (no tRPC, superjson, zod, authenticated client);
- *  - the uniform 404 is one typed `not_found` (revoked / expired / unknown are
- *    indistinguishable by design); the constant 202 is `{ received: true }`;
- *  - a submit has six typed non-success outcomes (`invalid` with the field keys,
- *    `retry`, `unavailable`, `rate_limited`, `network`, `server`); a 422 `retry`
- *    (ticket missing / too early / stale) is retried ONCE automatically: the
- *    form is fetched again, `minSubmitMs` is waited out (capped) and the same
- *    submission (same idempotency key) is resent;
- *  - server detail (bodies, messages) never reaches the caller.
- *
- * DRIFT RISK: the response types below are HAND-WRITTEN from the backend wire
- * contracts (synap-backend: `_codecs/public-shares.ts` PublicShareResponseSchema,
- * `services/forms/form-definition.ts` publicFormView + the public-forms route,
- * `SubmissionEnvelopeSchema`). `src/__tests__/fixtures.ts` copies those shapes;
- * when the backend changes, update both.
- */
-
-// ── Wire types (hand-written; see DRIFT RISK) ────────────────────────────────
-
-export interface PublicShare {
-  resourceType: "entity";
-  /** Present only when the publisher allowlisted `title`. */
-  title?: string;
-  properties: Record<string, string | number | boolean>;
-  body: { format: "markdown"; content: string } | null;
-  /** Publication day, YYYY-MM-DD. */
-  publishedOn: string;
-}
-
-export type PublicFormFieldType =
-  | "text"
-  | "richtext"
-  | "email"
-  | "phone"
-  | "url"
-  | "number"
-  | "boolean"
-  | "date"
-  | "enum";
-
-export interface PublicFormField {
-  key: string;
-  label: string;
-  type: PublicFormFieldType;
-  required?: true;
-  help?: string;
-  constraints?: {
-    enum?: string[];
-    min?: number;
-    max?: number;
-    maxLength?: number;
-  };
-}
-
-export interface PublicForm {
-  title: string;
-  fields: PublicFormField[];
-  successMessage: string;
-  /** The envelope key of the honeypot (always "hp" today). */
-  honeypotField: string;
-  /** Time-to-submit ticket, minted by this GET; pass it back to `submitForm`. */
-  ticket: string;
-  /**
-   * The POST is refused with `retry` until this many ms have passed since the
-   * ticket was minted. Hold the submit button until then. 0 = no wait.
-   */
-  minSubmitMs: number;
-  captcha: { required: true; siteKey: string | null } | { required: false };
-}
-
-// ── Results ──────────────────────────────────────────────────────────────────
-
-/** `not_found` is the uniform 404 (never says revoked vs expired vs unknown). */
-export type PublicReadError = "not_found" | "rate_limited" | "network" | "server";
-/** A submit never yields `not_found`: the door answers 202 to everything. */
-export type PublicSubmitError =
-  | "invalid"
-  /** The ticket was refused, even after the one automatic retry. */
-  | "retry"
-  /** 503: the pod failed to file it; resubmitting with the same key is safe. */
-  | "unavailable"
-  | "rate_limited"
-  | "network"
-  | "server";
-
-export type PublicResult<T, E extends string = PublicReadError> =
-  | { ok: true; data: T }
-  | { ok: false; error: E };
-
-export type SubmitResult =
-  | { ok: true; received: true }
-  /** 422: the answers do not satisfy the form. `fields` are field keys; empty = not a submission. */
-  | { ok: false; error: "invalid"; fields: string[] }
-  | { ok: false; error: Exclude<PublicSubmitError, "invalid"> };
-
-export interface SubmitFormInput {
-  /** Answers keyed by the form's field `key`s. */
-  fields: Record<string, unknown>;
-  /** The `ticket` from `getForm` (waiting out the form's min time is the caller's job). */
-  ticket?: string;
-  /** Turnstile-style token, when `captcha.required`. */
-  captchaToken?: string;
-  /** Optional replay key; a repeated key collapses onto one submission. */
-  idempotencyKey?: string;
-}
-
-export interface PublicClientOptions {
-  /** Pod origin, e.g. `https://you.synap.live` (a trailing slash is ignored). */
-  podUrl: string;
-  /** Injectable fetch; defaults to the global one. */
-  fetch?: typeof fetch;
-  /** Injectable wait (tests); defaults to `setTimeout`. */
-  sleep?: (ms: number) => Promise<void>;
-}
-
-export interface PublicClient {
-  readShare(token: string): Promise<PublicResult<PublicShare>>;
-  getForm(token: string): Promise<PublicResult<PublicForm>>;
-  submitForm(token: string, input: SubmitFormInput): Promise<SubmitResult>;
-}
-
-/** The honeypot envelope key the door reads. Always sent empty. */
-const HONEYPOT_KEY = "hp";
-/** Longest wait the automatic ticket retry will sit out, whatever the pod says. */
-const MAX_TICKET_WAIT_MS = 10_000;
-const MAX_INVALID_KEYS = 100;
-const MAX_KEY_LENGTH = 200;
-
-function waitMs(form: unknown): number {
-  const n = (form as { minSubmitMs?: unknown } | null)?.minSubmitMs;
-  return typeof n === "number" && Number.isFinite(n) && n > 0
-    ? Math.min(n, MAX_TICKET_WAIT_MS)
-    : 0;
-}
-
-/** A 422 body -> outcome. Only field keys survive; anything else is dropped. */
-function parse422(body: unknown): { retry: true } | { fields: string[] } | null {
-  if (typeof body !== "object" || body === null) return null;
-  const b = body as { retry?: unknown; invalid?: unknown };
-  if (b.retry === true) return { retry: true };
-  if (!Array.isArray(b.invalid)) return null;
-  return {
-    fields: b.invalid
-      .filter((k): k is string => typeof k === "string" && k.length <= MAX_KEY_LENGTH)
-      .slice(0, MAX_INVALID_KEYS),
-  };
-}
-
-function classify(status: number): PublicReadError {
-  if (status === 404) return "not_found";
-  if (status === 429) return "rate_limited";
-  return "server";
-}
-
-export function createPublicClient(opts: PublicClientOptions): PublicClient {
-  const base = `${opts.podUrl.replace(/\/+$/, "")}/api/hub/public`;
-  const doFetch = (): typeof fetch => {
-    const f = opts.fetch ?? globalThis.fetch;
-    if (!f) throw new Error("No fetch available: pass `fetch` to createPublicClient");
-    return f;
-  };
-  const url = (resource: "shares" | "forms", token: string) =>
-    `${base}/${resource}/${encodeURIComponent(token)}`;
-
-  async function send(
-    target: string,
-    init: { method: "GET" | "POST"; body?: string }
-  ): Promise<Response | null> {
-    try {
-      return await doFetch()(target, {
-        method: init.method,
-        credentials: "omit",
-        headers:
-          init.method === "POST"
-            ? { "Content-Type": "application/json" }
-            : { Accept: "application/json" },
-        ...(init.body !== undefined ? { body: init.body } : {}),
-      });
-    } catch {
-      return null;
-    }
-  }
-
-  async function getJson<T>(
-    resource: "shares" | "forms",
-    token: string
-  ): Promise<PublicResult<T>> {
-    const res = await send(url(resource, token), { method: "GET" });
-    if (!res) return { ok: false, error: "network" };
-    if (res.status !== 200) return { ok: false, error: classify(res.status) };
-    try {
-      return { ok: true, data: (await res.json()) as T };
-    } catch {
-      return { ok: false, error: "server" };
-    }
-  }
-
-  const sleep =
-    opts.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
-
-  async function postOnce(
-    token: string,
-    input: SubmitFormInput,
-    ticket: string | undefined
-  ): Promise<{ retry: true } | { retry: false; result: SubmitResult }> {
-    const body: Record<string, unknown> = {
-      fields: input.fields,
-      [HONEYPOT_KEY]: "",
-    };
-    if (ticket !== undefined) body.ticket = ticket;
-    if (input.captchaToken !== undefined) body.captchaToken = input.captchaToken;
-    if (input.idempotencyKey !== undefined) body.idempotencyKey = input.idempotencyKey;
-    const res = await send(url("forms", token), {
-      method: "POST",
-      body: JSON.stringify(body),
-    });
-    const done = (result: SubmitResult) => ({ retry: false as const, result });
-    if (!res) return done({ ok: false, error: "network" });
-    if (res.status === 202) return done({ ok: true, received: true });
-    if (res.status === 422) {
-      let parsed: ReturnType<typeof parse422> = null;
-      try {
-        parsed = parse422(await res.json());
-      } catch {
-        parsed = null;
-      }
-      if (!parsed) return done({ ok: false, error: "server" });
-      if ("retry" in parsed) return { retry: true };
-      return done({ ok: false, error: "invalid", fields: parsed.fields });
-    }
-    if (res.status === 503) return done({ ok: false, error: "unavailable" });
-    if (res.status === 429) return done({ ok: false, error: "rate_limited" });
-    return done({ ok: false, error: "server" });
-  }
-
-  return {
-    readShare: (token) => getJson<PublicShare>("shares", token),
-    getForm: (token) => getJson<PublicForm>("forms", token),
-    async submitForm(token, input) {
-      const first = await postOnce(token, input, input.ticket);
-      if (!first.retry) return first.result;
-      // Ticket refused: fetch the form again (a fresh ticket + the wait), hold
-      // for it, resubmit once with the same idempotency key.
-      const fresh = await getJson<PublicForm>("forms", token);
-      if (!fresh.ok) return { ok: false, error: "retry" };
-      await sleep(waitMs(fresh.data));
-      const second = await postOnce(token, input, fresh.data.ticket);
-      return second.retry ? { ok: false, error: "retry" } : second.result;
-    },
-  };
-}