@bettercms-ai/sdk 1.13.1 → 1.14.0

package/dist/index.cjs

@@ -38,6 +38,7 @@ __export(index_exports, {
   BetterCMSError: () => BetterCMSError,
   BetterCMSManagementClient: () => BetterCMSManagementClient,
   ErrorCodes: () => ErrorCodes,
+  PORTABLE_TEXT_FORMAT: () => PORTABLE_TEXT_FORMAT,
   addModelFields: () => addModelFields,
   addPageFields: () => addPageFields,
   asStringArray: () => asStringArray,
@@ -87,6 +88,7 @@ __export(index_exports, {
   listSubmissions: () => listSubmissions,
   listWorkspaces: () => listWorkspaces,
   plain: () => plain,
+  portableText: () => portableText,
   publishPage: () => publishPage,
   regenerateApiKey: () => regenerateApiKey,
   removeMember: () => removeMember,
@@ -205,6 +207,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));
@@ -269,14 +300,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);
@@ -309,24 +343,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();
   }
 };
 
@@ -407,19 +463,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 {
@@ -429,12 +481,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;
@@ -448,12 +500,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") {
@@ -463,8 +515,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;
@@ -481,9 +533,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) {
@@ -624,7 +673,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;
@@ -853,8 +909,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;
@@ -876,10 +930,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;
@@ -893,12 +951,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") {
@@ -906,8 +964,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;
@@ -1039,9 +1097,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";
@@ -1132,7 +1187,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
     });
   },
   /**
@@ -1164,10 +1220,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)) {
@@ -1184,6 +1237,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;
@@ -1195,9 +1269,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 {
@@ -1207,9 +1283,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") {
@@ -1217,8 +1293,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(
@@ -1340,6 +1416,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);
 }
@@ -1728,6 +1810,7 @@ var import_types = require("@bettercms-ai/types");
   BetterCMSError,
   BetterCMSManagementClient,
   ErrorCodes,
+  PORTABLE_TEXT_FORMAT,
   addModelFields,
   addPageFields,
   asStringArray,
@@ -1777,6 +1860,7 @@ var import_types = require("@bettercms-ai/types");
   listSubmissions,
   listWorkspaces,
   plain,
+  portableText,
   publishPage,
   regenerateApiKey,
   removeMember,