@bettercms-ai/sdk 1.32.0 → 1.34.0

package/dist/read-ndf2I3D4.d.ts

@@ -0,0 +1,393 @@
+import { BetterCMSErrorCode, Perspective, DeliveryEntry, DeliveryList, DeliveryPage, DeliveryComponent, DeliveredLayout } from '@bettercms-ai/types';
+
+/** Semantic error codes used by the SDK. */
+declare const ErrorCodes: {
+    readonly CONTENT_NOT_FOUND: "CONTENT_NOT_FOUND";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly ADMIN_NOT_IMPLEMENTED: "ADMIN_NOT_IMPLEMENTED";
+};
+/**
+ * BetterCMSError — normalized SDK error with a semantic code.
+ */
+declare class BetterCMSError extends Error {
+    readonly status: number;
+    readonly code: BetterCMSErrorCode;
+    /**
+     * Raw machine-readable `code` from the response body (e.g. "PROJECT_DELETED"),
+     * when the API supplies one. Distinct from `code` (which is derived from the
+     * HTTP status), this lets callers branch on a specific server condition that
+     * shares a status with others (e.g. 409 slug-conflict vs 409 project-deleted).
+     */
+    readonly bodyCode?: string;
+    /**
+     * Per-field validation messages from a 400 `{ errors: { field: message } }` body.
+     * The backend returns validation failures in this shape (not `message`/`error`), so
+     * without this the SDK collapsed every validation 400 to a bare "Bad Request" with no
+     * hint which field or rule failed (FLO-474). Mirrors the forms client's `fieldErrors`.
+     */
+    readonly fieldErrors?: Record<string, string>;
+    /**
+     * The parsed response body, when there was one.
+     *
+     * Several refusals carry STRUCTURED detail that neither `message` nor `fieldErrors` can hold,
+     * and which is the whole point of the refusal: a component publish 409s with the full
+     * `readiness` tuple (what evidence is missing, whether a human still has to approve it) and
+     * 422s with the `issues` naming the Layouts it would break. Collapsing those to a sentence
+     * leaves a caller able to report that something failed and not what to do about it.
+     */
+    readonly body?: unknown;
+    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string, fieldErrors?: Record<string, string>, body?: unknown);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        code: BetterCMSErrorCode;
+        bodyCode: string | undefined;
+        fieldErrors: Record<string, string> | undefined;
+    };
+    /**
+     * Factory — creates a BetterCMSError from a failed fetch Response. Reads the body's
+     * `message` (or `error`) for the human message and `code` for a machine-readable
+     * condition surfaced as `bodyCode`. Validation failures arrive as `{ errors: {...} }`
+     * (no `message`/`error`), so fall back to the first field error for the message and
+     * expose the full map as `fieldErrors` (FLO-474).
+     */
+    static from(res: Response): Promise<BetterCMSError>;
+}
+
+/**
+ * Public forms — the headless integration surface for sites built on or imported
+ * into BetterCMS (the "render it yourself" model, like Sanity's delivery API).
+ *
+ * Form definitions ship in the build-time content snapshot (`bcms-content.json` →
+ * `forms` / `turnstileSiteKey`) and from `GET /api/v1/delivery/:workspace/forms`.
+ * A site renders them with its own components (see `@bettercms-ai/next`'s <BcmsForm>)
+ * and posts here. No API key — the endpoint is Turnstile-gated (Webflow model).
+ *
+ * This module is the single source of truth for the delivered form shape + the
+ * pure logic (conditional visibility, initial values) the renderers share, so the
+ * vanilla embed and the React component never drift.
+ */
+
+/**
+ * Field types the delivery API serializes. Must stay equal to the authoring
+ * vocabulary in `packages/db/src/schema/forms.ts` — this list is what every site
+ * renderer switches on, so a type missing HERE renders as a plain text input on
+ * every published site while the builder happily offers it. `radio`/`checkboxes`
+ * were exactly that gap.
+ */
+type DeliveryFormFieldType = "text" | "email" | "phone" | "url" | "number" | "date" | "textarea" | "select" | "radio" | "checkboxes" | "checkbox" | "consent" | "hidden" | "step";
+interface DeliveryFormField {
+    key: string;
+    label: string;
+    type: DeliveryFormFieldType;
+    placeholder?: string;
+    /** Hint rendered under the control. */
+    helpText?: string;
+    required?: boolean;
+    options?: string[];
+    defaultValue?: string;
+    /** Conditional visibility — render this field only when another field equals `equals`. */
+    showIf?: {
+        field: string;
+        equals: string;
+    };
+    /**
+     * Per-field rules the API enforces on submit. Renderers should mirror them onto the
+     * native control (`min`/`max`/`pattern`) so the browser reports them before the round
+     * trip — the server check is the one that counts.
+     */
+    validation?: DeliveryFormFieldValidation;
+    /**
+     * Presentation options the renderer honours. Unlike `validation`, the API does NOT enforce
+     * these on submit — they change what the visitor is shown, not what is accepted.
+     */
+    ui?: DeliveryFormFieldUi;
+}
+/**
+ * @see FormFieldUi in @bettercms-ai/types — same shape, delivered to the site.
+ *
+ * ── The phone composition contract every renderer implements ──
+ *
+ * A picker-enabled phone field is rendered as a country control PLUS a `tel` input, but it
+ * submits ONE value under the field's own key, in E.164. Whatever a renderer uses to hold the
+ * country (a React state, a `{key}__country` select) is scaffolding: it must never reach the
+ * POST body.
+ *
+ * Composition, from the visible input's raw text:
+ *   - empty → `""`. NEVER `"+CC"`, and the reason is worse than "the server rejects it". The
+ *     server's loose phone shape is `{3,32}` chars, so the outcome depends on the calling
+ *     code's length: `"+1"` is REFUSED (an optional untouched field starts 400ing), while
+ *     `"+91"` is ACCEPTED and stored as a real-looking submission that is only a country code.
+ *     The silent case is the dangerous one. Pinned in `__tests__/lib/forms-validate.test.ts`.
+ *   - starts with `"+"` → `"+" + digits(raw)`. The visitor typed an international number; the
+ *     country control is ignored rather than fighting them.
+ *   - otherwise → `"+" + callingCode + digits(raw).replace(/^0/, "")`, dropping ONE trunk zero.
+ *     Known exception: Italian landlines keep their trunk zero, so this loses it. The value is
+ *     still accepted (shape-only check) — it is a formatting loss, not a refusal.
+ *
+ * `ui` changes what the visitor SEES. It never changes what the API accepts: enforcing a format
+ * is `validation.phoneFormat`'s job and the two are independent.
+ *
+ * Renderer parity is behavioural, not implementational. FIVE lanes render this field, and they
+ * agree on the VALUE, not on the implementation:
+ *
+ *   | Lane                          | Control                         | As-you-type formatting |
+ *   |-------------------------------|---------------------------------|------------------------|
+ *   | dashboard form preview        | searchable picker + formatter   | yes                    |
+ *   | @bettercms-ai/next <BcmsForm> | native select + formatter       | yes (lazy chunk)       |
+ *   | hosted sites (render-page)    | native select + tel input       | NO                     |
+ *   | embed snippet                 | native select + tel input       | NO                     |
+ *   | @bettercms-ai/astro BcmsForm  | native select + tel input       | NO                     |
+ *
+ * The missing as-you-type formatting on the three vanilla lanes is a NAMED degradation, not an
+ * oversight: it is what keeps libphonenumber off a visitor's page entirely. `packages/next`
+ * pays for it only on pages that actually render a picker, via a separate chunk.
+ *
+ * When a lane builds that option list, never pass a libphonenumber helper as a bare callback:
+ * `getCountries().filter(isSupportedCountry)` hands it the array INDEX as its `metadata`
+ * argument and throws. Always wrap — `.filter((iso) => isSupportedCountry(iso))`.
+ *
+ * And when a lane ships the composition rule inside a JS TEMPLATE LITERAL (the embed snippet
+ * does), `\D` collapses to `D` and the regex silently becomes `/D/g` — stripping the letter D
+ * and leaving every other separator in place. Write `\\D` there. Raw HTML `<script>` text (the
+ * hosted renderer, the Astro inline script) takes a single backslash. Nothing throws either
+ * way; numbers just arrive malformed, so each lane pins it with an executed-script test.
+ */
+interface DeliveryFormFieldUi {
+    /** `phone` — render a country picker beside the number. The submitted value is E.164. */
+    countryPicker?: boolean;
+    /** `phone` — uppercase ISO 3166-1 alpha-2 the picker starts on. */
+    defaultCountry?: string;
+    /**
+     * `phone` — show the country's flag beside the dialling code.
+     *
+     * Honoured only by a renderer with a custom picker. The native `<select>` the site lanes use
+     * cannot hold an SVG, and an emoji flag renders as two grey letters on Windows, so those
+     * lanes show the country NAME instead — the same information, legibly, everywhere.
+     */
+    showFlags?: boolean;
+}
+/** @see FormFieldValidation in @bettercms-ai/types — same shape, delivered to the site. */
+interface DeliveryFormFieldValidation {
+    emailPolicy?: "any" | "business";
+    min?: number;
+    max?: number;
+    phoneFormat?: "any" | "e164";
+    pattern?: string;
+}
+/** The pick-many type, whose value is an array rather than a scalar. */
+declare function isMultiValueField(type: DeliveryFormFieldType): boolean;
+/** A form as delivered to a published/imported site. Mirrors the delivery `/forms` payload. */
+interface DeliveryForm {
+    id: string;
+    name: string;
+    /** The project the form belongs to. */
+    projectId?: string | null;
+    /**
+     * A `draft` form refuses every submission: render it as unavailable rather than as a form that
+     * silently drops what a visitor sends. Delivered for exactly that reason, and missing from this
+     * type until the contract test held the two together.
+     */
+    status?: "draft" | "published" | (string & {});
+    /** Set on a form the site's owner told BetterCMS to leave alone (ISO time); such a form is not wired. */
+    ignoredAt?: string | null;
+    fields: DeliveryFormField[];
+    submitLabel?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    turnstileEnabled?: boolean;
+    honeypotField?: string | null;
+}
+/** `string[]` is the `checkboxes` (pick-many) value; every other type is scalar. */
+type FormValue = string | boolean | string[];
+type FormValues = Record<string, FormValue>;
+/** Read a `checkboxes` value defensively — stored data may predate the array shape. */
+declare function asStringArray(value: FormValue | undefined): string[];
+/** Add/remove `option` from a `checkboxes` value, preserving the field's option order. */
+declare function toggleOption(value: FormValue | undefined, option: string, on: boolean): string[];
+/**
+ * Conditional visibility. A `showIf` field is shown only when its trigger field's
+ * current value equals the target; non-conditional fields are always shown. The
+ * renderer must skip hidden fields when collecting/validating so a hidden required
+ * field never blocks submit.
+ */
+declare function shouldShowField(field: DeliveryFormField, values: FormValues): boolean;
+/**
+ * Build the initial value map: checkbox/consent default to false, checkboxes to an
+ * empty array, every other field to its `defaultValue`, with `prefill` (e.g. URL
+ * query params) taking precedence.
+ */
+declare function formInitialValues(form: DeliveryForm, prefill?: Record<string, string>): FormValues;
+interface SubmitFormOptions {
+    formId: string;
+    data: FormValues;
+    /** Cloudflare Turnstile token; required when the form has `turnstileEnabled`. */
+    turnstileToken?: string;
+    /** API origin. Defaults to https://api.bettercms.ai. */
+    baseUrl?: string;
+    /** Injectable fetch for tests / non-browser runtimes. */
+    fetchImpl?: typeof fetch;
+}
+interface SubmitFormResult {
+    id: string;
+}
+/** A submit failure that carries per-field validation messages from the API (HTTP 400). */
+type FormSubmitError = BetterCMSError & {
+    fieldErrors?: Record<string, string>;
+};
+/**
+ * Submit a public form. Resolves with the new submission id, or throws a
+ * BetterCMSError — field-level validation errors are attached as `.fieldErrors`.
+ */
+declare function submitForm(opts: SubmitFormOptions): Promise<SubmitFormResult>;
+
+/**
+ * createClient — framework-agnostic typed read client for the Delivery API.
+ *
+ * Shared by @bettercms-ai/astro and @bettercms-ai/next so the fetch/typing/retry
+ * logic lives in one place. Read-only; for schema authoring use the
+ * Management client, for sessions use the Admin client.
+ *
+ *   const client = createClient({ apiUrl, workspace, apiKey });
+ *   await client.getPage("home");
+ *   await client.listEntries({ model: "post", perPage: 50 });
+ */
+
+interface CreateClientOptions {
+    /** Backend base, e.g. `https://api.bettercms.ai` (no trailing slash needed). */
+    apiUrl: string;
+    /** Workspace slug. */
+    workspace: string;
+    /** Delivery API key. Use a `content:read:draft` key for drafts. */
+    apiKey?: string;
+    /**
+     * The project every read is addressed to. A workspace holds many projects whose slugs
+     * collide (each has a `blog` model and a `home` page), so a site names its own; published
+     * reads need no key for it. BetterCMS hosting supplies `PUBLIC_BCMS_PROJECT_ID`.
+     */
+    projectId?: string;
+    /** `published` (default) or `drafts`. */
+    perspective?: Perspective;
+    /**
+     * Preview-token JWT for token-based single-document draft reads via the
+     * `/preview/:slug` endpoint. Only used when `perspective === "drafts"`.
+     */
+    previewToken?: string;
+    /**
+     * Embed invisible visual-editing provenance in draft reads, so a preview build can
+     * deep-link each rendered value back to its editor. Requires `perspective: "drafts"`,
+     * and then either a `previewToken` or a `content:read:draft` key. Ignored on published
+     * reads — the payload must never reach a production build.
+     *
+     * **Defaults to `true` on `perspective: "drafts"`** (since 1.15.0). Provenance is the whole
+     * reason the drafts perspective exists in a preview build, and an option nobody knew to pass
+     * meant every such build rendered anonymous strings: the editor could bind them only by
+     * guessing at their text. It stays OFF on every other perspective, unconditionally, so a
+     * published build cannot acquire a payload by accident — pass `stega: false` to opt a draft
+     * read out (a diff or a checksum over draft content is the case that wants it).
+     */
+    stega?: boolean;
+    /** Per-attempt timeout in ms. Defaults to 10000. */
+    timeout?: number;
+    /**
+     * Collapse identical GETs to one network round-trip for the life of this client.
+     * Default false.
+     *
+     * Only correct where the content is a POINT-IN-TIME SNAPSHOT — i.e. a static build,
+     * where every route renders from the same published dataset. `@bettercms-ai/astro`
+     * turns this on automatically when Astro's `command === "build"` and never for `dev`,
+     * SSR or the drafts perspective, where a repeat read must see the current row.
+     *
+     * A static build without it re-fetches the same nav/settings/collection once PER ROUTE.
+     * That is what made a large site exhaust the delivery rate limit: hundreds of identical
+     * requests, and `getPage()` re-scanning every page of the paginated list each time it is
+     * called.
+     */
+    cache?: boolean;
+}
+interface ListEntriesOptions {
+    /** Filter by content-model slug. */
+    model?: string;
+    page?: number;
+    perPage?: number;
+    /** Reference hydration depth (lists cap at 1). */
+    depth?: 0 | 1;
+    /** Projection — field names to return. */
+    select?: string[];
+}
+interface GetEntryOptions {
+    depth?: 0 | 1 | 2;
+    select?: string[];
+}
+interface ListPagesOptions {
+    page?: number;
+    perPage?: number;
+}
+interface BetterCMSReadClient {
+    readonly perspective: Perspective;
+    getEntry<T = Record<string, unknown>>(slug: string, opts?: GetEntryOptions): Promise<DeliveryEntry<T>>;
+    listEntries<T = Record<string, unknown>>(opts?: ListEntriesOptions): Promise<DeliveryList<DeliveryEntry<T>>>;
+    getPage(slug: string): Promise<DeliveryPage | null>;
+    listPages(opts?: ListPagesOptions): Promise<DeliveryList<DeliveryPage>>;
+    /**
+     * The workspace's reusable component definitions, for resolving `component` blocks.
+     * Under `perspective: "drafts"` this is the DRAFT definition — what makes an SSR render
+     * of a draft page look like the page the editor is showing.
+     */
+    listComponents(): Promise<DeliveryComponent[]>;
+    /** Fetch the project-scoped Global Layout for the active perspective. */
+    getLayout(): Promise<DeliveredLayout | null>;
+    listForms(opts?: {
+        projectId?: string;
+    }): Promise<{
+        items: DeliveryForm[];
+        turnstileSiteKey: string | null;
+    }>;
+    /** Build a deterministic Next/cache tag for a resource. */
+    tag(resource: "entry" | "page" | "forms", id?: string): string;
+}
+declare function createClient(options: CreateClientOptions): BetterCMSReadClient;
+
+/**
+ * Public site search — the headless surface for the visitor-facing search box.
+ *
+ * Queries `GET /api/v1/delivery/search?project=…&q=…`, the same key-less public
+ * endpoint the embeddable widget uses. Powers <BcmsSearch> in @bettercms-ai/next
+ * and @bettercms-ai/astro, so the component and any custom UI never drift.
+ *
+ * `snippet` is HTML-safe: the server escapes the field content and keeps only the
+ * <mark> highlight wrappers, so it can be rendered with dangerouslySetInnerHTML.
+ */
+interface SearchHit {
+    title: string;
+    slug: string;
+    type: "page" | "entry";
+    /** HTML-safe snippet with <mark> highlights around matched terms. */
+    snippet: string;
+    /** Site-relative URL, e.g. "/about". */
+    url: string;
+}
+interface SearchOptions {
+    /** The project id (from the dashboard's Site Search settings). */
+    project: string;
+    /** The query string. Calls with fewer than 1 char resolve to []. */
+    q: string;
+    /** Max hits, 1–20 (default 8). */
+    limit?: number;
+    /** API origin. Defaults to https://api.bettercms.ai. */
+    baseUrl?: string;
+    /** Injectable fetch for tests / non-browser runtimes. */
+    fetchImpl?: typeof fetch;
+    /** AbortSignal so callers can cancel a stale in-flight search. */
+    signal?: AbortSignal;
+}
+/** Search a published site. Resolves with hits, or [] on an empty query / network error. */
+declare function search(opts: SearchOptions): Promise<SearchHit[]>;
+
+export { BetterCMSError as B, type CreateClientOptions as C, type DeliveryFormField as D, ErrorCodes as E, type FormSubmitError as F, type GetEntryOptions as G, type ListEntriesOptions as L, type SearchHit as S, type BetterCMSReadClient as a, type DeliveryForm as b, type DeliveryFormFieldType as c, type FormValue as d, type FormValues as e, type ListPagesOptions as f, type SearchOptions as g, type SubmitFormOptions as h, type SubmitFormResult as i, asStringArray as j, createClient as k, formInitialValues as l, isMultiValueField as m, shouldShowField as n, submitForm as o, search as s, toggleOption as t };