@synap-core/sdk 1.1.0 → 1.2.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;
-    },
-  };
-}