@bettercms-ai/sdk 1.19.0 → 1.21.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _bettercms_ai_types from '@bettercms-ai/types';
-import { ContentPageResult, Content, DeliveredLayout, ContentModelField, BetterCMSErrorCode, LayoutStructureDocument, LayoutDataDocument, PageLayoutOverrideDocument, ManagementLayoutCommand, AuthUser, AuthSession, SignInInput, SignUpInput, Perspective, DeliveryEntry, DeliveryList, DeliveryPage, DeliveryComponent, PageMetaJson, SiteSeoDefaults, Page, MediaAsset, Form, FormSubmission, Workspace, ApiKey, ApiKeyPermission, ApiKeyTokenType } from '@bettercms-ai/types';
+import { ContentPageResult, Content, DeliveredLayout, ContentModelField, BetterCMSErrorCode, LayoutStructureDocument, LayoutDataDocument, PageLayoutOverrideDocument, ManagementLayoutCommand, AuthUser, AuthSession, SignInInput, SignUpInput, Perspective, DeliveryEntry, DeliveryList, DeliveryPage, DeliveryComponent, PageMetaJson, DeliveryEntrySeo, SiteSeoDefaults, Page, MediaAsset, FormField, 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, DeliveryComponent, 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';
 
@@ -223,6 +223,8 @@ interface ManagedContentModel {
     name: string;
     slug: string;
     description: string | null;
+    /** Public URL of one entry, e.g. `/blog/:slug` (`:slug` is the entry's slug). Null = none. */
+    urlPattern?: string | null;
     fields: ContentModelField[];
     createdAt: string;
     updatedAt: string;
@@ -274,6 +276,11 @@ interface CreateManagedPageInput {
 /** Append fields to an existing page's schema (additive — see addPageFields). */
 interface AddPageFieldsInput {
     addFields: ContentModelField[];
+    /**
+     * Optional insertion point: the key of an existing TOP-LEVEL field to insert after. Omit to
+     * append (the default). An unknown key is refused by the API, never silently appended.
+     */
+    after?: string;
 }
 interface CreateModelInput {
     name: string;
@@ -289,12 +296,27 @@ interface CreateModelInput {
      * a block would orphan every entry it already has.
      */
     kind?: "model" | "block";
+    /** Editor-only field grouping. Fields join one with `fieldsetId`. Order is the array index. */
+    fieldsets?: ModelFieldset[];
+    /** Public URL of one entry, e.g. `/blog/:slug`: starts with `/`, contains `:slug` exactly once. */
+    urlPattern?: string | null;
+}
+/** A named, editor-only group of a model's fields. Same shape as the dashboard's `Fieldset`. */
+interface ModelFieldset {
+    id: string;
+    name: string;
+    /** One line shown under the card title in the editor, at most 500 characters. */
+    description?: string;
 }
 interface UpdateModelInput {
     name?: string;
     slug?: string;
     description?: string;
     fields?: ContentModelField[];
+    /** Replaces the fieldset list. `null` drops every fieldset. Sent alone, it leaves `fields` untouched. */
+    fieldsets?: ModelFieldset[] | null;
+    /** Public URL of one entry, e.g. `/blog/:slug`. `null` (or "") clears it. */
+    urlPattern?: string | null;
 }
 interface CreateEntryInput {
     contentModelId: string;
@@ -308,6 +330,27 @@ interface UpdateEntryInput {
     status?: "draft" | "published";
     data?: Record<string, unknown>;
     pageId?: string | null;
+    /** The entry's native SEO. Merges into what is stored: an omitted key is kept, null or "" clears it. */
+    meta?: {
+        metaTitle?: string | null;
+        metaDescription?: string | null;
+        noindex?: boolean;
+        canonical?: string | null;
+        og?: {
+            title?: string | null;
+            description?: string | null;
+            image?: string | null;
+            type?: string | null;
+        } | null;
+        twitter?: {
+            card?: string | null;
+            title?: string | null;
+            description?: string | null;
+            image?: string | null;
+        } | null;
+        schemaType?: string | null;
+        schema?: Record<string, unknown> | Array<Record<string, unknown>> | null;
+    };
 }
 /** Set a page's field VALUES (the actual content). For a singleton, upserts its one entry. */
 interface SetPageContentInput {
@@ -354,14 +397,21 @@ declare function createModel(client: ManagementClient, input: CreateModelInput):
 /** 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>;
+/**
+ * Advisory notes the server attached to a write — e.g. `REFERENCE_NOT_FOUND: …` for a reference
+ * whose target was deleted. The write succeeded; present only when there is something to say.
+ */
+type EntryWriteWarnings = {
+    warnings?: string[];
+};
+declare function createEntry(client: ManagementClient, input: CreateEntryInput): Promise<ManagedContentEntry & EntryWriteWarnings>;
 /**
  * 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>;
+}): Promise<ManagedContentEntry & EntryWriteWarnings>;
 
 /**
  * Management API SDK method — media upload (P2).
@@ -385,6 +435,12 @@ interface UploadAssetInput {
     filename?: string;
     altText?: string;
     caption?: string;
+    /**
+     * Video/audio only: the spoken words (≤ 100,000 characters). Stored on the asset and published
+     * wherever the file is used. Sent as a second JSON call after the upload, because it is too
+     * long for the upload's query string.
+     */
+    transcript?: string;
     /** Target Media Library folder id (defaults to project root). */
     folderId?: string;
 }
@@ -393,6 +449,27 @@ interface UploadedAsset {
     url: string;
     key: string;
     filename: string;
+    /** Present when a transcript was written with the upload. */
+    transcript?: string;
+}
+/** Describe an existing asset. `null` clears a field; an omitted key is left alone. */
+interface UpdateAssetInput {
+    altText?: string | null;
+    caption?: string | null;
+    /** Video/audio only, ≤ 100,000 characters. */
+    transcript?: string | null;
+}
+interface ManagedMediaAsset {
+    id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    sizeBytes: number;
+    altText: string | null;
+    caption: string | null;
+    transcript: string | null;
+    folderId: string | null;
+    createdAt: string;
 }
 
 /** Semantic error codes used by the SDK. */
@@ -498,6 +575,75 @@ interface DeliveryFormField {
      * 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 {
@@ -593,6 +739,14 @@ interface ManagedFormInput {
     submitLabel?: string;
     successMessage?: string;
     redirectUrl?: string;
+    /** Require a Cloudflare Turnstile check on submit. Its secret key is set in the dashboard only. */
+    turnstileEnabled?: boolean;
+    /** Name of a hidden field that must stay empty; a filled one marks the submission as spam. */
+    honeypotField?: string | null;
+    /** Addresses notified of each submission. */
+    notifyEmails?: string[];
+    /** URL that receives each submission as a POST. */
+    webhookUrl?: string | null;
 }
 
 /**
@@ -819,10 +973,10 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     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>;
+    createEntry(input: CreateEntryInput): Promise<ManagedContentEntry & EntryWriteWarnings>;
     updateEntry(id: string, input: UpdateEntryInput, opts?: {
         ifMatch?: number;
-    }): Promise<ManagedContentEntry>;
+    }): Promise<ManagedContentEntry & EntryWriteWarnings>;
     /** Soft-delete a page and its content entries. */
     deletePage(id: string): Promise<{
         id: string;
@@ -840,6 +994,8 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     /** Get one content entry by id INCLUDING its data (incl. drafts). */
     getEntry(id: string): Promise<ManagedContentEntry>;
     uploadAsset(input: UploadAssetInput): Promise<UploadedAsset>;
+    /** Set an asset's alt text, caption or transcript (video/audio only). `null` clears. */
+    updateAsset(id: string, input: UpdateAssetInput): Promise<ManagedMediaAsset>;
     /** List forms in the key's project (or workspace-level). */
     listForms(): Promise<ManagedForm[]>;
     /** Get one form by id INCLUDING its field schema + settings. */
@@ -1213,6 +1369,10 @@ interface SeoInput {
     metaTitle?: string | null;
     metaDescription?: string | null;
     metaJson?: PageMetaJson | null;
+    /** `"home"` makes the Automatic JSON-LD a WebSite, as the hosted renderer does. */
+    slug?: string | null;
+    /** Exclude from search engines. Surfaces as `ResolvedSeo.noindex` / `robots`. */
+    noindex?: boolean | null;
 }
 /** Fully-resolved SEO values, page-over-site. Empty string ⇒ omit that tag. */
 interface ResolvedSeo {
@@ -1238,9 +1398,33 @@ interface ResolvedSeo {
         image: string;
         site: string;
     };
-    /** JSON-LD nodes (site schema first, then the page's), already flattened + de-empted. */
+    /**
+     * JSON-LD nodes (site schema first, then the page's), already flattened + de-empted. The page's
+     * part follows the renderer's precedence: Custom (`metaJson.schema`) > `metaJson.schemaType` >
+     * Automatic (WebPage; WebSite on the home page).
+     */
     jsonLd: Array<Record<string, unknown>>;
+    /** True when the page is excluded from search engines (the renderer's `<meta name="robots" content="noindex">`). */
+    noindex: boolean;
+    /** `noindex` in the `{ index, follow }` shape Next's `Metadata.robots` takes. */
+    robots: {
+        index: boolean;
+        follow: boolean;
+    };
 }
+/**
+ * A Delivery API entry as a `resolveSeo` input. The server already resolved the collection
+ * template's `{{field}}` tokens for this entry and merged the entry's own SEO over it, so this is
+ * a reshape, not a resolver:
+ *
+ *   const entry = await bcms.getEntry("astro");
+ *   const seo = resolveSeo(entrySeoInput(entry), siteDefaults, { siteUrl, path: `/tags/${entry.slug}` });
+ *   // seo.jsonLd holds the template's schema, resolved for this entry
+ */
+declare function entrySeoInput(entry: {
+    slug: string;
+    seo?: DeliveryEntrySeo | null;
+}): SeoInput;
 /** Where this page lives, so a canonical can be derived when the page sets none. */
 interface SeoLocation {
     /** Absolute site origin, e.g. `https://acme.com`. Trailing slash optional. */
@@ -1357,14 +1541,20 @@ interface CreateFormInput {
     redirectUrl?: string;
     webhookUrl?: string;
 }
-interface FormFieldInput {
-    key: string;
-    label: string;
-    type: "text" | "email" | "textarea" | "select" | "checkbox" | "number";
-    placeholder?: string;
-    required?: boolean;
-    options?: string[];
-}
+/**
+ * A field in an admin create/update payload.
+ *
+ * An ALIAS of `FormField`, not a copy. It used to be a hand-written interface and it had gone
+ * stale: it listed six of the thirteen field types the builder can author — `phone`, `date`,
+ * `url`, `radio`, `checkboxes`, `consent` and `hidden` were all missing — and omitted
+ * `helpText`, `hidden`, `defaultValue`, `showIf`, `validation` and `ui` entirely. A typed
+ * consumer of this client therefore could not express a phone field at all, let alone one with
+ * a country picker, even though the route accepts every one of them.
+ *
+ * The admin routes validate against `formFieldSchema`, which mirrors `FormField`, so aliasing
+ * is what keeps this honest: there is no second declaration left to drift.
+ */
+type FormFieldInput = FormField;
 interface UpdateFormInput extends Partial<Omit<CreateFormInput, "fields">> {
     fields?: FormFieldInput[];
 }
@@ -1480,4 +1670,4 @@ declare function inviteMember(client: BetterCMSAdminClient, workspaceId: string,
 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 CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedComponentSummary, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };
+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 CommandManagedLayoutInput, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, ErrorCodes, type ExtractionCandidate, type FormFieldInput, type FormListOptions, type FormSubmitError, type FormValue, type FormValues, type GetEntryOptions, type GetManagedLayoutOptions, type ListContentAllOptions, type ListContentOptions, type ListEntriesFilter, type ListEntriesOptions, type ListPagesOptions, type ManagedComponent, type ManagedComponentInput, type ManagedComponentSummary, type ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedMediaAsset, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, PORTABLE_TEXT_FORMAT, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type ResolvedSeo, type RichTextValue, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateAssetInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, createApiKey, createClient, createEntry, createForm, createManagedPage, createModel, createPage, createWorkspace, decodeStega, deleteForm, deleteMedia, deletePage, deleteSubmission, deleteWorkspace, encodeStega, entrySeoInput, formInitialValues, getApiKeyUsage, getEntry, getForm, getManagedLayout, getManagedPage, getMedia, getMember, getModel, getPage, getSubmission, getWorkspace, inviteMember, isMultiValueField, isRichText, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, plain, portableText, publishManagedLayout, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };