@bettercms-ai/sdk 1.13.1 → 1.14.0

package/dist/index.d.cts

@@ -51,11 +51,13 @@ declare function listContentAll(client: BetterCMSDeliveryClient, opts?: ListCont
 declare class BetterCMSDeliveryClient {
     readonly workspace: string;
     readonly baseUrl: string;
+    protected readonly timeout: number;
     private readonly apiKey?;
     constructor(opts: {
         workspace: string;
         apiKey?: string;
         baseUrl: string;
+        timeout?: number;
     });
     getContent(slug: string): Promise<_bettercms_ai_types.Content>;
     listContent(opts?: Parameters<typeof listContent>[1]): Promise<_bettercms_ai_types.PaginatedResult<_bettercms_ai_types.Content>>;
@@ -71,8 +73,13 @@ declare class BetterCMSDeliveryClient {
     /** 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.
+     * Generic fetch helper — retries 429/503 honouring Retry-After, applies a
+     * per-attempt timeout, and throws a typed BetterCMSError on non-OK responses.
+     *
+     * This path (BetterCMS.site()) previously had NO retry and NO timeout: the first
+     * 429 from the delivery limiter threw straight through and killed the caller. In a
+     * static build that is a failed deploy. See ./retry.ts for why a fixed ladder was
+     * never going to be enough against a 60-second fixed window.
      */
     fetchJSON<T>(url: string): Promise<T>;
 }
@@ -139,7 +146,7 @@ interface WebhookListResponse {
  *
  * Extends BetterCMSDeliveryClient but overrides:
  * - `headers()` — uses Bearer token auth instead of API key
- * - `fetchJSON()` — adds retry on 429/503 and 10s timeout per request
+ * - `fetchJSON()` — adds Retry-After-aware retry on 429/503 (see ./retry.ts)
  *
  * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
  */
@@ -158,13 +165,12 @@ interface BetterCMSAdminOptions {
  * 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.
+     * Admin fetchJSON with Retry-After-aware retry (429, 503) and a per-request
+     * timeout (AbortController). Each retry gets a fresh timeout.
      */
     fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
     /** Build the admin API URL. */
@@ -741,7 +747,11 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     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 with Retry-After-aware retry (429, 503) + per-request timeout
+     * (mirrors the admin client). See ./retry.ts for why the delay must be able
+     * to outlast the backend's 60-second rate-limit window.
+     */
     fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
     listModels(): Promise<ManagedContentModel[]>;
     getModel(id: string): Promise<ManagedContentModel>;
@@ -864,6 +874,12 @@ interface BetterCMSSiteOptions {
     apiKey?: string;
     /** Base URL of the Delivery API. Defaults to https://api.bettercms.ai/v1. */
     baseUrl?: string;
+    /**
+     * Per-attempt request timeout in ms. Defaults to 10000. Each of the 3 retries gets
+     * a fresh one. Raise it for a slow delivery origin rather than losing the timeout —
+     * without one, a hung socket stalls a build indefinitely.
+     */
+    timeout?: number;
 }
 /**
  * BetterCMS factory — returns a typed client for the Delivery API.
@@ -931,6 +947,21 @@ interface CreateClientOptions {
     stega?: boolean;
     /** Per-attempt timeout in ms. Defaults to 10000. */
     timeout?: number;
+    /**
+     * Collapse identical GETs to one network round-trip for the life of this client.
+     * Default false.
+     *
+     * Only correct where the content is a POINT-IN-TIME SNAPSHOT — i.e. a static build,
+     * where every route renders from the same published dataset. `@bettercms-ai/astro`
+     * turns this on automatically when Astro's `command === "build"` and never for `dev`,
+     * SSR or the drafts perspective, where a repeat read must see the current row.
+     *
+     * A static build without it re-fetches the same nav/settings/collection once PER ROUTE.
+     * That is what made a large site exhaust the delivery rate limit: hundreds of identical
+     * requests, and `getPage()` re-scanning every page of the paginated list each time it is
+     * called.
+     */
+    cache?: boolean;
 }
 interface ListEntriesOptions {
     /** Filter by content-model slug. */
@@ -1048,6 +1079,24 @@ interface RichTextValue {
      */
     readonly doc?: DocValue;
 }
+/** The marker on a Portable Text envelope. `format` is a plain string, never a union — see below. */
+declare const PORTABLE_TEXT_FORMAT = "portable-text-1";
+/**
+ * Structured blocks, when the field stores Portable Text.
+ *
+ * ── The compatibility guarantee, stated once ────────────────────────────────────────────
+ * Portable Text did NOT change this envelope. `format`, `value` and `html` are the same three
+ * keys they always were, so `isRichText`, `plain()` and `rich()` keep working untouched — and
+ * they have to, because sites compiled months ago read `.html` directly and cannot be
+ * rebuilt. `bettercms-starter-modern/lib/cms.ts` even carries its OWN copy of `rich()`, baked
+ * into deployments nobody can reach. Storing a bare array instead would have made
+ * `isRichText` return false (it rejects arrays), every shipped `rich()` call return "", and
+ * every one of those pages go blank at 200 OK.
+ *
+ * `portableText()` is therefore ADDITIVE: `html` remains the always-present field, and this is
+ * the opt-in for consumers that want to render structure with `@portabletext/react` instead.
+ */
+declare function portableText(value: TextOrRich): readonly unknown[] | null;
 /**
  * A field that may arrive as either shape. Type author-editable text fields with this and the
  * compiler routes you through `plain()`/`rich()`, so a type switch in the CMS can never reach
@@ -1362,4 +1411,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 ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, type PageListOptions, type PendingInvite, 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, 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 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 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, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };

package/dist/index.d.ts

@@ -51,11 +51,13 @@ declare function listContentAll(client: BetterCMSDeliveryClient, opts?: ListCont
 declare class BetterCMSDeliveryClient {
     readonly workspace: string;
     readonly baseUrl: string;
+    protected readonly timeout: number;
     private readonly apiKey?;
     constructor(opts: {
         workspace: string;
         apiKey?: string;
         baseUrl: string;
+        timeout?: number;
     });
     getContent(slug: string): Promise<_bettercms_ai_types.Content>;
     listContent(opts?: Parameters<typeof listContent>[1]): Promise<_bettercms_ai_types.PaginatedResult<_bettercms_ai_types.Content>>;
@@ -71,8 +73,13 @@ declare class BetterCMSDeliveryClient {
     /** 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.
+     * Generic fetch helper — retries 429/503 honouring Retry-After, applies a
+     * per-attempt timeout, and throws a typed BetterCMSError on non-OK responses.
+     *
+     * This path (BetterCMS.site()) previously had NO retry and NO timeout: the first
+     * 429 from the delivery limiter threw straight through and killed the caller. In a
+     * static build that is a failed deploy. See ./retry.ts for why a fixed ladder was
+     * never going to be enough against a 60-second fixed window.
      */
     fetchJSON<T>(url: string): Promise<T>;
 }
@@ -139,7 +146,7 @@ interface WebhookListResponse {
  *
  * Extends BetterCMSDeliveryClient but overrides:
  * - `headers()` — uses Bearer token auth instead of API key
- * - `fetchJSON()` — adds retry on 429/503 and 10s timeout per request
+ * - `fetchJSON()` — adds Retry-After-aware retry on 429/503 (see ./retry.ts)
  *
  * @see openspec/changes/flo-6-backend-sdk-admin/specs/sdk-admin-client/spec.md
  */
@@ -158,13 +165,12 @@ interface BetterCMSAdminOptions {
  * 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.
+     * Admin fetchJSON with Retry-After-aware retry (429, 503) and a per-request
+     * timeout (AbortController). Each retry gets a fresh timeout.
      */
     fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
     /** Build the admin API URL. */
@@ -741,7 +747,11 @@ declare class BetterCMSManagementClient extends BetterCMSDeliveryClient {
     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 with Retry-After-aware retry (429, 503) + per-request timeout
+     * (mirrors the admin client). See ./retry.ts for why the delay must be able
+     * to outlast the backend's 60-second rate-limit window.
+     */
     fetchJSON<T>(url: string, init?: RequestInit): Promise<T>;
     listModels(): Promise<ManagedContentModel[]>;
     getModel(id: string): Promise<ManagedContentModel>;
@@ -864,6 +874,12 @@ interface BetterCMSSiteOptions {
     apiKey?: string;
     /** Base URL of the Delivery API. Defaults to https://api.bettercms.ai/v1. */
     baseUrl?: string;
+    /**
+     * Per-attempt request timeout in ms. Defaults to 10000. Each of the 3 retries gets
+     * a fresh one. Raise it for a slow delivery origin rather than losing the timeout —
+     * without one, a hung socket stalls a build indefinitely.
+     */
+    timeout?: number;
 }
 /**
  * BetterCMS factory — returns a typed client for the Delivery API.
@@ -931,6 +947,21 @@ interface CreateClientOptions {
     stega?: boolean;
     /** Per-attempt timeout in ms. Defaults to 10000. */
     timeout?: number;
+    /**
+     * Collapse identical GETs to one network round-trip for the life of this client.
+     * Default false.
+     *
+     * Only correct where the content is a POINT-IN-TIME SNAPSHOT — i.e. a static build,
+     * where every route renders from the same published dataset. `@bettercms-ai/astro`
+     * turns this on automatically when Astro's `command === "build"` and never for `dev`,
+     * SSR or the drafts perspective, where a repeat read must see the current row.
+     *
+     * A static build without it re-fetches the same nav/settings/collection once PER ROUTE.
+     * That is what made a large site exhaust the delivery rate limit: hundreds of identical
+     * requests, and `getPage()` re-scanning every page of the paginated list each time it is
+     * called.
+     */
+    cache?: boolean;
 }
 interface ListEntriesOptions {
     /** Filter by content-model slug. */
@@ -1048,6 +1079,24 @@ interface RichTextValue {
      */
     readonly doc?: DocValue;
 }
+/** The marker on a Portable Text envelope. `format` is a plain string, never a union — see below. */
+declare const PORTABLE_TEXT_FORMAT = "portable-text-1";
+/**
+ * Structured blocks, when the field stores Portable Text.
+ *
+ * ── The compatibility guarantee, stated once ────────────────────────────────────────────
+ * Portable Text did NOT change this envelope. `format`, `value` and `html` are the same three
+ * keys they always were, so `isRichText`, `plain()` and `rich()` keep working untouched — and
+ * they have to, because sites compiled months ago read `.html` directly and cannot be
+ * rebuilt. `bettercms-starter-modern/lib/cms.ts` even carries its OWN copy of `rich()`, baked
+ * into deployments nobody can reach. Storing a bare array instead would have made
+ * `isRichText` return false (it rejects arrays), every shipped `rich()` call return "", and
+ * every one of those pages go blank at 200 OK.
+ *
+ * `portableText()` is therefore ADDITIVE: `html` remains the always-present field, and this is
+ * the opt-in for consumers that want to render structure with `@portabletext/react` instead.
+ */
+declare function portableText(value: TextOrRich): readonly unknown[] | null;
 /**
  * A field that may arrive as either shape. Type author-editable text fields with this and the
  * compiler routes you through `plain()`/`rich()`, so a type switch in the CMS can never reach
@@ -1362,4 +1411,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 ManagedContentEntry, type ManagedContentModel, type ManagedForm, type ManagedFormInput, type ManagedLayoutClient, type ManagedLayoutDocument, type ManagedPage, type ManagementClient, type MediaListOptions, type MediaMetadata, type Member, type MemberRole, type PageListOptions, type PendingInvite, 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, 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 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 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, publishPage, regenerateApiKey, removeMember, resolveSeo, revokeApiKey, rich, search, setPageContent, shouldShowField, signIn, signInWithGithub, signInWithGoogle, signUp, stripStega, submitForm, toggleOption, updateApiKey, updateEntry, updateForm, updateMemberRole, updateModel, updatePage, updateWorkspace, uploadMedia };

package/dist/index.js

@@ -89,6 +89,35 @@ var BetterCMSError = class _BetterCMSError extends Error {
   }
 };
 
+// src/retry.ts
+var RETRY_STATUSES = [429, 503];
+var MAX_RETRIES = 3;
+var MAX_DELAY_MS = 65e3;
+var BASE_DELAY_MS = 1e3;
+var JITTER_MS = 250;
+function isRetryableStatus(status) {
+  return RETRY_STATUSES.includes(status);
+}
+function retryAfterMs(res) {
+  const raw = res.headers?.get?.("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) {
+    return Math.min(Math.max(seconds, 0) * 1e3, MAX_DELAY_MS);
+  }
+  const at = Date.parse(raw);
+  if (!Number.isNaN(at)) {
+    return Math.min(Math.max(0, at - Date.now()), MAX_DELAY_MS);
+  }
+  return null;
+}
+function backoffMs(attempt, res) {
+  const fromServer = res ? retryAfterMs(res) : null;
+  const base = Math.min(fromServer ?? BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS - JITTER_MS);
+  return base + Math.random() * JITTER_MS;
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 // src/methods/getContent.ts
 async function getContent(client, slug) {
   const data = await client.fetchJSON(client.url(slug));
@@ -153,14 +182,17 @@ function listContentAll(client, opts) {
 }
 
 // src/delivery-client.ts
+var DEFAULT_TIMEOUT = 1e4;
 var BetterCMSDeliveryClient = class {
   workspace;
   baseUrl;
+  timeout;
   apiKey;
   constructor(opts) {
     this.workspace = opts.workspace;
     this.baseUrl = opts.baseUrl;
     this.apiKey = opts.apiKey;
+    this.timeout = opts.timeout ?? DEFAULT_TIMEOUT;
   }
   getContent(slug) {
     return getContent(this, slug);
@@ -193,24 +225,46 @@ var BetterCMSDeliveryClient = class {
     return headers;
   }
   /**
-   * Generic fetch helper — wraps a request with network-error handling
-   * and throws a typed BetterCMSError on non-OK responses.
+   * Generic fetch helper — retries 429/503 honouring Retry-After, applies a
+   * per-attempt timeout, and throws a typed BetterCMSError on non-OK responses.
+   *
+   * This path (BetterCMS.site()) previously had NO retry and NO timeout: the first
+   * 429 from the delivery limiter threw straight through and killed the caller. In a
+   * static build that is a failed deploy. See ./retry.ts for why a fixed ladder was
+   * never going to be enough against a 60-second fixed window.
    */
   async fetchJSON(url) {
-    let res;
-    try {
-      res = await globalThis.fetch(url, { headers: this.headers() });
-    } catch (err) {
-      throw new BetterCMSError(
-        `Network error: ${err instanceof Error ? err.message : String(err)}`,
-        0,
-        "NETWORK_ERROR"
-      );
-    }
-    if (!res.ok) {
+    for (let attempt = 0; ; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      let res;
+      try {
+        res = await globalThis.fetch(url, {
+          headers: this.headers(),
+          signal: controller.signal
+        });
+      } catch (err) {
+        const timedOut = err instanceof Error && err.name === "AbortError";
+        if (attempt < MAX_RETRIES) {
+          await sleep(backoffMs(attempt));
+          continue;
+        }
+        if (timedOut) throw new BetterCMSError("Request timeout", 408, "NETWORK_ERROR");
+        throw new BetterCMSError(
+          `Network error: ${err instanceof Error ? err.message : String(err)}`,
+          0,
+          "NETWORK_ERROR"
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+      if (res.ok) return await res.json();
+      if (attempt < MAX_RETRIES && isRetryableStatus(res.status)) {
+        await sleep(backoffMs(attempt, res));
+        continue;
+      }
       throw await BetterCMSError.from(res);
     }
-    return await res.json();
   }
 };
 
@@ -291,19 +345,15 @@ function addWebhookMethods(client) {
 
 // src/admin-client.ts
 var DEFAULT_BASE_URL = "https://api.bettercms.ai/v1";
-var DEFAULT_TIMEOUT = 1e4;
-var RETRY_STATUSES = [429, 503];
-var RETRY_DELAYS = [1e3, 2e3, 4e3];
 var BetterCMSAdminClient = class extends BetterCMSDeliveryClient {
-  timeout;
   _token;
   constructor(options) {
     super({
       workspace: "",
-      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      timeout: options.timeout
     });
     this._token = options.token;
-    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
   }
   headers() {
     return {
@@ -313,12 +363,12 @@ var BetterCMSAdminClient = class extends BetterCMSDeliveryClient {
     };
   }
   /**
-   * Admin fetchJSON with retry (429, 503) and per-request timeout (AbortController).
-   * Each retry gets a fresh timeout.
+   * Admin fetchJSON with Retry-After-aware retry (429, 503) and a per-request
+   * timeout (AbortController). Each retry gets a fresh timeout.
    */
   async fetchJSON(url, init) {
     let lastError;
-    for (let attempt = 0; attempt <= 3; attempt++) {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       let nonRetryable = false;
@@ -332,12 +382,12 @@ var BetterCMSAdminClient = class extends BetterCMSDeliveryClient {
         if (res.ok) {
           return res.json();
         }
-        const shouldRetry = attempt < 3 && RETRY_STATUSES.includes(res.status);
+        const shouldRetry = attempt < MAX_RETRIES && isRetryableStatus(res.status);
         if (!shouldRetry) {
           nonRetryable = true;
           throw await BetterCMSError.from(res);
         }
-        await sleep(RETRY_DELAYS[attempt] ?? 0);
+        await sleep(backoffMs(attempt, res));
       } catch (err) {
         clearTimeout(timeoutId);
         if (err instanceof Error && err.name === "AbortError") {
@@ -347,8 +397,8 @@ var BetterCMSAdminClient = class extends BetterCMSDeliveryClient {
           throw err;
         }
         lastError = err;
-        if (attempt < 3) {
-          await sleep(RETRY_DELAYS[attempt] ?? 0);
+        if (attempt < MAX_RETRIES) {
+          await sleep(backoffMs(attempt));
           continue;
         }
         throw err;
@@ -365,9 +415,6 @@ var BetterCMSAdminClient = class extends BetterCMSDeliveryClient {
     return addWebhookMethods(this);
   }
 };
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/methods/management/content.ts
 async function listModels(client) {
@@ -508,7 +555,14 @@ var MIME_BY_EXT = {
   avif: "image/avif",
   mp4: "video/mp4",
   webm: "video/webm",
-  pdf: "application/pdf"
+  pdf: "application/pdf",
+  // mp3/ogg were server-allowed all along; the SDK sent application/octet-stream for them,
+  // which the allowlist then refused — so an agent could never upload audio.
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  txt: "text/plain",
+  md: "text/markdown",
+  markdown: "text/markdown"
 };
 function basenameOf(p) {
   const clean = p.split(/[?#]/)[0] ?? p;
@@ -737,8 +791,6 @@ async function commandManagedLayout(client, input) {
 // src/management-client.ts
 var DEFAULT_BASE_URL2 = "https://api.bettercms.ai/v1";
 var DEFAULT_TIMEOUT2 = 1e4;
-var RETRY_STATUSES2 = [429, 503];
-var RETRY_DELAYS2 = [1e3, 2e3, 4e3];
 var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
   timeout;
   _apiKey;
@@ -760,10 +812,14 @@ var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
   url(path) {
     return `${this.baseUrl}${path}`;
   }
-  /** fetchJSON with retry (429, 503) + per-request timeout (mirrors the admin client). */
+  /**
+   * fetchJSON with Retry-After-aware retry (429, 503) + per-request timeout
+   * (mirrors the admin client). See ./retry.ts for why the delay must be able
+   * to outlast the backend's 60-second rate-limit window.
+   */
   async fetchJSON(url, init) {
     let lastError;
-    for (let attempt = 0; attempt <= 3; attempt++) {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       const controller = new AbortController();
       const timeoutId = setTimeout(() => controller.abort(), this.timeout);
       let nonRetryable = false;
@@ -777,12 +833,12 @@ var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
         if (res.ok) {
           return res.json();
         }
-        const shouldRetry = attempt < 3 && RETRY_STATUSES2.includes(res.status);
+        const shouldRetry = attempt < MAX_RETRIES && isRetryableStatus(res.status);
         if (!shouldRetry) {
           nonRetryable = true;
           throw await BetterCMSError.from(res);
         }
-        await sleep2(RETRY_DELAYS2[attempt] ?? 0);
+        await sleep(backoffMs(attempt, res));
       } catch (err) {
         clearTimeout(timeoutId);
         if (err instanceof Error && err.name === "AbortError") {
@@ -790,8 +846,8 @@ var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
         }
         if (nonRetryable) throw err;
         lastError = err;
-        if (attempt < 3) {
-          await sleep2(RETRY_DELAYS2[attempt] ?? 0);
+        if (attempt < MAX_RETRIES) {
+          await sleep(backoffMs(attempt));
           continue;
         }
         throw err;
@@ -923,9 +979,6 @@ var BetterCMSManagementClient = class extends BetterCMSDeliveryClient {
     return generateSeoMeta(this, input);
   }
 };
-function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
 
 // src/auth.ts
 var AUTH_BASE_URL = "https://api.bettercms.ai/api/v1/auth";
@@ -1016,7 +1069,8 @@ var BetterCMS = {
     return new BetterCMSDeliveryClient({
       workspace: options.workspace,
       apiKey: options.apiKey,
-      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL3
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL3,
+      timeout: options.timeout
     });
   },
   /**
@@ -1048,10 +1102,7 @@ var BetterCMS = {
 };
 
 // src/read-client.ts
-var RETRY_STATUSES3 = [429, 503];
-var RETRY_DELAYS3 = [250, 750, 1500];
 var DEFAULT_TIMEOUT3 = 1e4;
-var sleep3 = (ms) => new Promise((r) => setTimeout(r, ms));
 function qs(params2) {
   const sp = new URLSearchParams();
   for (const [k, v] of Object.entries(params2)) {
@@ -1068,6 +1119,27 @@ function unwrap(json) {
   }
   return json;
 }
+function createRequestCache() {
+  const inflight = /* @__PURE__ */ new Map();
+  const settled = /* @__PURE__ */ new Map();
+  const copy = (value) => typeof structuredClone === "function" ? structuredClone(value) : JSON.parse(JSON.stringify(value));
+  return async function collapse(url, fetcher) {
+    if (settled.has(url)) return copy(settled.get(url));
+    const pending = inflight.get(url);
+    if (pending) return copy(await pending);
+    const run = (async () => {
+      try {
+        const value = await fetcher();
+        settled.set(url, value);
+        return value;
+      } finally {
+        inflight.delete(url);
+      }
+    })();
+    inflight.set(url, run);
+    return copy(await run);
+  };
+}
 function createClient(options) {
   const apiUrl = options.apiUrl.replace(/\/+$/, "");
   const { workspace, apiKey, perspective = "published", previewToken } = options;
@@ -1079,9 +1151,11 @@ function createClient(options) {
     if (apiKey) h["X-API-Key"] = apiKey;
     return h;
   };
-  async function fetchJSON(url) {
+  const collapse = options.cache && perspective === "published" ? createRequestCache() : void 0;
+  const fetchJSON = (url) => collapse ? collapse(url, () => request(url)) : request(url);
+  async function request(url) {
     let lastError;
-    for (let attempt = 0; attempt <= RETRY_DELAYS3.length; attempt++) {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeout);
       try {
@@ -1091,9 +1165,9 @@ function createClient(options) {
         });
         clearTimeout(timer);
         if (res.ok) return await res.json();
-        const retryable = attempt < RETRY_DELAYS3.length && RETRY_STATUSES3.includes(res.status);
+        const retryable = attempt < MAX_RETRIES && isRetryableStatus(res.status);
         if (!retryable) throw await BetterCMSError.from(res);
-        await sleep3(RETRY_DELAYS3[attempt] ?? 0);
+        await sleep(backoffMs(attempt, res));
       } catch (err) {
         clearTimeout(timer);
         if (err instanceof Error && err.name === "AbortError") {
@@ -1101,8 +1175,8 @@ function createClient(options) {
         }
         if (err instanceof BetterCMSError) throw err;
         lastError = err;
-        if (attempt < RETRY_DELAYS3.length) {
-          await sleep3(RETRY_DELAYS3[attempt] ?? 0);
+        if (attempt < MAX_RETRIES) {
+          await sleep(backoffMs(attempt));
           continue;
         }
         throw new BetterCMSError(
@@ -1224,6 +1298,12 @@ function stripStega(value) {
 }
 
 // src/richtext.ts
+var PORTABLE_TEXT_FORMAT = "portable-text-1";
+function portableText(value) {
+  if (!isRichText(value)) return null;
+  const v = value;
+  return v.format === PORTABLE_TEXT_FORMAT && Array.isArray(v.value) ? v.value : null;
+}
 function isRichText(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) && ("html" in value || "format" in value);
 }
@@ -1611,6 +1691,7 @@ export {
   BetterCMSError,
   BetterCMSManagementClient,
   ErrorCodes,
+  PORTABLE_TEXT_FORMAT,
   addModelFields,
   addPageFields,
   asStringArray,
@@ -1660,6 +1741,7 @@ export {
   listSubmissions,
   listWorkspaces,
   plain,
+  portableText,
   publishPage,
   regenerateApiKey,
   removeMember,