@synap-core/sdk 1.0.0 → 1.2.0

package/README.md

@@ -17,7 +17,7 @@ import { createSynapClient } from "@synap-core/sdk";
 
 const synap = createSynapClient({
   podUrl: "https://your-pod.synap.live", // your data pod URL
-  apiKey: "sk_live_...", // from Workspace → Settings → API Keys
+  sessionToken: "...", // Kratos session token (see Authentication)
   workspaceId: "ws_...", // your workspace ID
 });
 
@@ -35,23 +35,29 @@ await synap.entities.create.mutate({
 
 ## Authentication
 
-**API key (server-side / external apps)**
+**Session token (non-browser clients: extensions, CLIs, mobile)**
 
 ```typescript
 const synap = createSynapClient({
   podUrl: "https://your-pod.synap.live",
-  apiKey: "sk_live_...", // Bearer token — generate in workspace settings
+  sessionToken: "...", // Kratos session token from an API (native) login flow
   workspaceId: "ws_...",
 });
 ```
 
+**`apiKey` is for the local-mode token only.** It sends `Authorization: Bearer`
+to `/trpc`, which on a real pod is behind Ory session auth and refuses hub / user
+API keys (`synap_hub_*`, `synap_user_*`). `createSynapClient` throws early if you
+pass one. For hub / user API keys use
+`@synap-core/hub-rest-client` against `/api/hub/*`.
+
 **Session cookie (browser — after Kratos login)**
 
 ```typescript
 const synap = createSynapClient({
   podUrl: "https://your-pod.synap.live",
   workspaceId: "ws_...",
-  // omit apiKey — credentials: "include" is set automatically
+  // omit apiKey/sessionToken — credentials: "include" is set automatically
 });
 ```
 
@@ -64,6 +70,78 @@ type EntityListInput = RouterInputs["entities"]["list"];
 type EntityListOutput = RouterOutputs["entities"]["list"];
 ```
 
+## Public doors (no credentials): `@synap-core/sdk/public`
+
+A tiny, dependency-free fetch client for the pod's credentialless public doors
+(published shares, guest forms, published sites). It never sends credentials
+(`credentials: 'omit'`, no Authorization/Cookie) and works from any origin, so it
+is safe in a public site. The same entry ships the framework-free view-models a
+site renders (no React): `toFieldModels` / `validate` / `submitFailure` (forms),
+`toSharePageModel`, `parseSafeMarkdown` (data, never HTML), `formatPublicValue`,
+`toCollectionPageModel` / `pageQuery` / `parsePageParam`, `toRecordViewModel`.
+
+```typescript
+import { createPublicClient } from "@synap-core/sdk/public";
+
+const pub = createPublicClient({ podUrl: "https://your-pod.synap.live" });
+
+const share = await pub.readShare(token); // { ok: true, data } | { ok: false, error }
+const form = await pub.getForm(formToken); // fields, honeypotField, ticket, captcha
+const sent = await pub.submitForm(formToken, {
+  fields: { email: "a@b.co" },
+  ticket: form.ok ? form.data.ticket : undefined,
+  captchaToken, // when form.data.captcha.required
+});
+```
+
+Errors are typed: `not_found` (the uniform 404: unknown, revoked and expired are
+indistinguishable), `rate_limited`, `network`, `server`. A submit always answers
+`{ ok: true, received: true }` on the pod's constant 202; the pod silently drops
+too-fast, honeypot, captcha-failed and over-cap submissions, so wait out the form's
+minimum time before submitting. Pass `fetch` to inject your own.
+
+### Published sites (1.2.0)
+
+```typescript
+const site = await pub.getSite(siteToken); // manifest: title?, collections[{ key, count, sort, pageSize, addressing }]
+const page = await pub.listCollection(siteToken, "paper", { offset: 20, limit: 10, sort: ["-year"] });
+const rec = await pub.getRecord(siteToken, "paper", "on-graphs"); // slug or "p_…" public id
+```
+
+Site reads fail with `not_found` (one uniform miss for token, collection and
+record), `doors_disabled`, `bad_request` (sent only when the door says 400: the
+SDK refuses out-of-bounds `offset`/`limit`/`sort` locally, without a request),
+`rate_limited`, `pod_unreachable` (no answer, or a 502/503/504) or `server`.
+`rate_limited` carries `retryAfterSec` only when the response has a readable
+`Retry-After`; the pod's public doors do not send one today, so expect
+`undefined`. Successes carry the door's weak `etag`; a server may revalidate with
+`{ ifNoneMatch: etag }` and get `{ ok: true, notModified: true }` on a 304. Do not
+pass `ifNoneMatch` from a browser: the doors allow no cross-origin request header
+but `Content-Type`, so the preflight fails (browsers revalidate on their own).
+
+## Mock pod: `@synap-core/sdk/testing`
+
+A fake `fetch` that answers the public doors (forms, shares, sites) from fixtures,
+with no network, for tests, a site's mock mode and a states gallery. Inject it
+into the real client so everything above the wire is the production path:
+
+```typescript
+import { createPublicClient } from "@synap-core/sdk/public";
+import { createMockPod, MOCK_TOKENS, MOCK_FAILURE_TOKENS } from "@synap-core/sdk/testing";
+
+const pod = createMockPod(); // or createMockPod({ sites: { mine: { … } } })
+const pub = createPublicClient({ podUrl: pod.podUrl, fetch: pod.fetch });
+
+await pub.listCollection(MOCK_TOKENS.site, "paper", { offset: 5 }); // demo site, 12 papers
+await pub.getSite(MOCK_FAILURE_TOKENS.rateLimited); // { ok: false, error: "rate_limited" }
+pod.requests; // every request (method, url, headers, credentials)
+```
+
+It mirrors the doors: the uniform 404, the constant 202 (422 for missing
+required or off-list answers), the collection query bounds, weak ETags and 304.
+A `credentials: "include"` request rejects, as it would in a browser;
+`createMockPod({ browser: true })` also rejects headers a CORS preflight refuses.
+
 ## React
 
 For React apps use [`@synap-core/react`](https://www.npmjs.com/package/@synap-core/react) which wraps this SDK with TanStack Query hooks.

package/dist/client-C5sF20f1.d.cts

@@ -0,0 +1,253 @@
+/**
+ * @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.
+ */
+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;
+}
+type PublicFormFieldType = "text" | "richtext" | "email" | "phone" | "url" | "number" | "boolean" | "date" | "enum";
+interface PublicFormField {
+    key: string;
+    label: string;
+    type: PublicFormFieldType;
+    required?: true;
+    help?: string;
+    constraints?: {
+        enum?: string[];
+        min?: number;
+        max?: number;
+        maxLength?: number;
+    };
+}
+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). */
+type PublicValue = string | number | boolean;
+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. */
+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). */
+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;
+}
+interface PublicCollectionPage {
+    items: PublicRecordSummary[];
+    /** Live published records in the collection. */
+    total: number;
+    offset: number;
+    limit: number;
+}
+/** One published record, with its pinned body. */
+interface PublicRecord extends PublicRecordSummary {
+    body: {
+        format: "markdown";
+        content: string;
+    } | null;
+}
+/** The collection door's query bounds (backend `parseCollectionQuery`). */
+declare const SITE_MAX_OFFSET = 10000;
+declare const SITE_MAX_LIMIT = 100;
+declare const SITE_MAX_SORT_KEYS = 3;
+/** The sort key every collection accepts, besides its configured ones. */
+declare const SITE_PUBLISHED_AT_SORT = "publishedAt";
+/** `not_found` is the uniform 404 (never says revoked vs expired vs unknown). */
+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. */
+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).
+ */
+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).
+ */
+type PublicFailure<E extends string> = E extends "rate_limited" ? {
+    ok: false;
+    error: E;
+    retryAfterSec?: number;
+} : {
+    ok: false;
+    error: E;
+};
+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`. */
+type PublicSiteResult<T> = {
+    ok: true;
+    data: T;
+    etag: string | null;
+} | PublicFailure<PublicSiteError>;
+/** 304: what the caller holds for `ifNoneMatch` is still current. */
+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).
+ */
+interface Revalidate {
+    ifNoneMatch: string;
+}
+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[];
+}
+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">>;
+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;
+}
+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>;
+}
+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>;
+}
+declare function createPublicClient(opts: PublicClientOptions): PublicClient;
+
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };

package/dist/client-C5sF20f1.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @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.
+ */
+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;
+}
+type PublicFormFieldType = "text" | "richtext" | "email" | "phone" | "url" | "number" | "boolean" | "date" | "enum";
+interface PublicFormField {
+    key: string;
+    label: string;
+    type: PublicFormFieldType;
+    required?: true;
+    help?: string;
+    constraints?: {
+        enum?: string[];
+        min?: number;
+        max?: number;
+        maxLength?: number;
+    };
+}
+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). */
+type PublicValue = string | number | boolean;
+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. */
+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). */
+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;
+}
+interface PublicCollectionPage {
+    items: PublicRecordSummary[];
+    /** Live published records in the collection. */
+    total: number;
+    offset: number;
+    limit: number;
+}
+/** One published record, with its pinned body. */
+interface PublicRecord extends PublicRecordSummary {
+    body: {
+        format: "markdown";
+        content: string;
+    } | null;
+}
+/** The collection door's query bounds (backend `parseCollectionQuery`). */
+declare const SITE_MAX_OFFSET = 10000;
+declare const SITE_MAX_LIMIT = 100;
+declare const SITE_MAX_SORT_KEYS = 3;
+/** The sort key every collection accepts, besides its configured ones. */
+declare const SITE_PUBLISHED_AT_SORT = "publishedAt";
+/** `not_found` is the uniform 404 (never says revoked vs expired vs unknown). */
+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. */
+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).
+ */
+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).
+ */
+type PublicFailure<E extends string> = E extends "rate_limited" ? {
+    ok: false;
+    error: E;
+    retryAfterSec?: number;
+} : {
+    ok: false;
+    error: E;
+};
+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`. */
+type PublicSiteResult<T> = {
+    ok: true;
+    data: T;
+    etag: string | null;
+} | PublicFailure<PublicSiteError>;
+/** 304: what the caller holds for `ifNoneMatch` is still current. */
+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).
+ */
+interface Revalidate {
+    ifNoneMatch: string;
+}
+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[];
+}
+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">>;
+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;
+}
+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>;
+}
+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>;
+}
+declare function createPublicClient(opts: PublicClientOptions): PublicClient;
+
+export { type CollectionQuery as C, type PublicForm as P, type Revalidate as R, type SubmitResult as S, type PublicReadError as a, type PublicRecordSummary as b, type PublicValue as c, type PublicCollectionPage as d, type PublicRecord as e, type PublicResult as f, type PublicShare as g, type PublicClient as h, type PublicClientOptions as i, type PublicFailure as j, type PublicFormField as k, type PublicFormFieldType as l, type PublicNotModified as m, type PublicSite as n, type PublicSiteCollection as o, type PublicSiteError as p, type PublicSiteResult as q, type PublicSubmitError as r, SITE_MAX_LIMIT as s, SITE_MAX_OFFSET as t, SITE_MAX_SORT_KEYS as u, SITE_PUBLISHED_AT_SORT as v, type SubmitFormInput as w, createPublicClient as x };