@bettercms-ai/sdk 1.6.0

package/dist/index.d.ts

@@ -0,0 +1,1072 @@
+import * as _bettercms_ai_types from '@bettercms-ai/types';
+import { ContentPageResult, Content, ContentModelField, BetterCMSErrorCode, AuthUser, AuthSession, SignInInput, SignUpInput, Perspective, DeliveryEntry, DeliveryList, DeliveryPage, PageMetaJson, SiteSeoDefaults, Page, MediaAsset, Form, FormSubmission, Workspace, ApiKey, ApiKeyPermission, ApiKeyTokenType } from '@bettercms-ai/types';
+export { ApiError, ApiKey, ApiKeyPermission, ApiKeyTokenType, AssertEqual, AuthSession, AuthUser, BetterCMSErrorCode, BlockType, ButtonBlock, ButtonProps, ColumnsBlock, ColumnsProps, Content, ContentBlock, ContentEntry, ContentModel, ContentModelField, ContentPageResult, ContentResponse, DeepReadonly, DeliveryEntry, DeliveryList, DeliveryPage, Form, FormBlock, FormField, FormProps, FormSubmission, HeadingBlock, HeadingProps, ImageBlock, ImageProps, MediaAsset, Page, PageMetaJson, PaginatedResult, Perspective, Redirect, SignInInput, SignUpInput, SiteSeoDefaults, SpacerBlock, SpacerProps, TextBlock, TextProps, VideoBlock, VideoProps, Workspace, getBlockType, isBlock } from '@bettercms-ai/types';
+export { ImageFit, ImageFormat, ImageSource, ImageUrlBuilder, ImageUrlOptions, imageUrl, default as imageUrlBuilder } from '@bettercms-ai/image-url';
+
+/**
+ * Options for {@link BetterCMSDeliveryClient.listContent}.
+ */
+interface ListContentOptions {
+    /** Page number (1-based). Defaults to 1. */
+    page?: number;
+    /** Items per page. Defaults to 20. */
+    perPage?: number;
+}
+/**
+ * Fetches a paginated list of published content pages.
+ */
+declare function listContent(client: BetterCMSDeliveryClient, opts?: ListContentOptions): Promise<ContentPageResult["data"]>;
+
+/**
+ * Options for {@link BetterCMSDeliveryClient.listContentAll}.
+ */
+interface ListContentAllOptions extends ListContentOptions {
+}
+/**
+ * An async iterator that transparently auto-paginates through all content.
+ *
+ * Usage:
+ * ```ts
+ * for await (const item of client.listContentAll()) { ... }
+ * ```
+ *
+ * Or with the `all()` convenience:
+ * ```ts
+ * const items = await client.listContentAll().all({ limit: 500 });
+ * ```
+ */
+declare function listContentAll(client: BetterCMSDeliveryClient, opts?: ListContentAllOptions): {
+    /**
+     * Async iterator — yields Content items page by page.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<Content>;
+    /**
+     * Convenience: collect all items into an array, optionally limited.
+     */
+    all(options?: {
+        limit?: number;
+    }): Promise<Content[]>;
+};
+
+declare class BetterCMSDeliveryClient {
+    readonly workspace: string;
+    readonly baseUrl: string;
+    private readonly apiKey?;
+    constructor(opts: {
+        workspace: string;
+        apiKey?: string;
+        baseUrl: string;
+    });
+    getContent(slug: string): Promise<_bettercms_ai_types.Content>;
+    listContent(opts?: Parameters<typeof listContent>[1]): Promise<_bettercms_ai_types.PaginatedResult<_bettercms_ai_types.Content>>;
+    listContentAll(opts?: Parameters<typeof listContentAll>[1]): {
+        [Symbol.asyncIterator](): AsyncIterableIterator<_bettercms_ai_types.Content>;
+        all(options?: {
+            limit?: number;
+        }): Promise<_bettercms_ai_types.Content[]>;
+    };
+    /** Build the full URL for a content path. */
+    url(path: string): string;
+    /** Build request headers, including auth if provided. */
+    headers(): Record<string, string>;
+    /**
+     * Generic fetch helper — wraps a request with network-error handling
+     * and throws a typed BetterCMSError on non-OK responses.
+     */
+    fetchJSON<T>(url: string): Promise<T>;
+}
+
+/**
+ * SDK webhook methods — create, list, delete, test webhooks.
+ */
+/**
+ * Webhook event types supported by BetterCMS.
+ */
+type WebhookEvent = "content.publish" | "content.unpublish" | "content.created" | "content.updated" | "content.deleted" | "page.published" | "page.unpublished" | "page.created" | "page.updated" | "page.deleted" | "form.submitted" | "api_key.created" | "api_key.deleted";
+/**
+ * Webhook record returned from the API (without secret).
+ */
+interface Webhook {
+    id: string;
+    projectId: string;
+    workspaceId: string;
+    name: string;
+    url: string;
+    events: WebhookEvent[];
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Webhook with secret — returned only on create.
+ */
+interface WebhookWithSecret extends Webhook {
+    secret: string;
+}
+/**
+ * Input for creating a webhook.
+ */
+interface CreateWebhookInput {
+    name: string;
+    url: string;
+    events?: WebhookEvent[];
+}
+/**
+ * Input for updating a webhook.
+ */
+interface UpdateWebhookInput {
+    name?: string;
+    url?: string;
+    events?: WebhookEvent[];
+    isActive?: boolean;
+}
+/**
+ * Paginated list response.
+ */
+interface WebhookListResponse {
+    data: Webhook[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+
+/**
+ * BetterCMSAdminClient — typed SDK client for admin CRUD operations.
+ *
+ * Extends BetterCMSDeliveryClient but overrides:
+ * - `headers()` — uses Bearer token auth instead of API key
+ * - `fetchJSON()` — adds retry on 429/503 and 10s timeout per request
+ *
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface BetterCMSAdminOptions {
+    /** Base URL of the Admin API. Defaults to https://api.bettercms.ai/v1 */
+    baseUrl?: string;
+    /** BetterAuth session Bearer token. */
+    token: string;
+    /** Request timeout per attempt in ms. Defaults to 10000. */
+    timeout?: number;
+}
+/**
+ * Admin SDK client. Extends BetterCMSDeliveryClient so it reuses
+ * workspace, baseUrl, url() from the base. Overrides headers() and
+ * fetchJSON() for Bearer auth + retry/timeout.
+ */
+declare class BetterCMSAdminClient extends BetterCMSDeliveryClient {
+    readonly timeout: number;
+    private readonly _token;
+    constructor(options: BetterCMSAdminOptions);
+    headers(): Record<string, string>;
+    /**
+     * Admin fetchJSON with retry (429, 503) and per-request timeout (AbortController).
+     * Each retry gets a fresh timeout.
+     */
+    fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
+    /** Build the admin API URL. */
+    url(path: string): string;
+    /** Webhook management methods. */
+    webhooks(): {
+        list: (options?: {
+            page?: number;
+            limit?: number;
+        }) => Promise<WebhookListResponse>;
+        create: (input: CreateWebhookInput) => Promise<WebhookWithSecret>;
+        get: (webhookId: string) => Promise<{
+            data: Webhook;
+        }>;
+        update: (webhookId: string, input: UpdateWebhookInput) => Promise<{
+            data: Webhook;
+        }>;
+        delete: (webhookId: string) => Promise<{
+            data: {
+                id: string;
+            };
+        }>;
+        test: (webhookId: string, event?: WebhookEvent) => Promise<{
+            data: {
+                delivered: boolean;
+                status?: number;
+            };
+        }>;
+    };
+}
+
+/**
+ * Management API SDK methods — programmatic content-model + content-entry authoring.
+ *
+ * These call /api/v1/management/content/* (key-auth, content:manage scope). The MCP
+ * server wraps these. Mostly additive (create + update); delete is supported via
+ * soft-delete (reversible, audit-logged) so agents can clean up their own mistakes.
+ */
+
+/** Minimal client surface these methods need (satisfied by BetterCMSManagementClient). */
+interface ManagementClient {
+    fetchJSON: <T>(url: string, init?: RequestInit) => Promise<T>;
+    url: (path: string) => string;
+}
+/** A content model row as returned by the Management API (the full DB record). */
+interface ManagedContentModel {
+    id: string;
+    workspaceId: string;
+    projectId: string | null;
+    name: string;
+    slug: string;
+    description: string | null;
+    fields: ContentModelField[];
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/** A content entry row as returned by the Management API (the full DB record). */
+interface ManagedContentEntry {
+    id: string;
+    workspaceId: string;
+    projectId: string | null;
+    contentModelId: string;
+    pageId: string | null;
+    slug: string;
+    status: "draft" | "published";
+    data: Record<string, unknown>;
+    publishedAt: string | null;
+    optimisticVersion: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+/** A page row as returned by the Management API. A page carries its own typed
+ *  schema (`fields`) plus `pageType`, and is project-scoped from the key. */
+interface ManagedPage {
+    id: string;
+    workspaceId: string;
+    projectId: string | null;
+    title: string;
+    slug: string;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    status: "draft" | "published";
+    pageType: "singleton" | "dynamic" | null;
+    fields: ContentModelField[];
+    optimisticVersion: number;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+interface CreateManagedPageInput {
+    title: string;
+    slug: string;
+    pageType?: "singleton" | "dynamic";
+    fields?: ContentModelField[];
+    metaTitle?: string;
+    metaDescription?: string;
+    status?: "draft" | "published";
+}
+/** Append fields to an existing page's schema (additive — see addPageFields). */
+interface AddPageFieldsInput {
+    addFields: ContentModelField[];
+}
+interface CreateModelInput {
+    name: string;
+    slug: string;
+    description?: string;
+    fields?: ContentModelField[];
+    projectId?: string;
+}
+interface UpdateModelInput {
+    name?: string;
+    slug?: string;
+    description?: string;
+    fields?: ContentModelField[];
+}
+interface CreateEntryInput {
+    contentModelId: string;
+    slug?: string;
+    status?: "draft" | "published";
+    data?: Record<string, unknown>;
+    pageId?: string | null;
+}
+interface UpdateEntryInput {
+    slug?: string;
+    status?: "draft" | "published";
+    data?: Record<string, unknown>;
+    pageId?: string | null;
+}
+/** Set a page's field VALUES (the actual content). For a singleton, upserts its one entry. */
+interface SetPageContentInput {
+    data: Record<string, unknown>;
+    status?: "draft" | "published";
+}
+/** Filter for listing content entries. */
+interface ListEntriesFilter {
+    modelId?: string;
+    pageId?: string;
+    status?: "draft" | "published";
+}
+/** List content models (schemas) in the key's workspace. Excludes soft-deleted. */
+declare function listModels(client: ManagementClient): Promise<ManagedContentModel[]>;
+/** Get a single content model by id. Needed for additive read-modify-write (e.g. add_field). */
+declare function getModel(client: ManagementClient, id: string): Promise<ManagedContentModel>;
+/** List pages in the key's project (or workspace-level if the key is not project-scoped). */
+declare function listManagedPages(client: ManagementClient): Promise<ManagedPage[]>;
+/** Create a page (the page-first schema: title/slug/pageType/fields). Project-scoped from the key.
+ *  Supports both `singleton` and `dynamic` pageType. */
+declare function createManagedPage(client: ManagementClient, input: CreateManagedPageInput): Promise<ManagedPage>;
+/**
+ * Append fields to an existing page's schema (additive read-append). The API
+ * rejects keys that already exist, so this never overwrites or retypes a field.
+ * Project-scoped from the key. Returns the updated page.
+ */
+declare function addPageFields(client: ManagementClient, id: string, input: AddPageFieldsInput): Promise<ManagedPage>;
+/** Get a single page by id INCLUDING its field schema + pageType. */
+declare function getManagedPage(client: ManagementClient, id: string): Promise<ManagedPage>;
+/**
+ * Set a page's field VALUES. For a SINGLETON page this creates or updates its one
+ * page-backed content entry (idempotent); for a dynamic page it upserts the entry
+ * keyed by the page. Returns the resulting entry.
+ */
+declare function setPageContent(client: ManagementClient, id: string, input: SetPageContentInput): Promise<ManagedContentEntry>;
+/** Append fields to a content model's schema (additive — rejects existing keys). */
+declare function addModelFields(client: ManagementClient, id: string, input: AddPageFieldsInput): Promise<ManagedContentModel>;
+/** List content entries (incl. drafts), optionally filtered by model/page/status. */
+declare function listEntries(client: ManagementClient, filter?: ListEntriesFilter): Promise<ManagedContentEntry[]>;
+/** Get a single content entry by id INCLUDING its data (field values), incl. drafts. */
+declare function getEntry(client: ManagementClient, id: string): Promise<ManagedContentEntry>;
+/** Create a content model (schema). */
+declare function createModel(client: ManagementClient, input: CreateModelInput): Promise<ManagedContentModel>;
+/** Update a content model (additive — fields/name/slug/description). */
+declare function updateModel(client: ManagementClient, id: string, input: UpdateModelInput): Promise<ManagedContentModel>;
+/** Create a content entry under a model. */
+declare function createEntry(client: ManagementClient, input: CreateEntryInput): Promise<ManagedContentEntry>;
+/**
+ * Update a content entry. If `opts.ifMatch` (current optimisticVersion) is supplied,
+ * the update is optimistic-locked; omit it for programmatic last-write-wins.
+ */
+declare function updateEntry(client: ManagementClient, id: string, input: UpdateEntryInput, opts?: {
+    ifMatch?: number;
+}): Promise<ManagedContentEntry>;
+
+/**
+ * Management API SDK method — media upload (P2).
+ *
+ * uploadAsset() resolves bytes from a local file path OR a remote URL, then POSTs
+ * them to /api/v1/management/media (media:write scope) and returns the stored
+ * asset's stable CDN URL. The MCP `upload_asset` tool wraps this so an AI agent
+ * can put repo/remote images into the Media Library and reference the URL in an
+ * entry's image field.
+ *
+ * Local-file reads use a lazy `node:` import so browser bundles that never call
+ * the localPath branch don't pull Node built-ins.
+ */
+
+interface UploadAssetInput {
+    /** Path to a local file (e.g. a repo image). Mutually exclusive with `url`. */
+    localPath?: string;
+    /** Remote image URL to ingest. Mutually exclusive with `localPath`. */
+    url?: string;
+    /** Override the stored filename (defaults to the source basename). */
+    filename?: string;
+    altText?: string;
+    caption?: string;
+    /** Target Media Library folder id (defaults to project root). */
+    folderId?: string;
+}
+interface UploadedAsset {
+    id: string;
+    url: string;
+    key: string;
+    filename: string;
+}
+
+/** 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;
+    constructor(message: string, status: number, code: BetterCMSErrorCode, bodyCode?: string);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        code: BetterCMSErrorCode;
+        bodyCode: 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 the SDK surfaces as `bodyCode`.
+     */
+    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 (superset of the admin builder). */
+type DeliveryFormFieldType = "text" | "email" | "phone" | "url" | "number" | "date" | "textarea" | "select" | "checkbox" | "consent" | "hidden";
+interface DeliveryFormField {
+    key: string;
+    label: string;
+    type: DeliveryFormFieldType;
+    placeholder?: string;
+    required?: boolean;
+    options?: string[];
+    defaultValue?: string;
+    /** Conditional visibility — render this field only when another field equals `equals`. */
+    showIf?: {
+        field: string;
+        equals: string;
+    };
+}
+/** A form as delivered to a published/imported site. Mirrors the delivery `/forms` payload. */
+interface DeliveryForm {
+    id: string;
+    name: string;
+    fields: DeliveryFormField[];
+    submitLabel?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    turnstileEnabled?: boolean;
+    honeypotField?: string | null;
+}
+type FormValue = string | boolean;
+type FormValues = Record<string, FormValue>;
+/**
+ * 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, 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>;
+
+/**
+ * Management API SDK methods — read-only form discovery.
+ *
+ * These call /api/v1/management/forms (key-auth, content:manage scope). The MCP
+ * server wraps these so an agent can list/read the forms built in the dashboard
+ * and then embed the matching `<BcmsForm>` into the user's site code. Read-only by
+ * design — form authoring + Google Sheets "integrations" stay dashboard-only.
+ */
+
+/** A form as returned by the Management API — the public, render-only projection. */
+interface ManagedForm {
+    id: string;
+    projectId: string | null;
+    name: string;
+    description: string | null;
+    fields: DeliveryFormField[];
+    submitLabel?: string | null;
+    successMessage?: string | null;
+    redirectUrl?: string | null;
+    turnstileEnabled?: boolean | null;
+    honeypotField?: string | null;
+}
+/** Create/update input — mirrors the Management API form schema (fields are passed through). */
+interface ManagedFormInput {
+    name?: string;
+    description?: string;
+    fields?: DeliveryFormField[];
+    submitLabel?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+}
+
+/**
+ * Management API SDK methods — reusable components (discover + author).
+ *
+ * Call /api/v1/management/components (key-auth, content:manage). The MCP server wraps
+ * these so an agent can list/read components and author new ones (blockJson + props).
+ */
+
+/** A component as returned by the Management API (render + author shape). */
+interface ManagedComponent {
+    id: string;
+    projectId: string | null;
+    name: string;
+    slug: string;
+    category: string;
+    description: string | null;
+    blockJson: unknown[];
+    props: unknown[];
+    thumbnail?: string | null;
+}
+/** Create/update input. `blockJson` is the ContentBlock tree; `props` the override allowlist. */
+interface ManagedComponentInput {
+    name?: string;
+    slug?: string;
+    category?: string;
+    description?: string;
+    blockJson?: unknown[];
+    props?: unknown[];
+}
+
+interface BetterCMSManagementOptions {
+    /** Base URL of the Management API. Defaults to https://api.bettercms.ai/v1 */
+    baseUrl?: string;
+    /** A content:manage scoped API key. */
+    apiKey: string;
+    /** Request timeout per attempt in ms. Defaults to 10000. */
+    timeout?: number;
+}
+declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
+    readonly timeout: number;
+    private readonly _apiKey;
+    constructor(options: BetterCMSManagementOptions);
+    headers(): Record<string, string>;
+    /** Management API URL: baseUrl + path (path is workspace-scoped via the key). */
+    url(path: string): string;
+    /** fetchJSON with retry (429, 503) + per-request timeout (mirrors the admin client). */
+    fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
+    listModels(): Promise<ManagedContentModel[]>;
+    getModel(id: string): Promise<ManagedContentModel>;
+    createModel(input: CreateModelInput): Promise<ManagedContentModel>;
+    updateModel(id: string, input: UpdateModelInput): Promise<ManagedContentModel>;
+    listPages(): Promise<ManagedPage[]>;
+    /** Get one page by id INCLUDING its field schema + pageType. */
+    getPage(id: string): Promise<ManagedPage>;
+    createPage(input: CreateManagedPageInput): Promise<ManagedPage>;
+    /** Append fields to an existing page (additive — the API rejects existing keys). */
+    addPageFields(id: string, input: AddPageFieldsInput): Promise<ManagedPage>;
+    /** Set a page's field VALUES — singleton pages get/update their one entry. */
+    setPageContent(id: string, input: SetPageContentInput): Promise<ManagedContentEntry>;
+    /** Append fields to a content model (additive — rejects existing keys). */
+    addModelFields(id: string, input: AddPageFieldsInput): Promise<ManagedContentModel>;
+    createEntry(input: CreateEntryInput): Promise<ManagedContentEntry>;
+    updateEntry(id: string, input: UpdateEntryInput, opts?: {
+        ifMatch?: number;
+    }): Promise<ManagedContentEntry>;
+    /** Soft-delete a page and its content entries. */
+    deletePage(id: string): Promise<{
+        id: string;
+    }>;
+    /** Soft-delete a single content entry. */
+    deleteEntry(id: string): Promise<{
+        id: string;
+    }>;
+    /** Soft-delete a content model and its entries. */
+    deleteModel(id: string): Promise<{
+        id: string;
+    }>;
+    /** List content entries (incl. drafts), optionally filtered by model/page/status. */
+    listEntries(filter?: ListEntriesFilter): Promise<ManagedContentEntry[]>;
+    /** Get one content entry by id INCLUDING its data (incl. drafts). */
+    getEntry(id: string): Promise<ManagedContentEntry>;
+    uploadAsset(input: UploadAssetInput): Promise<UploadedAsset>;
+    /** List forms in the key's project (or workspace-level). */
+    listForms(): Promise<ManagedForm[]>;
+    /** Get one form by id INCLUDING its field schema + settings. */
+    getForm(id: string): Promise<ManagedForm>;
+    /** Create a form in the key's project. */
+    createForm(input: ManagedFormInput): Promise<ManagedForm>;
+    /** Update a form by id (passing `fields` replaces the array). */
+    updateForm(id: string, input: ManagedFormInput): Promise<ManagedForm>;
+    listComponents(): Promise<ManagedComponent[]>;
+    getComponent(id: string): Promise<ManagedComponent>;
+    createComponent(input: ManagedComponentInput): Promise<ManagedComponent>;
+    updateComponent(id: string, input: ManagedComponentInput): Promise<ManagedComponent>;
+}
+
+interface AuthResult {
+    token: string;
+    user: AuthUser;
+    session: AuthSession;
+    admin: BetterCMSAdminClient;
+    signOut(): Promise<void>;
+}
+/** Sign in with email + password. Returns a session ready for API calls. */
+declare function signIn(input: SignInInput): Promise<AuthResult>;
+/** Sign up with email + password + name. Returns a session ready for API calls. */
+declare function signUp(input: SignUpInput): Promise<AuthResult>;
+/**
+ * Initiate Google OAuth sign-in (browser flow) or verify a Google ID token (programmatic).
+ *
+ * Browser flow:  Returns { url } — redirect the user to this URL.
+ * Programmatic:   Pass { idToken: { token: "<google-id-token>" } } — returns AuthResult directly.
+ */
+declare function signInWithGoogle(options?: {
+    idToken?: {
+        token: string;
+        nonce?: string;
+    };
+    callbackURL?: string;
+}): Promise<AuthResult & {
+    url?: string;
+    redirect?: boolean;
+}>;
+/**
+ * Initiate GitHub OAuth sign-in (browser flow) or verify a GitHub OAuth token (programmatic).
+ *
+ * Browser flow:  Returns { url } — redirect the user to this URL.
+ * Programmatic:   Pass { idToken: { token: "<github-access-token>" } } — returns AuthResult directly.
+ */
+declare function signInWithGithub(options?: {
+    idToken?: {
+        token: string;
+        nonce?: string;
+    };
+    callbackURL?: string;
+}): Promise<AuthResult & {
+    url?: string;
+    redirect?: boolean;
+}>;
+
+/**
+ * Options for {@link BetterCMS.site}.
+ */
+interface BetterCMSSiteOptions {
+    /** The workspace slug (e.g. "rahul-project-one"). */
+    workspace: string;
+    /** Optional API key for authenticated requests. */
+    apiKey?: string;
+    /** Base URL of the Delivery API. Defaults to https://api.bettercms.ai/v1. */
+    baseUrl?: string;
+}
+/**
+ * BetterCMS factory — returns a typed client for the Delivery API.
+ */
+declare const BetterCMS: {
+    /**
+     * Returns a client for fetching published content.
+     * `apiKey` is optional — public content works without one.
+     */
+    site(options: BetterCMSSiteOptions): BetterCMSDeliveryClient;
+    /**
+     * Returns a typed client for admin CRUD operations.
+     * Requires a BetterAuth session Bearer token.
+     */
+    admin(options: BetterCMSAdminOptions): BetterCMSAdminClient;
+    /**
+     * Returns a typed client for the Management API (programmatic schema + content
+     * authoring). Requires a content:manage scoped API key.
+     */
+    management(options: BetterCMSManagementOptions): BetterCMSManagementClient;
+    /**
+     * Sign in with email + password. Returns a session ready for API calls.
+     */
+    auth(options: SignInInput): Promise<AuthResult>;
+    /**
+     * Sign up with email + password + name. Returns a session ready for API calls.
+     */
+    signUp(options: SignUpInput): Promise<AuthResult>;
+};
+
+/**
+ * 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;
+    /** Optional project scope for forms. */
+    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 visual-editing stega provenance in draft reads (preview lane only). */
+    stega?: boolean;
+    /** Per-attempt timeout in ms. Defaults to 10000. */
+    timeout?: number;
+}
+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>>;
+    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;
+
+/** Provenance describing where a string came from, for editor deep-linking. */
+interface StegaPayload {
+    /** Workspace slug. */
+    ws: string;
+    type: "entry" | "page";
+    /** Entry/page id. */
+    id: string;
+    slug: string;
+    /** Field key (or block id) the value belongs to. */
+    field: string;
+}
+/** Append an invisible provenance payload to a string. */
+declare function encodeStega(clean: string, payload: StegaPayload): string;
+/** Extract `{ clean, payload }` from a stega-encoded string, or null if absent. */
+declare function decodeStega(value: string): {
+    clean: string;
+    payload: StegaPayload;
+} | null;
+/** Remove any stega payload, returning the clean string. */
+declare function stripStega(value: string): string;
+
+/**
+ * resolveSeo — framework-agnostic page-over-site SEO merge for headless consumers.
+ *
+ * The single source of truth for "per-page meta layered over project defaults",
+ * mirroring the server renderer's `mergeSeoMeta` so `*.bettercms.site` and headless
+ * sites (@bettercms-ai/next, @bettercms-ai/astro) emit identical <head> SEO. Pure: empty
+ * inputs collapse to empty strings ("omit the tag"), never fabricated values.
+ *
+ *   const seo = resolveSeo(page, siteDefaults);
+ *   // → { title, description, canonical, og, twitter, jsonLd }
+ *
+ * Next consumers map this to a `Metadata` via `buildMetadata` (@bettercms-ai/next);
+ * Astro consumers read the fields straight into `<head>`.
+ */
+
+/** Minimal page shape `resolveSeo` reads — a `DeliveryPage`/`BetterCMSPage` satisfies it. */
+interface SeoInput {
+    title: string;
+    metaTitle?: string | null;
+    metaDescription?: string | null;
+    metaJson?: PageMetaJson | null;
+}
+/** Fully-resolved SEO values, page-over-site. Empty string ⇒ omit that tag. */
+interface ResolvedSeo {
+    title: string;
+    description: string;
+    /** Canonical URL — page's own `canonical`, else "". Consumers may supply their own base. */
+    canonical: string;
+    og: {
+        title: string;
+        description: string;
+        type: string;
+        image: string;
+        url: string;
+    };
+    twitter: {
+        card: string;
+        title: string;
+        description: string;
+        image: string;
+        site: string;
+    };
+    /** JSON-LD nodes (site schema first, then the page's), already flattened + de-empted. */
+    jsonLd: Array<Record<string, unknown>>;
+}
+/**
+ * Merge a page's own SEO over the site defaults. Identical precedence to the server's
+ * `mergeSeoMeta`: page meta wins, then site defaults, then sensible fallbacks.
+ */
+declare function resolveSeo(page: SeoInput, defaults?: SiteSeoDefaults): ResolvedSeo;
+
+/**
+ * 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[]>;
+
+/**
+ * Admin pages methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface PageListOptions {
+    page?: number;
+    limit?: number;
+}
+interface CreatePageInput {
+    title: string;
+    slug: string;
+    metaTitle?: string;
+    metaDescription?: string;
+    status?: "draft" | "published";
+}
+interface UpdatePageInput extends Partial<CreatePageInput> {
+}
+declare function listPages(client: BetterCMSAdminClient, opts?: PageListOptions): Promise<Page[]>;
+declare function getPage(client: BetterCMSAdminClient, id: string): Promise<Page>;
+declare function createPage(client: BetterCMSAdminClient, data: CreatePageInput): Promise<Page>;
+declare function updatePage(client: BetterCMSAdminClient, id: string, data: UpdatePageInput): Promise<Page>;
+declare function deletePage(client: BetterCMSAdminClient, id: string): Promise<void>;
+declare function publishPage(client: BetterCMSAdminClient, id: string): Promise<Page>;
+
+/**
+ * Admin media methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface MediaListOptions {
+    page?: number;
+    limit?: number;
+}
+interface MediaMetadata {
+    alt?: string;
+    caption?: string;
+}
+declare function listMedia(client: BetterCMSAdminClient, opts?: MediaListOptions): Promise<MediaAsset[]>;
+declare function getMedia(client: BetterCMSAdminClient, id: string): Promise<MediaAsset>;
+declare function uploadMedia(client: BetterCMSAdminClient, file: File, metadata?: MediaMetadata): Promise<MediaAsset>;
+declare function deleteMedia(client: BetterCMSAdminClient, id: string): Promise<void>;
+
+/**
+ * Admin forms methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface FormListOptions {
+    page?: number;
+    limit?: number;
+}
+interface CreateFormInput {
+    name: string;
+    description?: string;
+    fields?: FormFieldInput[];
+    submitLabel?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    webhookUrl?: string;
+}
+interface FormFieldInput {
+    key: string;
+    label: string;
+    type: "text" | "email" | "textarea" | "select" | "checkbox" | "number";
+    placeholder?: string;
+    required?: boolean;
+    options?: string[];
+}
+interface UpdateFormInput extends Partial<Omit<CreateFormInput, "fields">> {
+    fields?: FormFieldInput[];
+}
+declare function listForms(client: BetterCMSAdminClient, opts?: FormListOptions): Promise<Form[]>;
+declare function getForm(client: BetterCMSAdminClient, id: string): Promise<Form>;
+declare function createForm(client: BetterCMSAdminClient, data: CreateFormInput): Promise<Form>;
+declare function updateForm(client: BetterCMSAdminClient, id: string, data: UpdateFormInput): Promise<Form>;
+declare function deleteForm(client: BetterCMSAdminClient, id: string): Promise<void>;
+
+/**
+ * Admin submissions methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface SubmissionListOptions {
+    page?: number;
+    limit?: number;
+}
+declare function listSubmissions(client: BetterCMSAdminClient, opts?: SubmissionListOptions): Promise<FormSubmission[]>;
+declare function getSubmission(client: BetterCMSAdminClient, id: string): Promise<FormSubmission>;
+declare function deleteSubmission(client: BetterCMSAdminClient, id: string): Promise<void>;
+
+/**
+ * Admin workspaces methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+interface CreateWorkspaceInput {
+    name: string;
+    slug: string;
+    customDomain?: string;
+    planId: string;
+}
+interface UpdateWorkspaceInput {
+    name?: string;
+    slug?: string;
+    customDomain?: string | null;
+}
+declare function listWorkspaces(client: BetterCMSAdminClient): Promise<Workspace[]>;
+declare function getWorkspace(client: BetterCMSAdminClient, id: string): Promise<Workspace>;
+declare function createWorkspace(client: BetterCMSAdminClient, data: CreateWorkspaceInput): Promise<Workspace>;
+declare function updateWorkspace(client: BetterCMSAdminClient, id: string, data: UpdateWorkspaceInput): Promise<Workspace>;
+declare function deleteWorkspace(client: BetterCMSAdminClient, id: string): Promise<void>;
+
+/**
+ * Admin API keys methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+/** ApiKey with raw key — returned only on creation or regeneration. */
+interface ApiKeyWithRaw extends ApiKey {
+    key: string;
+}
+interface CreateApiKeyInput {
+    name: string;
+    permissions?: ApiKeyPermission[];
+    tokenType?: ApiKeyTokenType;
+    description?: string;
+    expiresAt?: string;
+    rateLimit?: number;
+}
+interface UpdateApiKeyInput {
+    name?: string;
+    permissions?: ApiKeyPermission[];
+    tokenType?: ApiKeyTokenType;
+    description?: string | null;
+    expiresAt?: string | null;
+    rateLimit?: number | null;
+}
+interface ApiKeyUsage {
+    keyId: string;
+    name: string;
+    lastUsedAt: string | null;
+    createdAt: string;
+    totalRequests: number;
+}
+declare function listApiKeys(client: BetterCMSAdminClient): Promise<ApiKey[]>;
+declare function createApiKey(client: BetterCMSAdminClient, data: CreateApiKeyInput): Promise<ApiKeyWithRaw>;
+declare function updateApiKey(client: BetterCMSAdminClient, id: string, data: UpdateApiKeyInput): Promise<ApiKey>;
+declare function regenerateApiKey(client: BetterCMSAdminClient, id: string): Promise<ApiKeyWithRaw>;
+declare function getApiKeyUsage(client: BetterCMSAdminClient, id: string): Promise<ApiKeyUsage>;
+declare function revokeApiKey(client: BetterCMSAdminClient, id: string): Promise<void>;
+
+/**
+ * Admin members methods.
+ * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
+ */
+
+type MemberRole = "owner" | "admin" | "editor" | "viewer";
+interface Member {
+    id: string;
+    userId: string;
+    email: string | null;
+    name: string | null;
+    role: MemberRole;
+    joinedAt: string;
+}
+interface PendingInvite {
+    id: string;
+    email: string;
+    role: MemberRole;
+    expiresAt: string;
+}
+declare function listMembers(client: BetterCMSAdminClient, workspaceId: string, opts?: {
+    page?: number;
+    limit?: number;
+}): Promise<Member[]>;
+declare function getMember(client: BetterCMSAdminClient, workspaceId: string, memberId: string): Promise<Member>;
+declare function inviteMember(client: BetterCMSAdminClient, workspaceId: string, data: {
+    email: string;
+    role: MemberRole;
+}): Promise<PendingInvite>;
+declare function updateMemberRole(client: BetterCMSAdminClient, workspaceId: string, memberId: string, role: MemberRole): Promise<Member>;
+declare function removeMember(client: BetterCMSAdminClient, workspaceId: string, memberId: string): Promise<void>;
+
+export { type AddPageFieldsInput, type ApiKeyUsage, type ApiKeyWithRaw, type AuthResult, BetterCMSError as BCMSClientError, ErrorCodes as BCMSErrorCodes, BetterCMS, BetterCMSAdminClient, type BetterCMSAdminOptions, BetterCMSDeliveryClient, BetterCMSError, BetterCMSManagementClient, type BetterCMSManagementOptions, type BetterCMSReadClient, type BetterCMSSiteOptions, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, type PageListOptions, type PendingInvite, type ResolvedSeo, type SearchHit, type SearchOptions, type SeoInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, addModelFields, addPageFields, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };