@drakkar.software/starfish-client 3.0.0-alpha.23 → 3.0.0-alpha.26

package/dist/client.d.ts

@@ -92,6 +92,9 @@ export declare class StarfishClient {
     private readonly fetch;
     private readonly cache?;
     private readonly cacheMaxAgeMs?;
+    private readonly cacheFallbackStatuses?;
+    private readonly onRevalidated?;
+    private readonly revalidating;
     /**
      * Installed client-side plugins. Currently stored as inert data; no
      * hooks fire yet. Extensions can inspect this list if needed.
@@ -164,6 +167,16 @@ export declare class StarfishClient {
     pull(path: string, options: PullOptions): Promise<PullResult>;
     /** Pull an append-only collection. Extracts and returns `data[appendField]` as `T[]`. */
     pull<T = unknown>(path: string, options: AppendPullOptions): Promise<T[]>;
+    /** Deduplicated fire-and-forget: starts one revalidation loop per cacheKey. */
+    private scheduleRevalidate;
+    /**
+     * Background revalidation loop for a {@link cacheFallbackStatuses} hit.
+     * Retries the pull (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS}
+     * times. On a live 2xx response the fresh snapshot is written through to the
+     * cache and {@link onRevalidated} fires. Stops early on a non-fallback HTTP
+     * status (e.g. 404/403 — the server gave a genuine answer).
+     */
+    private revalidateLoop;
     /**
      * Read the cached snapshot for a document `path` WITHOUT hitting the network —
      * the basis for cache-first paint (seed the UI from the last-synced snapshot,

package/dist/fetch.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Parse a `Retry-After` header value into milliseconds.
+ *
+ * - Numeric string (`"30"`) — treated as seconds × 1000.
+ * - HTTP-date string — delta from now in ms (floored to 0).
+ * - `null`, empty, or unparseable — returns `opts.fallbackMs`.
+ *
+ * All results are clamped to `[0, opts.maxMs]`.
+ */
+export declare function parseRetryAfterMs(header: string | null | undefined, opts: {
+    fallbackMs: number;
+    maxMs: number;
+}): number;
 /** Error category returned by classifyError. */
 export type ErrorCategory = "network" | "auth" | "conflict" | "rate-limited" | "server" | "client" | "unknown";
 /** Classify an error from a fetch response or network failure. */

package/dist/fetch.js

@@ -1,4 +1,15 @@
 // src/fetch.ts
+function parseRetryAfterMs(header, opts) {
+  const { fallbackMs, maxMs } = opts;
+  const trimmed = header?.trim();
+  if (trimmed) {
+    const seconds = Number(trimmed);
+    if (!isNaN(seconds)) return Math.min(seconds * 1e3, maxMs);
+    const date = Date.parse(trimmed);
+    if (!isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), maxMs);
+  }
+  return Math.min(fallbackMs, maxMs);
+}
 function classifyError(err) {
   if (err instanceof Response || err && typeof err === "object" && "status" in err) {
     const status = err.status;
@@ -25,19 +36,12 @@ function createRetryFetch(options) {
         if (res.ok || attempt >= maxRetries) return res;
         const category = classifyError(res);
         if (category !== "rate-limited" && category !== "server") return res;
-        const retryAfter = res.headers.get("Retry-After")?.trim();
-        let delay;
-        if (retryAfter) {
-          const seconds = Number(retryAfter);
-          if (retryAfter !== "" && !isNaN(seconds)) {
-            delay = Math.min(seconds * 1e3, maxDelay);
-          } else {
-            const date = Date.parse(retryAfter);
-            delay = isNaN(date) ? initialDelay : Math.min(Math.max(date - Date.now(), 0), maxDelay);
-          }
-        } else {
-          delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
-        }
+        const retryAfterHeader = res.headers.get("Retry-After");
+        const exponentialDelay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay);
+        const delay = parseRetryAfterMs(retryAfterHeader, {
+          fallbackMs: retryAfterHeader?.trim() ? initialDelay : exponentialDelay,
+          maxMs: maxDelay
+        });
         await new Promise((r) => setTimeout(r, delay));
         attempt++;
       } catch (err) {
@@ -136,6 +140,7 @@ export {
   classifyError,
   createCompressedFetch,
   createResilientFetch,
-  createRetryFetch
+  createRetryFetch,
+  parseRetryAfterMs
 };
 //# sourceMappingURL=fetch.js.map

package/dist/fetch.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/fetch.ts"],
-  "sourcesContent": ["/** Error category returned by classifyError. */\nexport type ErrorCategory =\n  | \"network\"\n  | \"auth\"\n  | \"conflict\"\n  | \"rate-limited\"\n  | \"server\"\n  | \"client\"\n  | \"unknown\"\n\n/** Classify an error from a fetch response or network failure. */\nexport function classifyError(err: unknown): ErrorCategory {\n  if (err instanceof Response || (err && typeof err === \"object\" && \"status\" in err)) {\n    const status = (err as { status: unknown }).status\n    if (typeof status !== \"number\" || isNaN(status)) return \"unknown\"\n    if (status === 0) return \"network\"\n    if (status === 401 || status === 403) return \"auth\"\n    if (status === 409) return \"conflict\"\n    if (status === 429) return \"rate-limited\"\n    if (status >= 500) return \"server\"\n    if (status >= 400) return \"client\"\n  }\n  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return \"network\"\n  return \"unknown\"\n}\n\nexport interface RetryOptions {\n  /** Max number of retries (default: 3). */\n  maxRetries?: number\n  /** Initial delay in ms before first retry (default: 500). */\n  initialDelayMs?: number\n  /** Maximum delay in ms (default: 10000). */\n  maxDelayMs?: number\n}\n\n/**\n * Wraps a fetch function with automatic retry for retriable errors\n * (network failures, 429, 5xx). Respects Retry-After headers.\n */\nexport function createRetryFetch(options?: RetryOptions): typeof globalThis.fetch {\n  const maxRetries = Math.max(0, options?.maxRetries ?? 3)\n  const initialDelay = options?.initialDelayMs ?? 500\n  const maxDelay = options?.maxDelayMs ?? 10_000\n\n  return async (input, init?) => {\n    let attempt = 0\n    while (true) {\n      try {\n        const res = await globalThis.fetch(input, init)\n        if (res.ok || attempt >= maxRetries) return res\n\n        const category = classifyError(res)\n        if (category !== \"rate-limited\" && category !== \"server\") return res\n\n        const retryAfter = res.headers.get(\"Retry-After\")?.trim()\n        let delay: number\n        if (retryAfter) {\n          const seconds = Number(retryAfter)\n          if (retryAfter !== \"\" && !isNaN(seconds)) {\n            delay = Math.min(seconds * 1000, maxDelay)\n          } else {\n            const date = Date.parse(retryAfter)\n            delay = isNaN(date) ? initialDelay : Math.min(Math.max(date - Date.now(), 0), maxDelay)\n          }\n        } else {\n          delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay)\n        }\n\n        await new Promise<void>((r) => setTimeout(r, delay))\n        attempt++\n      } catch (err) {\n        if (attempt >= maxRetries) throw err\n        const category = classifyError(err)\n        if (category !== \"network\") throw err\n\n        const delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay)\n        await new Promise<void>((r) => setTimeout(r, delay))\n        attempt++\n      }\n    }\n  }\n}\n\ntype BreakerState = \"closed\" | \"open\" | \"half-open\"\n\nexport interface CircuitBreakerOptions {\n  /** Number of consecutive failures to open the circuit (default: 5). */\n  threshold?: number\n  /** Cooldown in ms before transitioning from open to half-open (default: 30000). */\n  cooldownMs?: number\n}\n\n/** Circuit breaker that prevents requests when the backend is unavailable. */\nexport class CircuitBreaker {\n  private state: BreakerState = \"closed\"\n  private failures = 0\n  private openedAt = 0\n  private readonly threshold: number\n  private readonly cooldownMs: number\n\n  constructor(options?: CircuitBreakerOptions) {\n    this.threshold = options?.threshold ?? 5\n    this.cooldownMs = options?.cooldownMs ?? 30_000\n  }\n\n  getState(): BreakerState {\n    this.maybeTransition()\n    return this.state\n  }\n\n  isOpen(): boolean {\n    return this.getState() === \"open\"\n  }\n\n  recordSuccess(): void {\n    this.failures = 0\n    this.state = \"closed\"\n  }\n\n  recordFailure(): void {\n    this.failures++\n    if (this.state === \"half-open\" || this.failures >= this.threshold) {\n      this.state = \"open\"\n      this.openedAt = Date.now()\n    }\n  }\n\n  private maybeTransition(): void {\n    if (this.state === \"open\" && Date.now() - this.openedAt >= this.cooldownMs) {\n      this.state = \"half-open\"\n    }\n  }\n}\n\n/**\n * Wraps fetch to gzip-compress string request bodies using the CompressionStream API.\n * Adds Content-Encoding: gzip header. Non-string bodies (ArrayBuffer, Blob, etc.)\n * are passed through uncompressed. Requires CompressionStream (browsers, Node.js 18+, Deno).\n */\nexport function createCompressedFetch(inner?: typeof globalThis.fetch): typeof globalThis.fetch {\n  const baseFetch = inner ?? globalThis.fetch.bind(globalThis)\n  return async (input, init?) => {\n    if (!init?.body || typeof CompressionStream === \"undefined\") {\n      return baseFetch(input, init)\n    }\n\n    const bodyText = typeof init.body === \"string\" ? init.body : null\n    if (!bodyText) return baseFetch(input, init)\n\n    try {\n      const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream(\"gzip\"))\n      const compressed = await new Response(stream).arrayBuffer()\n\n      const normalized = Object.fromEntries(new Headers(init.headers as HeadersInit).entries())\n      normalized[\"content-encoding\"] = \"gzip\"\n\n      return baseFetch(input, {\n        ...init,\n        body: compressed,\n        headers: normalized,\n      })\n    } catch {\n      return baseFetch(input, init)\n    }\n  }\n}\n\n/**\n * Combines retry and circuit breaker into a single resilient fetch wrapper.\n * Rejects immediately when the circuit is open.\n */\nexport function createResilientFetch(\n  retryOptions?: RetryOptions,\n  breakerOptions?: CircuitBreakerOptions,\n): { fetch: typeof globalThis.fetch; breaker: CircuitBreaker } {\n  const breaker = new CircuitBreaker(breakerOptions)\n  const retryFetch = createRetryFetch(retryOptions)\n\n  const resilientFetch: typeof globalThis.fetch = async (input, init?) => {\n    if (breaker.isOpen()) {\n      const cooldown = Math.ceil((breakerOptions?.cooldownMs ?? 30_000) / 1000)\n      throw new Error(`Request blocked: too many consecutive failures. Retry in ${cooldown}s.`)\n    }\n\n    try {\n      const res = await retryFetch(input, init)\n      if (res.status >= 500) {\n        breaker.recordFailure()\n      } else {\n        breaker.recordSuccess()\n      }\n      return res\n    } catch (err) {\n      breaker.recordFailure()\n      throw err\n    }\n  }\n\n  return { fetch: resilientFetch, breaker }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Parse a `Retry-After` header value into milliseconds.\n *\n * - Numeric string (`\"30\"`) \u2014 treated as seconds \u00D7 1000.\n * - HTTP-date string \u2014 delta from now in ms (floored to 0).\n * - `null`, empty, or unparseable \u2014 returns `opts.fallbackMs`.\n *\n * All results are clamped to `[0, opts.maxMs]`.\n */\nexport function parseRetryAfterMs(\n  header: string | null | undefined,\n  opts: { fallbackMs: number; maxMs: number },\n): number {\n  const { fallbackMs, maxMs } = opts\n  const trimmed = header?.trim()\n  if (trimmed) {\n    const seconds = Number(trimmed)\n    if (!isNaN(seconds)) return Math.min(seconds * 1000, maxMs)\n    const date = Date.parse(trimmed)\n    if (!isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), maxMs)\n  }\n  return Math.min(fallbackMs, maxMs)\n}\n\n/** Error category returned by classifyError. */\nexport type ErrorCategory =\n  | \"network\"\n  | \"auth\"\n  | \"conflict\"\n  | \"rate-limited\"\n  | \"server\"\n  | \"client\"\n  | \"unknown\"\n\n/** Classify an error from a fetch response or network failure. */\nexport function classifyError(err: unknown): ErrorCategory {\n  if (err instanceof Response || (err && typeof err === \"object\" && \"status\" in err)) {\n    const status = (err as { status: unknown }).status\n    if (typeof status !== \"number\" || isNaN(status)) return \"unknown\"\n    if (status === 0) return \"network\"\n    if (status === 401 || status === 403) return \"auth\"\n    if (status === 409) return \"conflict\"\n    if (status === 429) return \"rate-limited\"\n    if (status >= 500) return \"server\"\n    if (status >= 400) return \"client\"\n  }\n  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return \"network\"\n  return \"unknown\"\n}\n\nexport interface RetryOptions {\n  /** Max number of retries (default: 3). */\n  maxRetries?: number\n  /** Initial delay in ms before first retry (default: 500). */\n  initialDelayMs?: number\n  /** Maximum delay in ms (default: 10000). */\n  maxDelayMs?: number\n}\n\n/**\n * Wraps a fetch function with automatic retry for retriable errors\n * (network failures, 429, 5xx). Respects Retry-After headers.\n */\nexport function createRetryFetch(options?: RetryOptions): typeof globalThis.fetch {\n  const maxRetries = Math.max(0, options?.maxRetries ?? 3)\n  const initialDelay = options?.initialDelayMs ?? 500\n  const maxDelay = options?.maxDelayMs ?? 10_000\n\n  return async (input, init?) => {\n    let attempt = 0\n    while (true) {\n      try {\n        const res = await globalThis.fetch(input, init)\n        if (res.ok || attempt >= maxRetries) return res\n\n        const category = classifyError(res)\n        if (category !== \"rate-limited\" && category !== \"server\") return res\n\n        const retryAfterHeader = res.headers.get(\"Retry-After\")\n        const exponentialDelay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay)\n        // When the header is present but unparseable, original falls back to\n        // initialDelay (not exponential). Preserve that by checking presence first.\n        const delay = parseRetryAfterMs(retryAfterHeader, {\n          fallbackMs: retryAfterHeader?.trim() ? initialDelay : exponentialDelay,\n          maxMs: maxDelay,\n        })\n\n        await new Promise<void>((r) => setTimeout(r, delay))\n        attempt++\n      } catch (err) {\n        if (attempt >= maxRetries) throw err\n        const category = classifyError(err)\n        if (category !== \"network\") throw err\n\n        const delay = Math.min(initialDelay * Math.pow(2, attempt), maxDelay)\n        await new Promise<void>((r) => setTimeout(r, delay))\n        attempt++\n      }\n    }\n  }\n}\n\ntype BreakerState = \"closed\" | \"open\" | \"half-open\"\n\nexport interface CircuitBreakerOptions {\n  /** Number of consecutive failures to open the circuit (default: 5). */\n  threshold?: number\n  /** Cooldown in ms before transitioning from open to half-open (default: 30000). */\n  cooldownMs?: number\n}\n\n/** Circuit breaker that prevents requests when the backend is unavailable. */\nexport class CircuitBreaker {\n  private state: BreakerState = \"closed\"\n  private failures = 0\n  private openedAt = 0\n  private readonly threshold: number\n  private readonly cooldownMs: number\n\n  constructor(options?: CircuitBreakerOptions) {\n    this.threshold = options?.threshold ?? 5\n    this.cooldownMs = options?.cooldownMs ?? 30_000\n  }\n\n  getState(): BreakerState {\n    this.maybeTransition()\n    return this.state\n  }\n\n  isOpen(): boolean {\n    return this.getState() === \"open\"\n  }\n\n  recordSuccess(): void {\n    this.failures = 0\n    this.state = \"closed\"\n  }\n\n  recordFailure(): void {\n    this.failures++\n    if (this.state === \"half-open\" || this.failures >= this.threshold) {\n      this.state = \"open\"\n      this.openedAt = Date.now()\n    }\n  }\n\n  private maybeTransition(): void {\n    if (this.state === \"open\" && Date.now() - this.openedAt >= this.cooldownMs) {\n      this.state = \"half-open\"\n    }\n  }\n}\n\n/**\n * Wraps fetch to gzip-compress string request bodies using the CompressionStream API.\n * Adds Content-Encoding: gzip header. Non-string bodies (ArrayBuffer, Blob, etc.)\n * are passed through uncompressed. Requires CompressionStream (browsers, Node.js 18+, Deno).\n */\nexport function createCompressedFetch(inner?: typeof globalThis.fetch): typeof globalThis.fetch {\n  const baseFetch = inner ?? globalThis.fetch.bind(globalThis)\n  return async (input, init?) => {\n    if (!init?.body || typeof CompressionStream === \"undefined\") {\n      return baseFetch(input, init)\n    }\n\n    const bodyText = typeof init.body === \"string\" ? init.body : null\n    if (!bodyText) return baseFetch(input, init)\n\n    try {\n      const stream = new Blob([bodyText]).stream().pipeThrough(new CompressionStream(\"gzip\"))\n      const compressed = await new Response(stream).arrayBuffer()\n\n      const normalized = Object.fromEntries(new Headers(init.headers as HeadersInit).entries())\n      normalized[\"content-encoding\"] = \"gzip\"\n\n      return baseFetch(input, {\n        ...init,\n        body: compressed,\n        headers: normalized,\n      })\n    } catch {\n      return baseFetch(input, init)\n    }\n  }\n}\n\n/**\n * Combines retry and circuit breaker into a single resilient fetch wrapper.\n * Rejects immediately when the circuit is open.\n */\nexport function createResilientFetch(\n  retryOptions?: RetryOptions,\n  breakerOptions?: CircuitBreakerOptions,\n): { fetch: typeof globalThis.fetch; breaker: CircuitBreaker } {\n  const breaker = new CircuitBreaker(breakerOptions)\n  const retryFetch = createRetryFetch(retryOptions)\n\n  const resilientFetch: typeof globalThis.fetch = async (input, init?) => {\n    if (breaker.isOpen()) {\n      const cooldown = Math.ceil((breakerOptions?.cooldownMs ?? 30_000) / 1000)\n      throw new Error(`Request blocked: too many consecutive failures. Retry in ${cooldown}s.`)\n    }\n\n    try {\n      const res = await retryFetch(input, init)\n      if (res.status >= 500) {\n        breaker.recordFailure()\n      } else {\n        breaker.recordSuccess()\n      }\n      return res\n    } catch (err) {\n      breaker.recordFailure()\n      throw err\n    }\n  }\n\n  return { fetch: resilientFetch, breaker }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { createMigrator } from "./migrate.js";
 export type { MigrationFn, MigrationConfig } from "./migrate.js";
 export { ValidationError, createSchemaValidator } from "./validate.js";
 export type { Validator, ValidationResult } from "./validate.js";
-export { classifyError } from "./fetch.js";
+export { classifyError, parseRetryAfterMs } from "./fetch.js";
 export type { ErrorCategory } from "./fetch.js";
 export { createUnionMerge, createSoftDeleteResolver, timestampWinner, pruneTombstones, withConflictMeta, } from "./resolvers.js";
 export type { ConflictMeta, ConflictResolverWithMeta } from "./resolvers.js";

package/dist/index.js

@@ -39,8 +39,41 @@ var StarfishHttpError = class extends Error {
   }
 };
 
+// src/fetch.ts
+function parseRetryAfterMs(header, opts) {
+  const { fallbackMs, maxMs } = opts;
+  const trimmed = header?.trim();
+  if (trimmed) {
+    const seconds = Number(trimmed);
+    if (!isNaN(seconds)) return Math.min(seconds * 1e3, maxMs);
+    const date = Date.parse(trimmed);
+    if (!isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), maxMs);
+  }
+  return Math.min(fallbackMs, maxMs);
+}
+function classifyError(err) {
+  if (err instanceof Response || err && typeof err === "object" && "status" in err) {
+    const status = err.status;
+    if (typeof status !== "number" || isNaN(status)) return "unknown";
+    if (status === 0) return "network";
+    if (status === 401 || status === 403) return "auth";
+    if (status === 409) return "conflict";
+    if (status === 429) return "rate-limited";
+    if (status >= 500) return "server";
+    if (status >= 400) return "client";
+  }
+  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return "network";
+  return "unknown";
+}
+
 // src/client.ts
 var APPEND_DEFAULT_FIELD = "items";
+var MAX_REVALIDATE_ATTEMPTS = 5;
+var REVALIDATE_INITIAL_DELAY_MS = 1e3;
+var REVALIDATE_MAX_DELAY_MS = 3e4;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function pullCacheKey(pathAndQuery) {
   const q = pathAndQuery.indexOf("?");
   return q === -1 ? pathAndQuery : pathAndQuery.slice(0, q);
@@ -67,6 +100,9 @@ var StarfishClient = class {
   fetch;
   cache;
   cacheMaxAgeMs;
+  cacheFallbackStatuses;
+  onRevalidated;
+  revalidating = /* @__PURE__ */ new Set();
   /**
    * Installed client-side plugins. Currently stored as inert data; no
    * hooks fire yet. Extensions can inspect this list if needed.
@@ -79,6 +115,8 @@ var StarfishClient = class {
     this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
     this.cache = options.cache;
     this.cacheMaxAgeMs = options.cacheMaxAgeMs;
+    this.cacheFallbackStatuses = options.cacheFallbackStatuses;
+    this.onRevalidated = options.onRevalidated;
     this.plugins = options.plugins ? [...options.plugins] : [];
   }
   /**
@@ -234,7 +272,17 @@ var StarfishClient = class {
       throw err;
     }
     if (!res.ok) {
-      throw new StarfishHttpError(res.status, await res.text());
+      const status = res.status;
+      if (cacheKey && this.cacheFallbackStatuses?.includes(status)) {
+        const retryAfterHeader = res.headers.get("Retry-After");
+        this.scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader);
+        const cached = await this.readCache(cacheKey);
+        if (cached) {
+          void res.body?.cancel();
+          return cached;
+        }
+      }
+      throw new StarfishHttpError(status, await res.text());
     }
     const result = await res.json();
     if (appendField !== void 0) {
@@ -253,6 +301,63 @@ var StarfishClient = class {
     }
     return result;
   }
+  /** Deduplicated fire-and-forget: starts one revalidation loop per cacheKey. */
+  scheduleRevalidate(cacheKey, pathAndQuery, retryAfterHeader) {
+    if (this.revalidating.has(cacheKey)) return;
+    this.revalidating.add(cacheKey);
+    void this.revalidateLoop(cacheKey, pathAndQuery, retryAfterHeader).finally(() => {
+      this.revalidating.delete(cacheKey);
+    });
+  }
+  /**
+   * Background revalidation loop for a {@link cacheFallbackStatuses} hit.
+   * Retries the pull (honoring `Retry-After`) up to {@link MAX_REVALIDATE_ATTEMPTS}
+   * times. On a live 2xx response the fresh snapshot is written through to the
+   * cache and {@link onRevalidated} fires. Stops early on a non-fallback HTTP
+   * status (e.g. 404/403 — the server gave a genuine answer).
+   */
+  async revalidateLoop(cacheKey, pathAndQuery, firstRetryAfter) {
+    let retryAfterHeader = firstRetryAfter;
+    for (let attempt = 0; attempt < MAX_REVALIDATE_ATTEMPTS; attempt++) {
+      const delay = parseRetryAfterMs(retryAfterHeader, {
+        fallbackMs: Math.min(
+          REVALIDATE_INITIAL_DELAY_MS * Math.pow(2, attempt),
+          REVALIDATE_MAX_DELAY_MS
+        ),
+        maxMs: REVALIDATE_MAX_DELAY_MS
+      });
+      await sleep(delay);
+      try {
+        const url = `${this.baseUrl}${pathAndQuery}`;
+        const authHeaders = await this.buildAuthHeaders("GET", pathAndQuery, void 0);
+        const res = await this.fetch(url, {
+          method: "GET",
+          headers: { [HEADER_ACCEPT]: "application/json", ...authHeaders }
+        });
+        if (res.ok) {
+          const result = await res.json();
+          if (this.cache) {
+            const snapshot = {
+              data: result.data,
+              hash: result.hash,
+              timestamp: result.timestamp,
+              cachedAt: Date.now()
+            };
+            void this.cache.set(cacheKey, JSON.stringify(snapshot)).catch(() => {
+            });
+          }
+          this.onRevalidated?.(pathAndQuery, result);
+          return;
+        }
+        if (!this.cacheFallbackStatuses?.includes(res.status)) {
+          return;
+        }
+        retryAfterHeader = res.headers.get("Retry-After");
+      } catch {
+        retryAfterHeader = null;
+      }
+    }
+  }
   /**
    * Read the cached snapshot for a document `path` WITHOUT hitting the network —
    * the basis for cache-first paint (seed the UI from the last-synced snapshot,
@@ -1008,22 +1113,6 @@ function createMigrator(config) {
   };
 }
 
-// src/fetch.ts
-function classifyError(err) {
-  if (err instanceof Response || err && typeof err === "object" && "status" in err) {
-    const status = err.status;
-    if (typeof status !== "number" || isNaN(status)) return "unknown";
-    if (status === 0) return "network";
-    if (status === 401 || status === 403) return "auth";
-    if (status === 409) return "conflict";
-    if (status === 429) return "rate-limited";
-    if (status >= 500) return "server";
-    if (status >= 400) return "client";
-  }
-  if (err instanceof Error && /failed to fetch|fetch failed|network|load failed|ECONNREFUSED|ENOTFOUND/i.test(err.message)) return "network";
-  return "unknown";
-}
-
 // src/resolvers.ts
 function shallowEqual(a, b) {
   if (a === b) return true;
@@ -1811,6 +1900,7 @@ export {
   isServiceWorkerSupported,
   mutateDoc,
   noopSyncLogger,
+  parseRetryAfterMs,
   pruneTombstones,
   pullWasFromCache,
   registerBackgroundSync,