@synap-core/sdk 1.1.0 → 1.3.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
 });
 ```
 
@@ -67,8 +73,12 @@ 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). It never sends credentials (`credentials: 'omit'`,
-no Authorization/Cookie) and works from any origin, so it is safe in a public site.
+(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";
@@ -90,6 +100,128 @@ indistinguishable), `rate_limited`, `network`, `server`. A submit always answers
 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).
+
+## Pod-app sign-in (server-only): `@synap-core/sdk/connect` (1.3.0)
+
+An app that reads and writes a person's OWN pod connects as an OAuth 2.1 public
+client of that pod: its `client_id` is the https URL of its client metadata
+document (CIMD), PKCE S256, every answer checked for the pod's `iss`. The pod
+token stays on the app's server, sealed (AES-GCM) in an HttpOnly cookie; the
+browser never sees it. Framework-free and Web-standard (`Request` → `Response`,
+WebCrypto): Next route handlers and `proxy.ts`, Hono, Remix, edge runtimes.
+**Server-only**: it throws when loaded in a browser, and a browser bundle
+resolves it to a stub that throws.
+
+```typescript
+// lib/synap/pod-app/auth.ts (server-only)
+import { createPodAppAuth } from "@synap-core/sdk/connect";
+
+export const synap = createPodAppAuth({
+  appUrl: process.env.SITE_URL!, // https://studio.example.com
+  clientName: "Studio",
+  requests: [
+    { permission: "entity.post.read", reason: "Show your posts" },
+    { permission: "entity.post.create", reason: "Save drafts to your pod" },
+  ],
+  secret: process.env.SYNAP_APP_SESSION_SECRET!, // ≥ 32 chars, never NEXT_PUBLIC_
+});
+
+// app/.well-known/synap-client.json/route.ts  export const GET = synap.handlers.clientMetadata;
+// app/api/synap/connect/route.ts               export const POST = synap.handlers.connect;    // form { pod, next?, space? }
+// app/api/synap/callback/route.ts              export const GET = synap.handlers.callback;
+// app/api/synap/disconnect/route.ts            export const POST = synap.handlers.disconnect; // form { next? }
+```
+
+```typescript
+// proxy.ts: refresh before render (server components cannot set cookies)
+const out = await synap.refreshIfNeeded(request);
+// out.status: none | skipped | fresh | refreshed | kept | expired | revoked | unavailable
+// send out.setCookies on the response; forward out.cookieHeader (when set) as the request's Cookie
+
+// a server component / action (no Request there: pass the Cookie header)
+const connection = await synap.readConnection((await headers()).get("cookie"));
+const pod = synap.client(connection!);
+const res = await pod.post("/entities", { profileSlug: "post", title: "Hello" });
+if (res.ok && res.status === "proposed") showPending(res.reviewUrl); // success: queued for review, never retry
+if (!res.ok) res.error.code; // expired | unauthorized | forbidden | door_unsupported | rate_limited (retryAfterSec) | pod_unreachable | …
+```
+
+- **Discovery**: `discoverPod("pod.example.com")` fetches the pod's RFC 8414
+  metadata and requires `issuer` equal to the address, CIMD, `iss` on answers and
+  S256 (`not_a_pod`, `pod_unsupported`, `pod_unreachable`). A browser launch
+  (`?iss=…&target_link_uri=…`) is read with `acceptLaunch` and only pre-fills the
+  connect page. Synap Cloud discovery is not available yet:
+  `cloudConnectAvailable()` is `false`.
+- **Failures** redirect with `?error=<ConnectErrorCode>`: `denied`,
+  `expired_transaction`, `mismatch`, `misconfigured`, `rate_limited`,
+  `pod_unreachable`, … (`parseConnectErrorCode` reads it back). `connect` and
+  `disconnect` are POST and same-origin only.
+- **Refresh** (rotating, single-use, 30 days from issue) is feature-detected: a
+  pod that issues no `refresh_token` gives a connection that ends with its
+  1-hour access token. `refreshIfNeeded` rotates only inside the last 5
+  minutes, is single-flight per connection in the process, and persists the
+  rotated connection BEFORE returning it. The pod revokes the whole connection
+  when a spent refresh token is presented again, so for 2 minutes a request
+  still carrying the spent token (a parallel request, a second tab) gets the
+  rotation's result instead of reaching the pod. Across server instances only
+  a shared server-side `ConnectionStore` rules that replay out. A concurrent
+  loser (refused softly by the pod) keeps the still-valid access token.
+- **Your own store**: implement `ConnectionStore` (`read`, `write`, `clear`,
+  returning Set-Cookie values) and pass it as `store`.
+- Lower level: `startConnect`, `handleCallback`, `refreshConnection`,
+  `revokeConnection`, `buildClientMetadata`, `seal`/`unseal`.
+
+Test without a pod: `createMockAuthServer()` from `@synap-core/sdk/testing`
+(metadata, `authorize()` as the consent screen, `/token` with PKCE, rotating
+refresh, `/revoke`, Hub REST doors; `writeMode`, `failures`, `refresh: false`):
+
+```typescript
+const pod = createMockAuthServer();
+const synap = createPodAppAuth({ ...config, fetch: pod.fetch });
+// POST connect → Location → pod.authorize(location) → GET callback with that URL
+```
+
+## 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/chunk-J7XHAAFJ.js

@@ -0,0 +1,79 @@
+// src/connect/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8(text) {
+  return encoder.encode(text);
+}
+function fromUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function base64url(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64url(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  let binary;
+  try {
+    binary = atob(padded);
+  } catch {
+    return null;
+  }
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function randomBytes(length) {
+  const out = new Uint8Array(length);
+  crypto.getRandomValues(out);
+  return out;
+}
+function randomToken() {
+  return base64url(randomBytes(32));
+}
+async function pkceChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", utf8(verifier));
+  return base64url(new Uint8Array(digest));
+}
+function constantTimeEqual(a, b) {
+  const x = utf8(a);
+  const y = utf8(b);
+  let diff = x.length ^ y.length;
+  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);
+  return diff === 0;
+}
+function parseCookies(header) {
+  const out = /* @__PURE__ */ new Map();
+  if (!header) return out;
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (!name || out.has(name)) continue;
+    let value = part.slice(eq + 1).trim();
+    if (value.startsWith('"') && value.endsWith('"')) value = value.slice(1, -1);
+    out.set(name, value);
+  }
+  return out;
+}
+function serializeCookie(name, value, attrs) {
+  const parts = [`${name}=${value}`, "Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];
+  if (attrs.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+export {
+  utf8,
+  fromUtf8,
+  base64url,
+  fromBase64url,
+  randomBytes,
+  randomToken,
+  pkceChallenge,
+  constantTimeEqual,
+  parseCookies,
+  serializeCookie
+};
+//# sourceMappingURL=chunk-J7XHAAFJ.js.map

package/dist/chunk-J7XHAAFJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/encoding.ts"],"sourcesContent":["/**\n * Web-standard primitives (WebCrypto, TextEncoder, btoa/atob): the same code\n * runs on Node 18+, edge runtimes and workers. No Node import.\n */\n\nconst encoder = new TextEncoder();\nconst decoder = new TextDecoder();\n\n/** `Uint8Array<ArrayBuffer>`: what WebCrypto's `BufferSource` takes under TS 5.7+ lib types. */\nexport type Bytes = Uint8Array<ArrayBuffer>;\n\nexport function utf8(text: string): Bytes {\n  return encoder.encode(text);\n}\n\nexport function fromUtf8(bytes: Uint8Array): string {\n  return decoder.decode(bytes);\n}\n\nexport function base64url(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);\n  return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\");\n}\n\n/** Null when `text` is not base64url. */\nexport function fromBase64url(text: string): Bytes | null {\n  if (!/^[A-Za-z0-9_-]*$/.test(text)) return null;\n  const padded = text.replace(/-/g, \"+\").replace(/_/g, \"/\") + \"===\".slice((text.length + 3) % 4);\n  let binary: string;\n  try {\n    binary = atob(padded);\n  } catch {\n    return null;\n  }\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\nexport function randomBytes(length: number): Bytes {\n  const out = new Uint8Array(length);\n  crypto.getRandomValues(out);\n  return out;\n}\n\n/** 32 random bytes, base64url (43 chars): a state value or a PKCE verifier. */\nexport function randomToken(): string {\n  return base64url(randomBytes(32));\n}\n\n/** RFC 7636 §4.2: `BASE64URL(SHA256(ASCII(code_verifier)))`. */\nexport async function pkceChallenge(verifier: string): Promise<string> {\n  const digest = await crypto.subtle.digest(\"SHA-256\", utf8(verifier));\n  return base64url(new Uint8Array(digest));\n}\n\n/** Compare two strings without an early exit on the first differing byte. */\nexport function constantTimeEqual(a: string, b: string): boolean {\n  const x = utf8(a);\n  const y = utf8(b);\n  let diff = x.length ^ y.length;\n  for (let i = 0; i < Math.max(x.length, y.length); i++) diff |= (x[i] ?? 0) ^ (y[i] ?? 0);\n  return diff === 0;\n}\n\n/** The request's cookies by name (the first value wins, as browsers order the most specific first). */\nexport function parseCookies(header: string | null): Map<string, string> {\n  const out = new Map<string, string>();\n  if (!header) return out;\n  for (const part of header.split(\";\")) {\n    const eq = part.indexOf(\"=\");\n    if (eq < 0) continue;\n    const name = part.slice(0, eq).trim();\n    if (!name || out.has(name)) continue;\n    let value = part.slice(eq + 1).trim();\n    if (value.startsWith('\"') && value.endsWith('\"')) value = value.slice(1, -1);\n    out.set(name, value);\n  }\n  return out;\n}\n\nexport interface CookieAttributes {\n  maxAgeSec: number;\n  secure: boolean;\n}\n\n/** `HttpOnly; SameSite=Lax; Path=/` always; `Secure` on https. Never a `Domain`. */\nexport function serializeCookie(name: string, value: string, attrs: CookieAttributes): string {\n  const parts = [`${name}=${value}`, \"Path=/\", \"HttpOnly\", \"SameSite=Lax\", `Max-Age=${Math.max(0, Math.floor(attrs.maxAgeSec))}`];\n  if (attrs.secure) parts.push(\"Secure\");\n  return parts.join(\"; \");\n}\n"],"mappings":";AAKA,IAAM,UAAU,IAAI,YAAY;AAChC,IAAM,UAAU,IAAI,YAAY;AAKzB,SAAS,KAAK,MAAqB;AACxC,SAAO,QAAQ,OAAO,IAAI;AAC5B;AAEO,SAAS,SAAS,OAA2B;AAClD,SAAO,QAAQ,OAAO,KAAK;AAC7B;AAEO,SAAS,UAAU,OAA2B;AACnD,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,IAAK,WAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAC7E,SAAO,KAAK,MAAM,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE;AAC/E;AAGO,SAAS,cAAc,MAA4B;AACxD,MAAI,CAAC,mBAAmB,KAAK,IAAI,EAAG,QAAO;AAC3C,QAAM,SAAS,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG,IAAI,MAAM,OAAO,KAAK,SAAS,KAAK,CAAC;AAC7F,MAAI;AACJ,MAAI;AACF,aAAS,KAAK,MAAM;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,MAAM,IAAI,WAAW,OAAO,MAAM;AACxC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,IAAK,KAAI,CAAC,IAAI,OAAO,WAAW,CAAC;AACpE,SAAO;AACT;AAEO,SAAS,YAAY,QAAuB;AACjD,QAAM,MAAM,IAAI,WAAW,MAAM;AACjC,SAAO,gBAAgB,GAAG;AAC1B,SAAO;AACT;AAGO,SAAS,cAAsB;AACpC,SAAO,UAAU,YAAY,EAAE,CAAC;AAClC;AAGA,eAAsB,cAAc,UAAmC;AACrE,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK,QAAQ,CAAC;AACnE,SAAO,UAAU,IAAI,WAAW,MAAM,CAAC;AACzC;AAGO,SAAS,kBAAkB,GAAW,GAAoB;AAC/D,QAAM,IAAI,KAAK,CAAC;AAChB,QAAM,IAAI,KAAK,CAAC;AAChB,MAAI,OAAO,EAAE,SAAS,EAAE;AACxB,WAAS,IAAI,GAAG,IAAI,KAAK,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAK,UAAS,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC,KAAK;AACtF,SAAO,SAAS;AAClB;AAGO,SAAS,aAAa,QAA4C;AACvE,QAAM,MAAM,oBAAI,IAAoB;AACpC,MAAI,CAAC,OAAQ,QAAO;AACpB,aAAW,QAAQ,OAAO,MAAM,GAAG,GAAG;AACpC,UAAM,KAAK,KAAK,QAAQ,GAAG;AAC3B,QAAI,KAAK,EAAG;AACZ,UAAM,OAAO,KAAK,MAAM,GAAG,EAAE,EAAE,KAAK;AACpC,QAAI,CAAC,QAAQ,IAAI,IAAI,IAAI,EAAG;AAC5B,QAAI,QAAQ,KAAK,MAAM,KAAK,CAAC,EAAE,KAAK;AACpC,QAAI,MAAM,WAAW,GAAG,KAAK,MAAM,SAAS,GAAG,EAAG,SAAQ,MAAM,MAAM,GAAG,EAAE;AAC3E,QAAI,IAAI,MAAM,KAAK;AAAA,EACrB;AACA,SAAO;AACT;AAQO,SAAS,gBAAgB,MAAc,OAAe,OAAiC;AAC5F,QAAM,QAAQ,CAAC,GAAG,IAAI,IAAI,KAAK,IAAI,UAAU,YAAY,gBAAgB,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE;AAC9H,MAAI,MAAM,OAAQ,OAAM,KAAK,QAAQ;AACrC,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}

package/dist/client-CVUT1Mcf.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 PublicShare as a, type PublicRecord as b, type PublicReadError as c, type PublicRecordSummary as d, type PublicValue as e, type PublicCollectionPage as f, type PublicResult 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 };