@bettercms-ai/sdk 1.25.0 → 1.26.1

package/dist/index.d.cts

@@ -1134,7 +1134,11 @@ interface CreateClientOptions {
     workspace: string;
     /** Delivery API key. Use a `content:read:draft` key for drafts. */
     apiKey?: string;
-    /** Optional project scope for forms. */
+    /**
+     * The project every read is addressed to. A workspace holds many projects whose slugs
+     * collide (each has a `blog` model and a `home` page), so a site names its own; published
+     * reads need no key for it. BetterCMS hosting supplies `PUBLIC_BCMS_PROJECT_ID`.
+     */
     projectId?: string;
     /** `published` (default) or `drafts`. */
     perspective?: Perspective;
@@ -1473,6 +1477,56 @@ interface SearchOptions {
 /** Search a published site. Resolves with hits, or [] on an empty query / network error. */
 declare function search(opts: SearchOptions): Promise<SearchHit[]>;
 
+/**
+ * The published content snapshot, read where the site RUNS — not bundled into it.
+ *
+ * Every BetterCMS build gets the published content as `bcms-content.json` in the project root,
+ * and a server app hosted on BetterCMS runs with `BCMS_CONTENT_FILE` pointing at a copy the
+ * platform rewrites on every publish. Read through this, a server-rendered page shows a publish
+ * within seconds and the publish never rebuilds the site. Import the JSON instead (a JSON import,
+ * `import.meta.glob`) and the bundle holds a frozen copy no publish can reach: the platform then
+ * has to rebuild the whole site for every edit.
+ *
+ * - On a hosted server: `BCMS_CONTENT_FILE`, re-read when it changes (checked at most once a second).
+ * - At build time and in local dev: `<cwd>/bcms-content.json`, the snapshot the build was given.
+ * - Anywhere without a filesystem (a browser, an edge runtime): `null`.
+ *
+ * A file that cannot be read keeps the last good copy; never throws into a render.
+ * No `node:fs` import at module scope, so the SDK stays safe to bundle for the browser.
+ */
+/** The snapshot's shape (`bcms-content/v1`, written by the platform's content fetch). */
+interface PublishedContent {
+    generatedAt?: string;
+    apiUrl?: string | null;
+    workspace?: string;
+    projectId?: string | null;
+    /** Published entries by model slug; each row carries its own `slug` and its field values. */
+    collections?: Record<string, Array<Record<string, unknown> & {
+        slug?: string;
+    }>>;
+    pages?: unknown[];
+    components?: unknown[];
+    forms?: unknown[];
+    layout?: unknown;
+    [key: string]: unknown;
+}
+/** Where the published content is read from here, or null where there is no filesystem. */
+declare function publishedContentFile(): string | null;
+/**
+ * The published content snapshot, or null when there is none here (no file, no filesystem).
+ * Call it per render — it is cached and cheap — never once at module scope, which would freeze it.
+ */
+declare function readPublishedContent<T extends PublishedContent = PublishedContent>(): T | null;
+/**
+ * One published entry by its slug, searched across every collection (first match wins, in the
+ * snapshot's model order). Not keyed by model slug: a page's backing model is named by the CMS.
+ */
+declare function publishedEntry<T extends Record<string, unknown> = Record<string, unknown>>(slug: string): (T & {
+    slug: string;
+}) | null;
+/** Test seam: forget the cached snapshot. */
+declare function resetPublishedContentCache(): void;
+
 /**
  * Admin pages methods.
  * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
@@ -1748,4 +1802,4 @@ 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, type CommandManagedLayoutInput, 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 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 UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, 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, updatePageModel, 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 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, 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 UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, 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, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };

package/dist/index.d.ts

@@ -1134,7 +1134,11 @@ interface CreateClientOptions {
     workspace: string;
     /** Delivery API key. Use a `content:read:draft` key for drafts. */
     apiKey?: string;
-    /** Optional project scope for forms. */
+    /**
+     * The project every read is addressed to. A workspace holds many projects whose slugs
+     * collide (each has a `blog` model and a `home` page), so a site names its own; published
+     * reads need no key for it. BetterCMS hosting supplies `PUBLIC_BCMS_PROJECT_ID`.
+     */
     projectId?: string;
     /** `published` (default) or `drafts`. */
     perspective?: Perspective;
@@ -1473,6 +1477,56 @@ interface SearchOptions {
 /** Search a published site. Resolves with hits, or [] on an empty query / network error. */
 declare function search(opts: SearchOptions): Promise<SearchHit[]>;
 
+/**
+ * The published content snapshot, read where the site RUNS — not bundled into it.
+ *
+ * Every BetterCMS build gets the published content as `bcms-content.json` in the project root,
+ * and a server app hosted on BetterCMS runs with `BCMS_CONTENT_FILE` pointing at a copy the
+ * platform rewrites on every publish. Read through this, a server-rendered page shows a publish
+ * within seconds and the publish never rebuilds the site. Import the JSON instead (a JSON import,
+ * `import.meta.glob`) and the bundle holds a frozen copy no publish can reach: the platform then
+ * has to rebuild the whole site for every edit.
+ *
+ * - On a hosted server: `BCMS_CONTENT_FILE`, re-read when it changes (checked at most once a second).
+ * - At build time and in local dev: `<cwd>/bcms-content.json`, the snapshot the build was given.
+ * - Anywhere without a filesystem (a browser, an edge runtime): `null`.
+ *
+ * A file that cannot be read keeps the last good copy; never throws into a render.
+ * No `node:fs` import at module scope, so the SDK stays safe to bundle for the browser.
+ */
+/** The snapshot's shape (`bcms-content/v1`, written by the platform's content fetch). */
+interface PublishedContent {
+    generatedAt?: string;
+    apiUrl?: string | null;
+    workspace?: string;
+    projectId?: string | null;
+    /** Published entries by model slug; each row carries its own `slug` and its field values. */
+    collections?: Record<string, Array<Record<string, unknown> & {
+        slug?: string;
+    }>>;
+    pages?: unknown[];
+    components?: unknown[];
+    forms?: unknown[];
+    layout?: unknown;
+    [key: string]: unknown;
+}
+/** Where the published content is read from here, or null where there is no filesystem. */
+declare function publishedContentFile(): string | null;
+/**
+ * The published content snapshot, or null when there is none here (no file, no filesystem).
+ * Call it per render — it is cached and cheap — never once at module scope, which would freeze it.
+ */
+declare function readPublishedContent<T extends PublishedContent = PublishedContent>(): T | null;
+/**
+ * One published entry by its slug, searched across every collection (first match wins, in the
+ * snapshot's model order). Not keyed by model slug: a page's backing model is named by the CMS.
+ */
+declare function publishedEntry<T extends Record<string, unknown> = Record<string, unknown>>(slug: string): (T & {
+    slug: string;
+}) | null;
+/** Test seam: forget the cached snapshot. */
+declare function resetPublishedContentCache(): void;
+
 /**
  * Admin pages methods.
  * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
@@ -1748,4 +1802,4 @@ 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, type CommandManagedLayoutInput, 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 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 UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, 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, updatePageModel, 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 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, 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 UpdateWebhookInput, type UpdateWorkspaceInput, type UploadAssetInput, type UploadedAsset, type Webhook, type WebhookAdvancedConfig, type WebhookEvent, type WebhookListResponse, type WebhookWithSecret, 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, publishedContentFile, publishedEntry, readPublishedContent, regenerateApiKey, removeMember, resetPublishedContentCache, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updatePageModel, updateWorkspace, uploadMedia };

package/dist/index.js

@@ -1270,7 +1270,8 @@ function createClient(options) {
         depth: opts?.depth,
         select: opts?.select?.join(","),
         perspective: draft ? "draft" : void 0,
-        stega: draft && stega ? "1" : void 0
+        stega: draft && stega ? "1" : void 0,
+        projectId: defaultProjectId
       })}`;
       return unwrap(await fetchJSON(url));
     },
@@ -1282,7 +1283,8 @@ function createClient(options) {
         depth: opts?.depth,
         select: opts?.select?.join(","),
         perspective: draft ? "draft" : void 0,
-        stega: draft && stega ? "1" : void 0
+        stega: draft && stega ? "1" : void 0,
+        projectId: defaultProjectId
       })}`;
       return unwrap(await fetchJSON(url));
     },
@@ -1316,19 +1318,21 @@ function createClient(options) {
     async listPages(opts) {
       const url = `${base}/pages${qs({
         page: opts?.page,
-        perPage: opts?.perPage
+        perPage: opts?.perPage,
+        projectId: defaultProjectId
       })}`;
       return unwrap(await fetchJSON(url));
     },
     async listComponents() {
       const url = `${base}/components${qs({
         perspective: draft ? "draft" : void 0,
-        token: draft ? previewToken : void 0
+        token: draft ? previewToken : void 0,
+        projectId: defaultProjectId
       })}`;
       return unwrap(await fetchJSON(url));
     },
     async getLayout() {
-      const url = `${base}/layout${draft ? "?perspective=draft" : ""}`;
+      const url = `${base}/layout${qs({ perspective: draft ? "draft" : void 0, projectId: defaultProjectId })}`;
       try {
         return unwrap(await fetchJSON(url));
       } catch (error) {
@@ -1562,6 +1566,45 @@ async function search(opts) {
   }
 }
 
+// src/published-content.ts
+var cache = null;
+var checkedAt = 0;
+function publishedContentFile() {
+  const proc = globalThis.process;
+  if (typeof proc?.getBuiltinModule !== "function") return null;
+  return proc.env?.BCMS_CONTENT_FILE || `${proc.cwd?.() ?? "."}/bcms-content.json`;
+}
+function readPublishedContent() {
+  const file = publishedContentFile();
+  if (!file) return null;
+  const now = Date.now();
+  if (cache && cache.file === file && now - checkedAt < 1e3) return cache.content;
+  checkedAt = now;
+  const proc = globalThis.process;
+  const fs = proc.getBuiltinModule("node:fs");
+  try {
+    const stamp = fs.statSync(file).mtimeMs;
+    if (cache && cache.file === file && cache.stamp === stamp) return cache.content;
+    cache = { file, stamp, content: JSON.parse(fs.readFileSync(file, "utf8")) };
+  } catch {
+    if (!cache || cache.file !== file) cache = { file, stamp: -1, content: null };
+  }
+  return cache.content;
+}
+function publishedEntry(slug) {
+  const collections = readPublishedContent()?.collections ?? {};
+  for (const rows of Object.values(collections)) {
+    if (!Array.isArray(rows)) continue;
+    const hit = rows.find((row) => row?.slug === slug);
+    if (hit) return hit;
+  }
+  return null;
+}
+function resetPublishedContentCache() {
+  cache = null;
+  checkedAt = 0;
+}
+
 // src/index.ts
 import {
   default as default2,
@@ -1923,8 +1966,12 @@ export {
   portableText,
   publishManagedLayout,
   publishPage,
+  publishedContentFile,
+  publishedEntry,
+  readPublishedContent,
   regenerateApiKey,
   removeMember,
+  resetPublishedContentCache,
   resolveSeo,
   revokeApiKey,
   rich,