@cmssy/react 3.0.0 → 4.0.1

package/dist/index.cjs

@@ -342,6 +342,108 @@ function parseEditorMessage(data, origin, expectedOrigin) {
   }
 }
 
+// src/data/http.ts
+var CmssyRequestError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "CmssyRequestError";
+    this.status = status;
+  }
+};
+var DEFAULT_RETRY_STATUSES = [429, 503];
+function retryAfterMs(response) {
+  const raw = response.headers?.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(raw);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return null;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("cmssy: request aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new Error("cmssy: request aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function fetchWithRetry(doFetch, url, init, retry) {
+  if (retry === false || retry === void 0) {
+    return doFetch(url, init);
+  }
+  const maxRetries = retry.maxRetries ?? 3;
+  const baseDelayMs = retry.baseDelayMs ?? 300;
+  const maxDelayMs = retry.maxDelayMs ?? 3e3;
+  const retryStatuses = retry.retryStatuses ?? DEFAULT_RETRY_STATUSES;
+  let response = await doFetch(url, init);
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    if (response.ok || !retryStatuses.includes(response.status)) {
+      return response;
+    }
+    const backoff = baseDelayMs * 2 ** attempt;
+    const wait = Math.min(retryAfterMs(response) ?? backoff, maxDelayMs);
+    await sleep(wait, init.signal);
+    response = await doFetch(url, init);
+  }
+  return response;
+}
+async function postGraphql(url, query, variables, options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new Error(
+      "cmssy: no fetch implementation available - pass options.fetch"
+    );
+  }
+  const response = await fetchWithRetry(
+    doFetch,
+    url,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json", ...options.headers },
+      body: JSON.stringify({ query, variables }),
+      signal: options.signal
+    },
+    options.retry
+  );
+  if (!response.ok) {
+    let detail = "";
+    try {
+      const body = await response.json();
+      if (body.errors && body.errors.length > 0) {
+        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
+      }
+    } catch {
+      detail = "";
+    }
+    throw new CmssyRequestError(
+      `cmssy: ${options.label} failed (${response.status})${detail}`,
+      response.status
+    );
+  }
+  let json;
+  try {
+    json = await response.json();
+  } catch {
+    throw new Error(`cmssy: invalid JSON response from the ${options.label}`);
+  }
+  if (json.errors && json.errors.length > 0) {
+    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
+    throw new Error(`cmssy: ${options.label} error - ${message}`);
+  }
+  return json.data;
+}
+
 // src/content/content-client.ts
 var DEFAULT_CMSSY_API_URL = "https://api.cmssy.io/graphql";
 function resolveApiUrl(apiUrl) {
@@ -433,251 +535,113 @@ function normalizeSlug(path) {
 }
 async function fetchPage(config, path, options = {}) {
   const slug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const trimmedSecret = options.previewSecret?.trim();
   const previewSecret = trimmedSecret ? trimmedSecret : null;
   const devToken = options.devToken?.trim();
   const devPreview = Boolean(options.devPreview && devToken);
-  const headers = {
-    "content-type": "application/json"
-  };
+  const headers = {};
   if (devPreview && devToken) {
     headers["authorization"] = `Bearer ${devToken}`;
     if (options.workspaceId) {
       headers["x-workspace-id"] = options.workspaceId;
     }
   }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers,
-    body: JSON.stringify({
-      query: devPreview ? PUBLIC_PAGE_DEV_QUERY : PUBLIC_PAGE_QUERY,
-      variables: {
-        workspaceSlug: config.workspaceSlug,
-        slug,
-        previewSecret,
-        ...devPreview ? { devPreview: true } : {}
-      }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    devPreview ? PUBLIC_PAGE_DEV_QUERY : PUBLIC_PAGE_QUERY,
+    {
+      workspaceSlug: config.workspaceSlug,
+      slug,
+      previewSecret,
+      ...devPreview ? { devPreview: true } : {}
+    },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      headers,
+      retry: options.retry ?? {},
+      label: "page fetch"
     }
-    throw new Error(`cmssy: page fetch failed (${response.status})${detail}`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page fetch error - ${message}`);
-  }
-  const page = json.data?.public?.page?.get;
+  );
+  const page = data?.public?.page?.get;
   if (!page) return null;
   const draft = previewSecret !== null || devPreview;
   const blocks = (draft ? page.blocks : page.publishedBlocks) ?? [];
   return { id: page.id, blocks };
 }
 async function fetchPageById(config, pageId, options = {}) {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_BY_ID_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug, pageId }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_BY_ID_QUERY,
+    { workspaceSlug: config.workspaceSlug, pageId },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "page-by-id fetch"
     }
-    throw new Error(
-      `cmssy: page-by-id fetch failed (${response.status})${detail}`
-    );
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page-by-id query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page-by-id fetch error - ${message}`);
-  }
-  const page = json.data?.public?.page?.getById;
+  );
+  const page = data?.public?.page?.getById;
   if (!page) return null;
   return { id: page.id, blocks: page.publishedBlocks ?? [] };
 }
 async function fetchPages(config, options = {}) {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGES_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: pages fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the pages query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: pages fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.list ?? [];
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGES_QUERY,
+    { workspaceSlug: config.workspaceSlug },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "pages fetch"
+    }
+  );
+  return data?.public?.page?.list ?? [];
 }
 async function fetchPageMeta(config, path, options = {}) {
   const slug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_META_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug, slug }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: page meta fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page meta query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page meta fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.get ?? null;
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_META_QUERY,
+    { workspaceSlug: config.workspaceSlug, slug },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "page meta fetch"
+    }
+  );
+  return data?.public?.page?.get ?? null;
 }
 async function fetchLayouts(config, path, options = {}) {
   const pageSlug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const trimmedSecret = options.previewSecret?.trim();
   const previewSecret = trimmedSecret ? trimmedSecret : null;
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_LAYOUTS_QUERY,
-      variables: {
-        workspaceSlug: config.workspaceSlug,
-        pageSlug,
-        previewSecret
-      }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: layouts fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the layouts query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: layouts fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.layouts ?? [];
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_LAYOUTS_QUERY,
+    { workspaceSlug: config.workspaceSlug, pageSlug, previewSecret },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "layouts fetch"
+    }
+  );
+  return data?.public?.page?.layouts ?? [];
 }
 
 // src/data/graphql-request.ts
 async function graphqlRequest(config, query, variables, options = {}, label = "request") {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const url = options.public ? resolvePublicUrl(config) : resolveApiUrl(config.apiUrl);
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: { "content-type": "application/json", ...options.headers },
-    body: JSON.stringify({ query, variables }),
-    signal: options.signal
+  return postGraphql(url, query, variables, {
+    fetch: options.fetch,
+    signal: options.signal,
+    headers: options.headers,
+    retry: options.retry,
+    label
   });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
-    }
-    throw new Error(`cmssy: ${label} failed (${response.status})${detail}`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error(`cmssy: invalid JSON response from the ${label}`);
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: ${label} error - ${message}`);
-  }
-  return json.data;
 }
 
 // src/data/queries.ts
@@ -759,7 +723,7 @@ async function fetchSiteConfig(config, options = {}) {
     config,
     SITE_CONFIG_QUERY,
     { workspaceSlug: config.workspaceSlug },
-    { ...options, public: true },
+    { ...options, public: true, retry: options.retry ?? {} },
     "site config query"
   );
   return data.public?.siteConfig ?? null;
@@ -875,7 +839,7 @@ async function resolveSiteLocales(config, options) {
       config,
       SITE_CONFIG_QUERY,
       { workspaceSlug: config.workspaceSlug },
-      { ...options, public: true },
+      { ...options, public: true, retry: options?.retry ?? {} },
       "site config"
     );
     const siteConfig = data.public?.siteConfig ?? null;
@@ -985,6 +949,7 @@ Object.defineProperty(exports, "evaluateFieldConditionGroup", {
   get: function () { return types.evaluateFieldConditionGroup; }
 });
 exports.CmssyBlock = CmssyBlock;
+exports.CmssyRequestError = CmssyRequestError;
 exports.CmssyServerLayout = CmssyServerLayout;
 exports.CmssyServerPage = CmssyServerPage;
 exports.DEFAULT_CMSSY_API_URL = DEFAULT_CMSSY_API_URL;

package/dist/index.d.cts

@@ -5,6 +5,22 @@ export { b as blocksToMeta, c as blocksToSchemas, d as buildBlockMap, e as defin
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'react';
 
+/** HTTP-level failure from the cmssy API, with a machine-readable status. */
+declare class CmssyRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface RetryPolicy {
+    /** Additional attempts after the first request (default 3). */
+    maxRetries?: number;
+    /** Exponential backoff base in ms: base * 2^attempt (default 300). */
+    baseDelayMs?: number;
+    /** Upper bound for any single wait, including Retry-After (default 3000). */
+    maxDelayMs?: number;
+    /** HTTP statuses that trigger a retry (default [429, 503]). */
+    retryStatuses?: number[];
+}
+
 /**
  * The cmssy cloud GraphQL delivery endpoint. It is the same for every workspace,
  * so consumers never need to set it - `apiUrl` defaults to this. Self-hosted /
@@ -23,6 +39,9 @@ interface FetchLikeResponse {
     ok: boolean;
     status: number;
     json: () => Promise<unknown>;
+    headers?: {
+        get: (name: string) => string | null;
+    };
 }
 type FetchLike = (url: string, init: {
     method: string;
@@ -37,12 +56,13 @@ interface FetchPageOptions {
     workspaceId?: string;
     fetch?: FetchLike;
     signal?: AbortSignal;
+    retry?: RetryPolicy | false;
 }
 declare function normalizeSlug(path: string | string[] | undefined): string;
 declare function fetchPage(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyPageData | null>;
-declare function fetchPageById(config: CmssyClientConfig, pageId: string, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageData | null>;
-declare function fetchPages(config: CmssyClientConfig, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageSummary[]>;
-declare function fetchPageMeta(config: CmssyClientConfig, path: string | string[] | undefined, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageMeta | null>;
+declare function fetchPageById(config: CmssyClientConfig, pageId: string, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageData | null>;
+declare function fetchPages(config: CmssyClientConfig, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageSummary[]>;
+declare function fetchPageMeta(config: CmssyClientConfig, path: string | string[] | undefined, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageMeta | null>;
 declare function fetchLayouts(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyLayoutGroup[]>;
 
 declare const SITE_CONFIG_QUERY = "query PublicSiteConfig($workspaceSlug: String!) {\n  public {\n    siteConfig(workspaceSlug: $workspaceSlug) {\n      id\n      workspaceId\n      siteName\n      defaultLanguage\n      enabledLanguages\n      enabledFeatures\n      notFoundPageId\n      previewUrl\n      branding {\n        brandName\n        logoUrl\n        faviconUrl\n        ogImageUrl\n      }\n    }\n  }\n}";
@@ -220,6 +240,12 @@ interface GraphqlRequestOptions {
      * resolves the workspace from the URL rather than a global slug lookup.
      */
     public?: boolean;
+    /**
+     * Retry transient HTTP failures (429/503, honoring Retry-After). Off by
+     * default: this function also carries mutations (auth, cart, checkout),
+     * which must never be blind-retried. Read-only callers opt in with `{}`.
+     */
+    retry?: RetryPolicy | false;
 }
 declare function graphqlRequest<T>(config: CmssyClientConfig, query: string, variables: Record<string, unknown>, options?: GraphqlRequestOptions, label?: string): Promise<T>;
 
@@ -282,4 +308,4 @@ interface UnknownBlockProps {
 }
 declare function UnknownBlock({ type }: UnknownBlockProps): react_jsx_runtime.JSX.Element;
 
-export { type AppToEditorMessage, BlockDefinition, BlockMap, type BoundsMessage, type ClickMessage, CmssyBlock, type CmssyBlockProps, type CmssyClient, CmssyServerLayout, type CmssyServerLayoutProps, CmssyServerPage, type CmssyServerPageProps, DEFAULT_CMSSY_API_URL, type EditorToAppMessage, FORM_QUERY, type FetchLike, type FetchLikeResponse, type FetchPageOptions, type GraphqlRequestOptions, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, UnknownBlock, type UnknownBlockProps, buildBlockContext, buildLocaleSwitchHref, collectFormIds, createCmssyClient, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };
+export { type AppToEditorMessage, BlockDefinition, BlockMap, type BoundsMessage, type ClickMessage, CmssyBlock, type CmssyBlockProps, type CmssyClient, CmssyRequestError, CmssyServerLayout, type CmssyServerLayoutProps, CmssyServerPage, type CmssyServerPageProps, DEFAULT_CMSSY_API_URL, type EditorToAppMessage, FORM_QUERY, type FetchLike, type FetchLikeResponse, type FetchPageOptions, type GraphqlRequestOptions, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, type RetryPolicy, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, UnknownBlock, type UnknownBlockProps, buildBlockContext, buildLocaleSwitchHref, collectFormIds, createCmssyClient, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };

package/dist/index.d.ts

@@ -5,6 +5,22 @@ export { b as blocksToMeta, c as blocksToSchemas, d as buildBlockMap, e as defin
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import 'react';
 
+/** HTTP-level failure from the cmssy API, with a machine-readable status. */
+declare class CmssyRequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface RetryPolicy {
+    /** Additional attempts after the first request (default 3). */
+    maxRetries?: number;
+    /** Exponential backoff base in ms: base * 2^attempt (default 300). */
+    baseDelayMs?: number;
+    /** Upper bound for any single wait, including Retry-After (default 3000). */
+    maxDelayMs?: number;
+    /** HTTP statuses that trigger a retry (default [429, 503]). */
+    retryStatuses?: number[];
+}
+
 /**
  * The cmssy cloud GraphQL delivery endpoint. It is the same for every workspace,
  * so consumers never need to set it - `apiUrl` defaults to this. Self-hosted /
@@ -23,6 +39,9 @@ interface FetchLikeResponse {
     ok: boolean;
     status: number;
     json: () => Promise<unknown>;
+    headers?: {
+        get: (name: string) => string | null;
+    };
 }
 type FetchLike = (url: string, init: {
     method: string;
@@ -37,12 +56,13 @@ interface FetchPageOptions {
     workspaceId?: string;
     fetch?: FetchLike;
     signal?: AbortSignal;
+    retry?: RetryPolicy | false;
 }
 declare function normalizeSlug(path: string | string[] | undefined): string;
 declare function fetchPage(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyPageData | null>;
-declare function fetchPageById(config: CmssyClientConfig, pageId: string, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageData | null>;
-declare function fetchPages(config: CmssyClientConfig, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageSummary[]>;
-declare function fetchPageMeta(config: CmssyClientConfig, path: string | string[] | undefined, options?: Pick<FetchPageOptions, "fetch" | "signal">): Promise<CmssyPageMeta | null>;
+declare function fetchPageById(config: CmssyClientConfig, pageId: string, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageData | null>;
+declare function fetchPages(config: CmssyClientConfig, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageSummary[]>;
+declare function fetchPageMeta(config: CmssyClientConfig, path: string | string[] | undefined, options?: Pick<FetchPageOptions, "fetch" | "signal" | "retry">): Promise<CmssyPageMeta | null>;
 declare function fetchLayouts(config: CmssyClientConfig, path: string | string[] | undefined, options?: FetchPageOptions): Promise<CmssyLayoutGroup[]>;
 
 declare const SITE_CONFIG_QUERY = "query PublicSiteConfig($workspaceSlug: String!) {\n  public {\n    siteConfig(workspaceSlug: $workspaceSlug) {\n      id\n      workspaceId\n      siteName\n      defaultLanguage\n      enabledLanguages\n      enabledFeatures\n      notFoundPageId\n      previewUrl\n      branding {\n        brandName\n        logoUrl\n        faviconUrl\n        ogImageUrl\n      }\n    }\n  }\n}";
@@ -220,6 +240,12 @@ interface GraphqlRequestOptions {
      * resolves the workspace from the URL rather than a global slug lookup.
      */
     public?: boolean;
+    /**
+     * Retry transient HTTP failures (429/503, honoring Retry-After). Off by
+     * default: this function also carries mutations (auth, cart, checkout),
+     * which must never be blind-retried. Read-only callers opt in with `{}`.
+     */
+    retry?: RetryPolicy | false;
 }
 declare function graphqlRequest<T>(config: CmssyClientConfig, query: string, variables: Record<string, unknown>, options?: GraphqlRequestOptions, label?: string): Promise<T>;
 
@@ -282,4 +308,4 @@ interface UnknownBlockProps {
 }
 declare function UnknownBlock({ type }: UnknownBlockProps): react_jsx_runtime.JSX.Element;
 
-export { type AppToEditorMessage, BlockDefinition, BlockMap, type BoundsMessage, type ClickMessage, CmssyBlock, type CmssyBlockProps, type CmssyClient, CmssyServerLayout, type CmssyServerLayoutProps, CmssyServerPage, type CmssyServerPageProps, DEFAULT_CMSSY_API_URL, type EditorToAppMessage, FORM_QUERY, type FetchLike, type FetchLikeResponse, type FetchPageOptions, type GraphqlRequestOptions, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, UnknownBlock, type UnknownBlockProps, buildBlockContext, buildLocaleSwitchHref, collectFormIds, createCmssyClient, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };
+export { type AppToEditorMessage, BlockDefinition, BlockMap, type BoundsMessage, type ClickMessage, CmssyBlock, type CmssyBlockProps, type CmssyClient, CmssyRequestError, CmssyServerLayout, type CmssyServerLayoutProps, CmssyServerPage, type CmssyServerPageProps, DEFAULT_CMSSY_API_URL, type EditorToAppMessage, FORM_QUERY, type FetchLike, type FetchLikeResponse, type FetchPageOptions, type GraphqlRequestOptions, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, type RetryPolicy, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, UnknownBlock, type UnknownBlockProps, buildBlockContext, buildLocaleSwitchHref, collectFormIds, createCmssyClient, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };

package/dist/index.js

@@ -340,6 +340,108 @@ function parseEditorMessage(data, origin, expectedOrigin) {
   }
 }
 
+// src/data/http.ts
+var CmssyRequestError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "CmssyRequestError";
+    this.status = status;
+  }
+};
+var DEFAULT_RETRY_STATUSES = [429, 503];
+function retryAfterMs(response) {
+  const raw = response.headers?.get("retry-after");
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+  const date = Date.parse(raw);
+  if (Number.isFinite(date)) return Math.max(0, date - Date.now());
+  return null;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("cmssy: request aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new Error("cmssy: request aborted"));
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function fetchWithRetry(doFetch, url, init, retry) {
+  if (retry === false || retry === void 0) {
+    return doFetch(url, init);
+  }
+  const maxRetries = retry.maxRetries ?? 3;
+  const baseDelayMs = retry.baseDelayMs ?? 300;
+  const maxDelayMs = retry.maxDelayMs ?? 3e3;
+  const retryStatuses = retry.retryStatuses ?? DEFAULT_RETRY_STATUSES;
+  let response = await doFetch(url, init);
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    if (response.ok || !retryStatuses.includes(response.status)) {
+      return response;
+    }
+    const backoff = baseDelayMs * 2 ** attempt;
+    const wait = Math.min(retryAfterMs(response) ?? backoff, maxDelayMs);
+    await sleep(wait, init.signal);
+    response = await doFetch(url, init);
+  }
+  return response;
+}
+async function postGraphql(url, query, variables, options) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new Error(
+      "cmssy: no fetch implementation available - pass options.fetch"
+    );
+  }
+  const response = await fetchWithRetry(
+    doFetch,
+    url,
+    {
+      method: "POST",
+      headers: { "content-type": "application/json", ...options.headers },
+      body: JSON.stringify({ query, variables }),
+      signal: options.signal
+    },
+    options.retry
+  );
+  if (!response.ok) {
+    let detail = "";
+    try {
+      const body = await response.json();
+      if (body.errors && body.errors.length > 0) {
+        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
+      }
+    } catch {
+      detail = "";
+    }
+    throw new CmssyRequestError(
+      `cmssy: ${options.label} failed (${response.status})${detail}`,
+      response.status
+    );
+  }
+  let json;
+  try {
+    json = await response.json();
+  } catch {
+    throw new Error(`cmssy: invalid JSON response from the ${options.label}`);
+  }
+  if (json.errors && json.errors.length > 0) {
+    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
+    throw new Error(`cmssy: ${options.label} error - ${message}`);
+  }
+  return json.data;
+}
+
 // src/content/content-client.ts
 var DEFAULT_CMSSY_API_URL = "https://api.cmssy.io/graphql";
 function resolveApiUrl(apiUrl) {
@@ -431,251 +533,113 @@ function normalizeSlug(path) {
 }
 async function fetchPage(config, path, options = {}) {
   const slug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const trimmedSecret = options.previewSecret?.trim();
   const previewSecret = trimmedSecret ? trimmedSecret : null;
   const devToken = options.devToken?.trim();
   const devPreview = Boolean(options.devPreview && devToken);
-  const headers = {
-    "content-type": "application/json"
-  };
+  const headers = {};
   if (devPreview && devToken) {
     headers["authorization"] = `Bearer ${devToken}`;
     if (options.workspaceId) {
       headers["x-workspace-id"] = options.workspaceId;
     }
   }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers,
-    body: JSON.stringify({
-      query: devPreview ? PUBLIC_PAGE_DEV_QUERY : PUBLIC_PAGE_QUERY,
-      variables: {
-        workspaceSlug: config.workspaceSlug,
-        slug,
-        previewSecret,
-        ...devPreview ? { devPreview: true } : {}
-      }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    devPreview ? PUBLIC_PAGE_DEV_QUERY : PUBLIC_PAGE_QUERY,
+    {
+      workspaceSlug: config.workspaceSlug,
+      slug,
+      previewSecret,
+      ...devPreview ? { devPreview: true } : {}
+    },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      headers,
+      retry: options.retry ?? {},
+      label: "page fetch"
     }
-    throw new Error(`cmssy: page fetch failed (${response.status})${detail}`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page fetch error - ${message}`);
-  }
-  const page = json.data?.public?.page?.get;
+  );
+  const page = data?.public?.page?.get;
   if (!page) return null;
   const draft = previewSecret !== null || devPreview;
   const blocks = (draft ? page.blocks : page.publishedBlocks) ?? [];
   return { id: page.id, blocks };
 }
 async function fetchPageById(config, pageId, options = {}) {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_BY_ID_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug, pageId }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_BY_ID_QUERY,
+    { workspaceSlug: config.workspaceSlug, pageId },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "page-by-id fetch"
     }
-    throw new Error(
-      `cmssy: page-by-id fetch failed (${response.status})${detail}`
-    );
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page-by-id query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page-by-id fetch error - ${message}`);
-  }
-  const page = json.data?.public?.page?.getById;
+  );
+  const page = data?.public?.page?.getById;
   if (!page) return null;
   return { id: page.id, blocks: page.publishedBlocks ?? [] };
 }
 async function fetchPages(config, options = {}) {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGES_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: pages fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the pages query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: pages fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.list ?? [];
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGES_QUERY,
+    { workspaceSlug: config.workspaceSlug },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "pages fetch"
+    }
+  );
+  return data?.public?.page?.list ?? [];
 }
 async function fetchPageMeta(config, path, options = {}) {
   const slug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_META_QUERY,
-      variables: { workspaceSlug: config.workspaceSlug, slug }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: page meta fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the page meta query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: page meta fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.get ?? null;
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_META_QUERY,
+    { workspaceSlug: config.workspaceSlug, slug },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "page meta fetch"
+    }
+  );
+  return data?.public?.page?.get ?? null;
 }
 async function fetchLayouts(config, path, options = {}) {
   const pageSlug = normalizeSlug(path);
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const trimmedSecret = options.previewSecret?.trim();
   const previewSecret = trimmedSecret ? trimmedSecret : null;
-  const response = await doFetch(resolvePublicUrl(config), {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      query: PUBLIC_PAGE_LAYOUTS_QUERY,
-      variables: {
-        workspaceSlug: config.workspaceSlug,
-        pageSlug,
-        previewSecret
-      }
-    }),
-    signal: options.signal
-  });
-  if (!response.ok) {
-    throw new Error(`cmssy: layouts fetch failed (${response.status})`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error("cmssy: invalid JSON response from the layouts query");
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: layouts fetch error - ${message}`);
-  }
-  return json.data?.public?.page?.layouts ?? [];
+  const data = await postGraphql(
+    resolvePublicUrl(config),
+    PUBLIC_PAGE_LAYOUTS_QUERY,
+    { workspaceSlug: config.workspaceSlug, pageSlug, previewSecret },
+    {
+      fetch: options.fetch,
+      signal: options.signal,
+      retry: options.retry ?? {},
+      label: "layouts fetch"
+    }
+  );
+  return data?.public?.page?.layouts ?? [];
 }
 
 // src/data/graphql-request.ts
 async function graphqlRequest(config, query, variables, options = {}, label = "request") {
-  const doFetch = options.fetch ?? globalThis.fetch;
-  if (typeof doFetch !== "function") {
-    throw new Error(
-      "cmssy: no fetch implementation available - pass options.fetch"
-    );
-  }
   const url = options.public ? resolvePublicUrl(config) : resolveApiUrl(config.apiUrl);
-  const response = await doFetch(url, {
-    method: "POST",
-    headers: { "content-type": "application/json", ...options.headers },
-    body: JSON.stringify({ query, variables }),
-    signal: options.signal
+  return postGraphql(url, query, variables, {
+    fetch: options.fetch,
+    signal: options.signal,
+    headers: options.headers,
+    retry: options.retry,
+    label
   });
-  if (!response.ok) {
-    let detail = "";
-    try {
-      const body = await response.json();
-      if (body.errors && body.errors.length > 0) {
-        detail = ` - ${body.errors.map((error) => error.message ?? "GraphQL error").join("; ")}`;
-      }
-    } catch {
-      detail = "";
-    }
-    throw new Error(`cmssy: ${label} failed (${response.status})${detail}`);
-  }
-  let json;
-  try {
-    json = await response.json();
-  } catch {
-    throw new Error(`cmssy: invalid JSON response from the ${label}`);
-  }
-  if (json.errors && json.errors.length > 0) {
-    const message = json.errors.map((error) => error.message ?? "GraphQL error").join("; ");
-    throw new Error(`cmssy: ${label} error - ${message}`);
-  }
-  return json.data;
 }
 
 // src/data/queries.ts
@@ -757,7 +721,7 @@ async function fetchSiteConfig(config, options = {}) {
     config,
     SITE_CONFIG_QUERY,
     { workspaceSlug: config.workspaceSlug },
-    { ...options, public: true },
+    { ...options, public: true, retry: options.retry ?? {} },
     "site config query"
   );
   return data.public?.siteConfig ?? null;
@@ -873,7 +837,7 @@ async function resolveSiteLocales(config, options) {
       config,
       SITE_CONFIG_QUERY,
       { workspaceSlug: config.workspaceSlug },
-      { ...options, public: true },
+      { ...options, public: true, retry: options?.retry ?? {} },
       "site config"
     );
     const siteConfig = data.public?.siteConfig ?? null;
@@ -978,4 +942,4 @@ function CmssyBlock({
   );
 }
 
-export { CmssyBlock, CmssyServerLayout, CmssyServerPage, DEFAULT_CMSSY_API_URL, FORM_QUERY, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, UnknownBlock, blocksToMeta, blocksToSchemas, buildBlockContext, buildBlockMap, buildLocaleSwitchHref, collectFormIds, createCmssyClient, defineBlock, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };
+export { CmssyBlock, CmssyRequestError, CmssyServerLayout, CmssyServerPage, DEFAULT_CMSSY_API_URL, FORM_QUERY, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PROTOCOL_VERSION, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, UnknownBlock, blocksToMeta, blocksToSchemas, buildBlockContext, buildBlockMap, buildLocaleSwitchHref, collectFormIds, createCmssyClient, defineBlock, fetchLayouts, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchSiteConfig, fields, getBlockContentForLanguage, graphqlRequest, isProtocolCompatible, localizeHref, localizeHtmlLinks, normalizeOrigin, normalizeSlug, parseEditorMessage, postToEditor, resolveApiUrl, resolveForms, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, splitLocaleFromPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/react",
-  "version": "3.0.0",
+  "version": "4.0.1",
   "description": "React blocks, renderers, data client and editor bridge for cmssy headless sites",
   "keywords": [
     "cmssy",