@bettercms-ai/sdk 1.20.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, DeliveryEntrySeo, 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';
 
@@ -397,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).
@@ -568,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 {
@@ -663,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;
 }
 
 /**
@@ -889,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;
@@ -1457,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[];
 }

package/dist/index.d.ts

@@ -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, DeliveryEntrySeo, 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';
 
@@ -397,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).
@@ -568,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 {
@@ -663,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;
 }
 
 /**
@@ -889,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;
@@ -1457,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[];
 }

package/dist/index.js

@@ -519,12 +519,13 @@ async function updateModel(client, id, input) {
   );
   return res.data;
 }
+var withWarnings = (res) => res.warnings?.length ? { ...res.data, warnings: res.warnings } : res.data;
 async function createEntry(client, input) {
   const res = await client.fetchJSON(
     client.url("/management/content/entries"),
     { method: "POST", body: JSON.stringify(input) }
   );
-  return res.data;
+  return withWarnings(res);
 }
 async function updateEntry(client, id, input, opts) {
   const headers = {};
@@ -533,7 +534,7 @@ async function updateEntry(client, id, input, opts) {
     client.url(`/management/content/entries/${id}`),
     { method: "PATCH", body: JSON.stringify(input), headers }
   );
-  return res.data;
+  return withWarnings(res);
 }
 async function deleteManagedPage(client, id) {
   const res = await client.fetchJSON(