@bettercms-ai/sdk 1.13.2 → 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. */

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. */

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) {
@@ -744,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;
@@ -767,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;
@@ -784,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") {
@@ -797,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;
@@ -930,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";
@@ -1023,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
     });
   },
   /**
@@ -1055,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)) {
@@ -1075,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;
@@ -1086,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 {
@@ -1098,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") {
@@ -1108,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(