@bettercms-ai/sdk 1.30.1 → 1.31.0

package/dist/index.d.cts

@@ -768,6 +768,8 @@ interface ManagedComponent {
     thumbnail?: string | null;
     /** How an instance reads as a row in a parent's slot list. @see ComponentPreview */
     preview?: ComponentPreview | null;
+    /** The block icon (a /kit schema's document-level `icon`), a dock icon name. */
+    icon?: string | null;
     /** Send it back as `ifMatch` on updateComponent. */
     optimisticVersion?: number;
 }
@@ -789,6 +791,8 @@ interface ManagedComponentInput {
     description?: string;
     /** title/subtitle/media name top-level prop keys (422 `preview_key_unknown` otherwise); null clears it. */
     preview?: ComponentPreview | null;
+    /** The block icon, a dock icon name (bettercms://icons/dock); null clears it. */
+    icon?: string | null;
     blockJson?: unknown[];
     props?: unknown[];
     /**
@@ -1429,6 +1433,16 @@ declare function plain(value: TextOrRich): string;
  * alone, so a body field still renders as a document.
  */
 declare function rich(value: TextOrRich, fallback?: string): string;
+/**
+ * Renderable HTML for a ONE-LINE place: a heading, a button, a caption. `rich()`, except that several
+ * paragraphs are that place's LINES, joined with `<br>` (a heading-styled first block counts as one).
+ *
+ * An author who presses Enter in a heading's editor stores a second paragraph. `rich()` leaves it a
+ * paragraph, and `<h1><p>…</p><p>…</p></h1>` is what the build then draws, while a publish between
+ * builds writes the same value into the built heading as lines. This draws what the publish draws.
+ * A value holding anything else (a list, an image, a table) is returned as `rich()` returns it.
+ */
+declare function lines(value: TextOrRich, fallback?: string): string;
 
 /**
  * resolveSeo — framework-agnostic page-over-site SEO merge for headless consumers.
@@ -1900,4 +1914,29 @@ interface WebhookListResponse {
     };
 }
 
-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, CONTENT_APPLIED, type CommandManagedLayoutInput, type ContentAppliedMessage, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWebhookInput, 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, type ModelFieldset, PORTABLE_TEXT_FORMAT, type PageCreateReport, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type PublishedContent, type ResolvedSeo, type RichTextValue, STEGA_OPEN, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaNode, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateAssetInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, contentApplied, 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, onContentApplied, plain, portableText, publishManagedLayout, publishPage, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, resolveStega, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stegaClean, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };
+/**
+ * `inEditor()`: is this page running inside the BetterCMS Visual Editor's canvas?
+ *
+ * The editor frames the site and names the frame, so the answer is the page's own `window.name`:
+ * there from the first script, kept through every navigation inside the frame, and never set on
+ * a published page a visitor opens. A site asks before it starts what the canvas cannot share:
+ *
+ *   const smooth = inEditor() ? null : new LocomotiveScroll({ el, smooth: true });
+ *
+ * The canvas owns the scroll, the pointer and the place on the page; the site's motion (scroll
+ * triggers, timelines, WebGL scenes) runs there as it does live. What has to stand down is only
+ * what takes those three away: scroll that is not the window's own, an intro that holds the
+ * page, a cursor drawn over it.
+ */
+/** The canvas frame's name. The dashboard sets this exact word (`EDITOR_FRAME_NAME`). */
+declare const EDITOR_FRAME_NAME = "bcms-editor";
+/** The least of `window` this needs. */
+interface FramedWindow {
+    name: string;
+    self: unknown;
+    top: unknown;
+}
+/** True inside the editor's canvas. Safe where there is no window (a server render): false. */
+declare function inEditor(win?: FramedWindow | undefined): boolean;
+
+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, CONTENT_APPLIED, type CommandManagedLayoutInput, type ContentAppliedMessage, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWebhookInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, EDITOR_FRAME_NAME, 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, type ModelFieldset, PORTABLE_TEXT_FORMAT, type PageCreateReport, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type PublishedContent, type ResolvedSeo, type RichTextValue, STEGA_OPEN, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaNode, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateAssetInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, contentApplied, 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, inEditor, inviteMember, isMultiValueField, isRichText, lines, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, onContentApplied, plain, portableText, publishManagedLayout, publishPage, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, resolveStega, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stegaClean, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };

package/dist/index.d.ts

@@ -768,6 +768,8 @@ interface ManagedComponent {
     thumbnail?: string | null;
     /** How an instance reads as a row in a parent's slot list. @see ComponentPreview */
     preview?: ComponentPreview | null;
+    /** The block icon (a /kit schema's document-level `icon`), a dock icon name. */
+    icon?: string | null;
     /** Send it back as `ifMatch` on updateComponent. */
     optimisticVersion?: number;
 }
@@ -789,6 +791,8 @@ interface ManagedComponentInput {
     description?: string;
     /** title/subtitle/media name top-level prop keys (422 `preview_key_unknown` otherwise); null clears it. */
     preview?: ComponentPreview | null;
+    /** The block icon, a dock icon name (bettercms://icons/dock); null clears it. */
+    icon?: string | null;
     blockJson?: unknown[];
     props?: unknown[];
     /**
@@ -1429,6 +1433,16 @@ declare function plain(value: TextOrRich): string;
  * alone, so a body field still renders as a document.
  */
 declare function rich(value: TextOrRich, fallback?: string): string;
+/**
+ * Renderable HTML for a ONE-LINE place: a heading, a button, a caption. `rich()`, except that several
+ * paragraphs are that place's LINES, joined with `<br>` (a heading-styled first block counts as one).
+ *
+ * An author who presses Enter in a heading's editor stores a second paragraph. `rich()` leaves it a
+ * paragraph, and `<h1><p>…</p><p>…</p></h1>` is what the build then draws, while a publish between
+ * builds writes the same value into the built heading as lines. This draws what the publish draws.
+ * A value holding anything else (a list, an image, a table) is returned as `rich()` returns it.
+ */
+declare function lines(value: TextOrRich, fallback?: string): string;
 
 /**
  * resolveSeo — framework-agnostic page-over-site SEO merge for headless consumers.
@@ -1900,4 +1914,29 @@ interface WebhookListResponse {
     };
 }
 
-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, CONTENT_APPLIED, type CommandManagedLayoutInput, type ContentAppliedMessage, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWebhookInput, 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, type ModelFieldset, PORTABLE_TEXT_FORMAT, type PageCreateReport, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type PublishedContent, type ResolvedSeo, type RichTextValue, STEGA_OPEN, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaNode, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateAssetInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, contentApplied, 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, onContentApplied, plain, portableText, publishManagedLayout, publishPage, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, resolveStega, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stegaClean, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };
+/**
+ * `inEditor()`: is this page running inside the BetterCMS Visual Editor's canvas?
+ *
+ * The editor frames the site and names the frame, so the answer is the page's own `window.name`:
+ * there from the first script, kept through every navigation inside the frame, and never set on
+ * a published page a visitor opens. A site asks before it starts what the canvas cannot share:
+ *
+ *   const smooth = inEditor() ? null : new LocomotiveScroll({ el, smooth: true });
+ *
+ * The canvas owns the scroll, the pointer and the place on the page; the site's motion (scroll
+ * triggers, timelines, WebGL scenes) runs there as it does live. What has to stand down is only
+ * what takes those three away: scroll that is not the window's own, an intro that holds the
+ * page, a cursor drawn over it.
+ */
+/** The canvas frame's name. The dashboard sets this exact word (`EDITOR_FRAME_NAME`). */
+declare const EDITOR_FRAME_NAME = "bcms-editor";
+/** The least of `window` this needs. */
+interface FramedWindow {
+    name: string;
+    self: unknown;
+    top: unknown;
+}
+/** True inside the editor's canvas. Safe where there is no window (a server render): false. */
+declare function inEditor(win?: FramedWindow | undefined): boolean;
+
+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, CONTENT_APPLIED, type CommandManagedLayoutInput, type ContentAppliedMessage, type CreateApiKeyInput, type CreateClientOptions, type CreateEntryInput, type CreateFormInput, type CreateManagedPageInput, type CreateModelInput, type CreatePageInput, type CreateWebhookInput, type CreateWorkspaceInput, type DeliveryForm, type DeliveryFormField, type DeliveryFormFieldType, EDITOR_FRAME_NAME, 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, type ModelFieldset, PORTABLE_TEXT_FORMAT, type PageCreateReport, type PageListOptions, type PendingInvite, type PublishManagedLayoutInput, type PublishedContent, type ResolvedSeo, type RichTextValue, STEGA_OPEN, type SearchHit, type SearchOptions, type SeoInput, type SeoLocation, type SeoMeta, type SeoMetaInput, type SetPageContentInput, type StegaNode, type StegaPayload, type SubmissionListOptions, type SubmitFormOptions, type SubmitFormResult, type TextOrRich, type UpdateApiKeyInput, type UpdateAssetInput, type UpdateEntryInput, type UpdateFormInput, type UpdateModelInput, type UpdatePageInput, type UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, type WriteContentInput, addModelFields, addPageFields, asStringArray, commandManagedLayout, contentApplied, 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, inEditor, inviteMember, isMultiValueField, isRichText, lines, listApiKeys, listEntries, listForms, listManagedPages, listMedia, listMembers, listModels, listPages, listSubmissions, listWorkspaces, onContentApplied, plain, portableText, publishManagedLayout, publishPage, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, resolveStega, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stegaClean, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };

package/dist/index.js

@@ -1461,6 +1461,15 @@ function rich(value, fallback = "") {
   const html = (typeof value === "string" ? escapeHtml(value) : isRichText(value) ? value.html ?? "" : "").trim();
   return html ? unwrapLoneBlock(html) : escapeHtml(fallback);
 }
+function lines(value, fallback = "") {
+  const html = rich(value, fallback);
+  const block = /<(p|h[1-6])(?:\s[^>]*)?>([\s\S]*?)<\/\1>/gi;
+  if (html.length > 1e4) return html;
+  const found = [...html.matchAll(block)];
+  if (found.length < 2 || html.replace(block, "").trim() !== "") return html;
+  const shown = found.map((m) => m[2].trim()).filter((line) => line.replace(/<br\s*\/?>/gi, "").trim() !== "");
+  return shown.length ? shown.join("<br>") : html;
+}
 function unwrapLoneBlock(html) {
   const m = html.match(/^<(p|div|h[1-6])(?:\s[^>]*)?>([\s\S]*)<\/\1>$/i);
   return m && !new RegExp(`</${m[1]}>`, "i").test(m[2]) ? m[2] : html;
@@ -1951,6 +1960,16 @@ async function submitForm(opts) {
 
 // src/index.ts
 import { isBlock, getBlockType } from "@bettercms-ai/types";
+
+// src/in-editor.ts
+var EDITOR_FRAME_NAME = "bcms-editor";
+function inEditor(win = globalThis.window) {
+  try {
+    return !!win && win.name === EDITOR_FRAME_NAME && win.self !== win.top;
+  } catch {
+    return false;
+  }
+}
 export {
   BetterCMSError as BCMSClientError,
   ErrorCodes as BCMSErrorCodes,
@@ -1960,6 +1979,7 @@ export {
   BetterCMSError,
   BetterCMSManagementClient,
   CONTENT_APPLIED,
+  EDITOR_FRAME_NAME,
   ErrorCodes,
   PORTABLE_TEXT_FORMAT,
   STEGA_OPEN,
@@ -2001,10 +2021,12 @@ export {
   default2 as imageUrlBuilder,
   imageValueObjectPosition,
   imageValueUrl,
+  inEditor,
   inviteMember,
   isBlock,
   isMultiValueField,
   isRichText,
+  lines,
   listApiKeys,
   listEntries,
   listForms2 as listForms,