@synap-core/sdk 1.1.0 → 1.3.0

package/src/public/client.ts

@@ -0,0 +1,579 @@
+/**
+ * @synap-core/sdk/public — a thin, CREDENTIALLESS fetch client for the pod's
+ * public doors (Sites W3/W4, collection door C1a/C1b):
+ *
+ *   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)
+ *   GET  <pod>/api/hub/public/sites/:token                          a site manifest
+ *   GET  <pod>/api/hub/public/sites/:token/collections/:key         a page of records
+ *   GET  <pod>/api/hub/public/sites/:token/collections/:key/:slugOrPublicId  a record
+ *
+ * Invariants (pinned by src/__tests__/public.guard.test.ts):
+ *  - every request is `credentials: 'omit'`; no Authorization / Cookie / session
+ *    header is ever set (only `Accept`, `If-None-Match` on a site revalidation,
+ *    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`, `_codecs/public-sites.ts` + the bounds in
+ * `services/sharing/public-site-read.ts` parseCollectionQuery).
+ * `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 };
+}
+
+/** A published value: a publish-time snapshot, scalars only (C1b). */
+export type PublicValue = string | number | boolean;
+
+export interface PublicSiteCollection {
+  /** The collection key (a profile slug); pass it to `listCollection`. */
+  key: string;
+  /** Live published records in it. */
+  count: number;
+  /** The default sort keys (`-` = descending). */
+  sort: string[];
+  /** The default page size. */
+  pageSize: number;
+  /** How a record of this collection is addressed in URLs. */
+  addressing: "slug" | "publicId";
+}
+
+/** A published site's manifest. */
+export interface PublicSite {
+  /** Present only when the owner's policy publishes `title`. */
+  title?: string;
+  /** Present only when the owner's policy publishes `description`. */
+  description?: string;
+  /** Day the site went live, YYYY-MM-DD. */
+  publishedOn: string;
+  collections: PublicSiteCollection[];
+}
+
+/** One published record as a list item (no body). */
+export interface PublicRecordSummary {
+  collection: string;
+  /** The stable public address: `p_` + 16 random base62 chars. */
+  publicId: string;
+  /** The record's slug in its collection, or null. */
+  slug: string | null;
+  /** Present only when the owner's policy publishes `title`. */
+  title?: string;
+  properties: Record<string, PublicValue>;
+  /** Publication day, YYYY-MM-DD. */
+  publishedOn: string;
+}
+
+export interface PublicCollectionPage {
+  items: PublicRecordSummary[];
+  /** Live published records in the collection. */
+  total: number;
+  offset: number;
+  limit: number;
+}
+
+/** One published record, with its pinned body. */
+export interface PublicRecord extends PublicRecordSummary {
+  body: { format: "markdown"; content: string } | null;
+}
+
+/** The collection door's query bounds (backend `parseCollectionQuery`). */
+export const SITE_MAX_OFFSET = 10_000;
+export const SITE_MAX_LIMIT = 100;
+export const SITE_MAX_SORT_KEYS = 3;
+/** The sort key every collection accepts, besides its configured ones. */
+export const SITE_PUBLISHED_AT_SORT = "publishedAt";
+
+// ── Results ──────────────────────────────────────────────────────────────────
+
+/** `not_found` is the uniform 404 (never says revoked vs expired vs unknown). */
+export type PublicReadError =
+  | "not_found"
+  | "rate_limited"
+  /** The owner has not turned public pages/forms on for this workspace. */
+  | "doors_disabled"
+  | "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"
+  /** The owner has not turned public pages/forms on for this workspace. */
+  | "doors_disabled"
+  | "network"
+  | "server";
+
+/**
+ * A site read's failure. `not_found` is the uniform 404 (an unknown, revoked
+ * or unpublished site, collection or record are indistinguishable).
+ */
+export type PublicSiteError =
+  | "not_found"
+  | "rate_limited"
+  /** The site is live but the owner switched its space's public pages off. */
+  | "doors_disabled"
+  /** 400: the query is out of bounds or names a sort key the collection does not offer. */
+  | "bad_request"
+  /** No answer (network, DNS, CORS) or a gateway 502/503/504. */
+  | "pod_unreachable"
+  | "server";
+
+/**
+ * A failure. `rate_limited` carries `retryAfterSec` only when the response
+ * had a `Retry-After` header the caller can read (see README: the pod's public
+ * doors do not send one today, and a browser cannot read it cross-origin).
+ */
+export type PublicFailure<E extends string> = E extends "rate_limited"
+  ? { ok: false; error: E; retryAfterSec?: number }
+  : { ok: false; error: E };
+
+export type PublicResult<T, E extends string = PublicReadError> =
+  | { ok: true; data: T }
+  | PublicFailure<E>;
+
+/** A site read. `etag` is the door's weak validator, for `ifNoneMatch`. */
+export type PublicSiteResult<T> =
+  | { ok: true; data: T; etag: string | null }
+  | PublicFailure<PublicSiteError>;
+
+/** 304: what the caller holds for `ifNoneMatch` is still current. */
+export interface PublicNotModified {
+  ok: true;
+  notModified: true;
+  etag: string;
+}
+
+/**
+ * Revalidate with the ETag of an earlier answer. SERVER-SIDE ONLY: the public
+ * doors allow no request header but `Content-Type` cross-origin, so a browser
+ * fails the preflight (→ `pod_unreachable`). Browsers revalidate on their own
+ * through their HTTP cache (`Cache-Control: no-cache` + ETag).
+ */
+export interface Revalidate {
+  ifNoneMatch: string;
+}
+
+export interface CollectionQuery {
+  /** 0..10 000 (default 0). Anything else is `bad_request`, without a request. */
+  offset?: number;
+  /** An integer, clamped to 1..100 (default: the collection's page size). */
+  limit?: number;
+  /**
+   * ≤ 3 keys, `-` = descending, out of the collection's `sort` keys and
+   * `publishedAt` (default: the collection's sort). A string is comma-split.
+   */
+  sort?: string | readonly string[];
+}
+
+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[] }
+  | PublicFailure<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>;
+
+  /** A published site's manifest: its metadata and configured collections. */
+  getSite(siteToken: string): Promise<PublicSiteResult<PublicSite>>;
+  getSite(
+    siteToken: string,
+    opts: Revalidate
+  ): Promise<PublicSiteResult<PublicSite> | PublicNotModified>;
+
+  /** One page of a collection's live published records (no bodies). */
+  listCollection(
+    siteToken: string,
+    key: string,
+    query?: CollectionQuery
+  ): Promise<PublicSiteResult<PublicCollectionPage>>;
+  listCollection(
+    siteToken: string,
+    key: string,
+    query: CollectionQuery & Revalidate
+  ): Promise<PublicSiteResult<PublicCollectionPage> | PublicNotModified>;
+
+  /** One record by its public id (`p_…`) or its slug, with its pinned body. */
+  getRecord(
+    siteToken: string,
+    key: string,
+    slugOrPublicId: string
+  ): Promise<PublicSiteResult<PublicRecord>>;
+  getRecord(
+    siteToken: string,
+    key: string,
+    slugOrPublicId: string,
+    opts: Revalidate
+  ): Promise<PublicSiteResult<PublicRecord> | PublicNotModified>;
+}
+
+/** 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),
+  };
+}
+
+/** The one refusal body's machine code (see `PUBLIC_DOORS_DISABLED_BODY` on the pod). */
+const DOORS_DISABLED_CODE = "public_doors_disabled";
+
+function isDoorsDisabledBody(body: unknown): boolean {
+  return (
+    typeof body === "object" &&
+    body !== null &&
+    (body as { code?: unknown }).code === DOORS_DISABLED_CODE
+  );
+}
+
+/** A non-200 answer of a read door (no answer at all is the caller's `network`). */
+function classify(status: number, body: unknown): Exclude<PublicReadError, "network"> {
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  if (status === 403 && isDoorsDisabledBody(body)) return "doors_disabled";
+  return "server";
+}
+
+function classifySite(status: number, body: unknown): PublicSiteError {
+  if (status === 400) return "bad_request";
+  if (status === 502 || status === 503 || status === 504) return "pod_unreachable";
+  return classify(status, body);
+}
+
+/** Longest `Retry-After` passed on, whatever the response says. */
+const MAX_RETRY_AFTER_SEC = 86_400;
+
+/** `Retry-After` (delta-seconds or an HTTP date) in whole seconds, else undefined. */
+function retryAfterSec(res: Response): number | undefined {
+  const raw = res.headers.get("retry-after")?.trim();
+  if (!raw) return undefined;
+  let sec: number;
+  if (/^\d+$/.test(raw)) {
+    sec = Number(raw);
+  } else {
+    const at = Date.parse(raw);
+    if (Number.isNaN(at)) return undefined;
+    sec = Math.ceil((at - Date.now()) / 1000);
+  }
+  return Math.min(Math.max(0, sec), MAX_RETRY_AFTER_SEC);
+}
+
+/** A failure; `rate_limited` picks up the response's `Retry-After`, if any. */
+function fail<E extends string>(error: E, res: Response | null): PublicFailure<E> {
+  const sec = error === "rate_limited" && res ? retryAfterSec(res) : undefined;
+  return (sec === undefined ? { ok: false, error } : { ok: false, error, retryAfterSec: sec }) as PublicFailure<E>;
+}
+
+async function readBody(res: Response): Promise<unknown> {
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One URL path segment, or null when it could not stay one: empty, `.` and
+ * `..` would be resolved away by the URL parser and reach ANOTHER door (e.g.
+ * collection `..` is the manifest), typed as the wrong shape.
+ */
+function segment(raw: string): string | null {
+  if (typeof raw !== "string" || raw === "" || raw === "." || raw === "..") return null;
+  return encodeURIComponent(raw);
+}
+
+/** A sort term as the door parses it (`-` = descending). */
+const SORT_TERM = /^(-?)([A-Za-z][A-Za-z0-9_]{0,63})$/;
+
+/**
+ * The collection query string, checked against the door's static bounds so a
+ * request that can only be a 400 is never sent. null = `bad_request`. Whether
+ * a sort key is one the collection offers is the door's call.
+ */
+function collectionSearch(q: CollectionQuery | undefined): string | null {
+  const params: string[] = [];
+  if (q?.offset !== undefined) {
+    if (!Number.isInteger(q.offset) || q.offset < 0 || q.offset > SITE_MAX_OFFSET) return null;
+    params.push(`offset=${q.offset}`);
+  }
+  if (q?.limit !== undefined) {
+    if (!Number.isInteger(q.limit) || q.limit < 0) return null;
+    params.push(`limit=${Math.min(SITE_MAX_LIMIT, Math.max(1, q.limit))}`);
+  }
+  if (q?.sort !== undefined) {
+    const terms = typeof q.sort === "string" ? q.sort.split(",") : [...q.sort];
+    if (terms.length > SITE_MAX_SORT_KEYS) return null;
+    const keys = new Set<string>();
+    for (const term of terms) {
+      const m = SORT_TERM.exec(term);
+      if (!m || keys.has(m[2])) return null;
+      keys.add(m[2]);
+    }
+    if (terms.length > 0) params.push(`sort=${terms.join(",")}`);
+  }
+  return params.length > 0 ? `?${params.join("&")}` : "";
+}
+
+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; ifNoneMatch?: string }
+  ): Promise<Response | null> {
+    try {
+      return await doFetch()(target, {
+        method: init.method,
+        credentials: "omit",
+        headers:
+          init.method === "POST"
+            ? { "Content-Type": "application/json" }
+            : init.ifNoneMatch
+              ? { Accept: "application/json", "If-None-Match": init.ifNoneMatch }
+              : { 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 fail(classify(res.status, await readBody(res)), res);
+    try {
+      return { ok: true, data: (await res.json()) as T };
+    } catch {
+      return { ok: false, error: "server" };
+    }
+  }
+
+  /** A site door read. `path` null = a segment that cannot be addressed: the uniform miss. */
+  async function siteRead<T>(
+    path: string | null,
+    ifNoneMatch: string | undefined
+  ): Promise<PublicSiteResult<T> | PublicNotModified> {
+    if (path === null) return { ok: false, error: "not_found" };
+    const revalidate = typeof ifNoneMatch === "string" && ifNoneMatch !== "" ? ifNoneMatch : undefined;
+    const res = await send(`${base}/sites/${path}`, { method: "GET", ifNoneMatch: revalidate });
+    if (!res) return { ok: false, error: "pod_unreachable" };
+    const etag = res.headers.get("etag");
+    if (res.status === 304 && revalidate !== undefined) {
+      return { ok: true, notModified: true, etag: etag ?? revalidate };
+    }
+    if (res.status !== 200) return fail(classifySite(res.status, await readBody(res)), res);
+    try {
+      return { ok: true, data: (await res.json()) as T, etag };
+    } catch {
+      return { ok: false, error: "server" };
+    }
+  }
+
+  function getSite(siteToken: string, opts?: Partial<Revalidate>) {
+    return siteRead<PublicSite>(segment(siteToken), opts?.ifNoneMatch);
+  }
+
+  async function listCollection(
+    siteToken: string,
+    key: string,
+    query?: CollectionQuery & Partial<Revalidate>
+  ): Promise<PublicSiteResult<PublicCollectionPage> | PublicNotModified> {
+    const token = segment(siteToken);
+    const k = segment(key);
+    if (token === null || k === null) return { ok: false, error: "not_found" };
+    const search = collectionSearch(query);
+    if (search === null) return { ok: false, error: "bad_request" };
+    return siteRead(`${token}/collections/${k}${search}`, query?.ifNoneMatch);
+  }
+
+  function getRecord(
+    siteToken: string,
+    key: string,
+    slugOrPublicId: string,
+    opts?: Partial<Revalidate>
+  ) {
+    const parts = [segment(siteToken), segment(key), segment(slugOrPublicId)];
+    const path = parts.every((p) => p !== null)
+      ? `${parts[0]}/collections/${parts[1]}/${parts[2]}`
+      : null;
+    return siteRead<PublicRecord>(path, opts?.ifNoneMatch);
+  }
+
+  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(fail("rate_limited", res));
+    if (res.status === 403 && isDoorsDisabledBody(await readBody(res))) {
+      return done({ ok: false, error: "doors_disabled" });
+    }
+    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;
+    },
+    getSite: getSite as PublicClient["getSite"],
+    listCollection: listCollection as PublicClient["listCollection"],
+    getRecord: getRecord as PublicClient["getRecord"],
+  };
+}