@synap-core/sdk 1.1.0 → 1.3.0

package/dist/client-CVUT1Mcf.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 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 };

package/dist/connect.browser.cjs

@@ -0,0 +1,22 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/connect/browser.ts
+var browser_exports = {};
+module.exports = __toCommonJS(browser_exports);
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. Import it from route handlers, proxy.ts or server code, never from a client component."
+);
+//# sourceMappingURL=connect.browser.cjs.map

package/dist/connect.browser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/browser.ts"],"sourcesContent":["/**\n * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`\n * export condition): no exports, and a throw on load. See ./guard.ts.\n */\nthrow new Error(\n  \"@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. \" +\n    \"Import it from route handlers, proxy.ts or server code, never from a client component.\",\n);\n\nexport {};\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;AAIA,MAAM,IAAI;AAAA,EACR;AAEF;","names":[]}

package/dist/connect.browser.d.cts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/connect.browser.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/connect.browser.js

@@ -0,0 +1,5 @@
+// src/connect/browser.ts
+throw new Error(
+  "@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. Import it from route handlers, proxy.ts or server code, never from a client component."
+);
+//# sourceMappingURL=connect.browser.js.map

package/dist/connect.browser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/connect/browser.ts"],"sourcesContent":["/**\n * What a BROWSER bundle gets for `@synap-core/sdk/connect` (the `browser`\n * export condition): no exports, and a throw on load. See ./guard.ts.\n */\nthrow new Error(\n  \"@synap-core/sdk/connect is server-only: it holds the pod's tokens and the app secret. \" +\n    \"Import it from route handlers, proxy.ts or server code, never from a client component.\",\n);\n\nexport {};\n"],"mappings":";AAIA,MAAM,IAAI;AAAA,EACR;AAEF;","names":[]}