@cross-deck/node 1.1.0 → 1.2.0

package/dist/index.mjs

@@ -318,7 +318,7 @@ function byteLength(s) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/node";
-var SDK_VERSION = "1.1.0";
+var SDK_VERSION = "1.2.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var CROSSDECK_API_VERSION = "2025-01-01";
@@ -1037,13 +1037,21 @@ function isInAppFrame(filename) {
   if (/^internal[\\/]/.test(filename)) return false;
   return true;
 }
-function fingerprintError(message, frames) {
+function fingerprintError(message, frames, location) {
   const inAppFrames = frames.filter((f) => f.in_app).slice(0, 3);
-  const key = [
+  const parts = [
     (message || "").slice(0, 200),
     ...inAppFrames.map((f) => `${f.function}@${f.filename}:${f.lineno}`)
-  ].join("|");
-  return djb2Hex(key);
+  ];
+  if (inAppFrames.length === 0 && location) {
+    const loc = [
+      location.errorType ?? "",
+      location.filename ?? "",
+      location.lineno ?? ""
+    ].join(":");
+    if (loc !== "::") parts.push(loc);
+  }
+  return djb2Hex(parts.join("|"));
 }
 function djb2Hex(input) {
   let h = 5381;
@@ -1274,34 +1282,30 @@ var ErrorTracker = class {
    * runtime-agnostic.
    */
   buildFromUnknown(err, kind, level) {
-    if (err instanceof Error) {
-      const frames = parseStack(err.stack);
-      return {
-        timestamp: Date.now(),
-        kind,
-        level,
-        message: String(err.message).slice(0, 1024),
-        errorType: err.name,
-        frames,
-        rawStack: err.stack ?? null,
-        fingerprint: fingerprintError(err.message, frames),
-        breadcrumbs: this.opts.breadcrumbs.snapshot(),
-        context: this.opts.getContext(),
-        tags: this.opts.getTags()
-      };
-    }
-    const message = safeStringify3(err).slice(0, 1024);
+    const payload = coerceErrorPayload(err);
+    const message = (payload.message || "Unknown error").slice(0, 1024);
+    const stack = err instanceof Error ? err.stack ?? null : null;
+    const frames = parseStack(stack);
+    const errorType = payload.errorType ?? null;
+    const context = payload.extras ? { ...this.opts.getContext(), __error_extras: payload.extras } : this.opts.getContext();
     return {
       timestamp: Date.now(),
       kind,
       level,
       message,
-      errorType: null,
-      frames: [],
-      rawStack: null,
-      fingerprint: fingerprintError(message, []),
+      errorType,
+      frames,
+      rawStack: stack,
+      // Location fallback ensures distinct call sites stay separate
+      // even when the message is generic and there are no parseable
+      // frames (e.g. `throw "boom"` from a middleware).
+      fingerprint: fingerprintError(message, frames, {
+        filename: frames[0]?.filename ?? null,
+        lineno: frames[0]?.lineno ?? null,
+        errorType
+      }),
       breadcrumbs: this.opts.breadcrumbs.snapshot(),
-      context: this.opts.getContext(),
+      context,
       tags: this.opts.getTags()
     };
   }
@@ -1316,7 +1320,10 @@ var ErrorTracker = class {
         errorType: "HTTPError",
         frames: [],
         rawStack: null,
-        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, []),
+        fingerprint: fingerprintError(`HTTP ${info.status} ${info.method}`, [], {
+          filename: info.url,
+          errorType: "HTTPError"
+        }),
         breadcrumbs: this.opts.breadcrumbs.snapshot(),
         context: this.opts.getContext(),
         tags: this.opts.getTags(),
@@ -1419,19 +1426,164 @@ var ErrorTracker = class {
     }
   }
 };
-function safeStringify3(v) {
-  if (v == null) return String(v);
-  if (typeof v === "string") return v;
-  if (typeof v === "number" || typeof v === "boolean") return String(v);
+function coerceErrorPayload(v) {
+  if (v === null) return { message: "(thrown: null)", errorType: null, extras: null };
+  if (v === void 0) return { message: "(thrown: undefined)", errorType: null, extras: null };
+  if (typeof v === "string") {
+    return { message: v, errorType: null, extras: null };
+  }
+  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") {
+    return { message: String(v), errorType: typeof v, extras: null };
+  }
+  if (typeof v === "symbol") {
+    return { message: v.toString(), errorType: "symbol", extras: null };
+  }
+  if (typeof v === "function") {
+    return { message: `(thrown function: ${v.name || "anonymous"})`, errorType: "function", extras: null };
+  }
+  if (v instanceof Error) {
+    const errorType = v.name || v.constructor?.name || "Error";
+    const message = typeof v.message === "string" && v.message.length > 0 ? v.message : safeToString(v) || errorType;
+    const extras = {};
+    const causeChain = collectCauseChain(v);
+    if (causeChain.length > 0) extras.cause = causeChain;
+    const aggErrors = v.errors;
+    if (Array.isArray(aggErrors)) {
+      extras.aggregatedErrors = aggErrors.slice(0, 10).map((inner) => {
+        if (inner instanceof Error) {
+          return { name: inner.name || "Error", message: inner.message || "" };
+        }
+        return { name: "non-Error", message: safeToString(inner) };
+      });
+    }
+    for (const key of [
+      "code",
+      "errno",
+      "syscall",
+      "path",
+      "status",
+      "statusCode",
+      "response",
+      "data",
+      "detail",
+      "details"
+    ]) {
+      const val = v[key];
+      if (val !== void 0 && typeof val !== "function") {
+        extras[key] = safeClone(val);
+      }
+    }
+    for (const key of Object.keys(v)) {
+      if (key === "message" || key === "stack" || key === "name" || key === "cause" || key === "errors") continue;
+      if (key in extras) continue;
+      const val = v[key];
+      if (typeof val === "function") continue;
+      extras[key] = safeClone(val);
+    }
+    return {
+      message,
+      errorType,
+      extras: Object.keys(extras).length > 0 ? extras : null
+    };
+  }
+  if (typeof Response !== "undefined" && v instanceof Response) {
+    return {
+      message: `HTTP ${v.status} ${v.statusText || ""}${v.url ? ` ${v.url}` : ""}`.trim(),
+      errorType: "Response",
+      extras: { status: v.status, statusText: v.statusText, url: v.url, type: v.type }
+    };
+  }
+  if (typeof v === "object") {
+    const obj = v;
+    const ctorName = obj.constructor && typeof obj.constructor === "function" && obj.constructor.name || null;
+    const ownMessage = typeof obj.message === "string" && obj.message ? obj.message : null;
+    const ownName = typeof obj.name === "string" && obj.name ? obj.name : null;
+    let jsonForm = null;
+    try {
+      const serialised = JSON.stringify(obj);
+      jsonForm = serialised === "{}" ? null : serialised;
+    } catch {
+      jsonForm = null;
+    }
+    const fallbackString = safeToString(obj);
+    const message = ownMessage ?? jsonForm ?? (fallbackString && fallbackString !== "[object Object]" ? fallbackString : null) ?? (ctorName ? `(thrown ${ctorName} with no message)` : "(thrown object with no message)");
+    const errorType = ownName ?? ctorName ?? null;
+    const extras = {};
+    let count = 0;
+    for (const key of Object.keys(obj)) {
+      if (count >= 20) break;
+      if (key === "message" || key === "name") continue;
+      const val = obj[key];
+      if (typeof val === "function") continue;
+      extras[key] = safeClone(val);
+      count++;
+    }
+    return {
+      message,
+      errorType,
+      extras: Object.keys(extras).length > 0 ? extras : null
+    };
+  }
+  return { message: safeToString(v) || "(unstringifiable thrown value)", errorType: null, extras: null };
+}
+function collectCauseChain(err) {
+  const out = [];
+  let cur = err.cause;
+  let depth = 0;
+  while (cur != null && depth < 5) {
+    if (cur instanceof Error) {
+      out.push({ name: cur.name || "Error", message: cur.message || "" });
+      cur = cur.cause;
+    } else {
+      out.push({ name: "non-Error", message: safeToString(cur) });
+      cur = null;
+    }
+    depth++;
+  }
+  return out;
+}
+function safeToString(v) {
   try {
-    return JSON.stringify(v);
+    const s = Object.prototype.toString.call(v);
+    if (s !== "[object Object]") return s;
+    const own = v?.toString;
+    if (typeof own === "function" && own !== Object.prototype.toString) {
+      const r = own.call(v);
+      if (typeof r === "string") return r;
+    }
+    return s;
   } catch {
-    return Object.prototype.toString.call(v);
+    return "(throwing toString)";
   }
 }
+function safeClone(v) {
+  if (v == null) return v;
+  const t = typeof v;
+  if (t === "string" || t === "number" || t === "boolean") return v;
+  if (t === "bigint") return String(v);
+  try {
+    const s = JSON.stringify(v);
+    return s === void 0 ? safeToString(v) : JSON.parse(s);
+  } catch {
+    return safeToString(v);
+  }
+}
+function safeStringify3(v) {
+  return coerceErrorPayload(v).message;
+}
 
 // src/runtime-info.ts
 import { hostname as osHostname, platform as osPlatform, release as osRelease } from "os";
+var SERVERLESS_HOSTS = /* @__PURE__ */ new Set([
+  "aws-lambda",
+  "azure-functions",
+  "google-app-engine",
+  "firebase-functions-v1",
+  "firebase-functions-v2",
+  "cloud-run",
+  "vercel",
+  "netlify"
+]);
 var cached = null;
 function collectRuntimeInfo(options = {}) {
   if (cached) return cached;
@@ -1447,6 +1599,7 @@ function detect(options) {
     platformRelease: safeRelease(),
     hostname: safeHostname(),
     host: detected.host,
+    isServerless: SERVERLESS_HOSTS.has(detected.host),
     region: detected.region,
     serviceName: options.serviceName ?? detected.serviceName,
     serviceVersion: options.serviceVersion ?? detected.serviceVersion,
@@ -1850,9 +2003,11 @@ var SuperPropertyStore = class {
 
 // src/entitlement-cache.ts
 var DEFAULT_MAX_CUSTOMERS = 1e4;
+var DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1e3;
 var EntitlementCache = class {
   ttlMs;
   maxCustomers;
+  staleAfterMs;
   byCustomer = /* @__PURE__ */ new Map();
   listeners = /* @__PURE__ */ new Set();
   listenerErrorCount = 0;
@@ -1860,52 +2015,95 @@ var EntitlementCache = class {
   constructor(options = {}) {
     this.ttlMs = options.ttlMs ?? 6e4;
     this.maxCustomers = options.maxCustomers ?? DEFAULT_MAX_CUSTOMERS;
+    this.staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
   }
   /**
-   * Synchronous lookup. Returns `true` iff the customer has the
-   * entitlement AND the cache entry is fresh (within `ttlMs`).
-   * Returns `false` otherwise (no entry / expired / key not active).
+   * Synchronous lookup — true iff the customer currently has the
+   * entitlement granting access. Pure in-memory `Map` read, ZERO I/O.
+   *
+   * Served from last-known-good: a stale entry (Crossdeck unreachable
+   * since the last successful fetch, or past `ttlMs`) STILL answers true
+   * for a still-valid entitlement. Cache staleness alone never makes
+   * this `false` — the central durability fix. The only things that
+   * turn it false:
+   *   - the customer has no cached entry at all (genuine cold miss)
+   *   - no matching `key` in the customer's entitlement set
+   *   - the matching entitlement is `isActive: false`
+   *   - the matching entitlement is past its OWN `validUntil` — a
+   *     time-based trial expiry still applies mid-outage (mirrors the
+   *     web SDK's `validUntil` check exactly).
+   *
+   * An entry being past `ttlMs`, or marked refresh-failed, does NOT
+   * affect the answer — `getEntitlements()` re-fetches on the TTL hint,
+   * but until it succeeds the customer keeps their access.
    */
   isEntitled(customerId, key) {
     const entry = this.byCustomer.get(customerId);
     if (!entry) return false;
-    if (Date.now() > entry.expiresAt) return false;
-    return entry.active.has(key);
+    const nowSec = Date.now() / 1e3;
+    return entry.all.some(
+      (e) => e.key === key && e.isActive && (e.validUntil == null || e.validUntil > nowSec)
+    );
   }
   /**
-   * Full snapshot for callers that need source / validUntil. Returns
-   * `[]` when the customer has no cached entry or the entry has
-   * expired.
+   * Full snapshot for callers that need source / validUntil details.
+   * Returns `[]` ONLY when the customer has no cached entry — a stale
+   * or past-TTL entry still returns its last-known-good entitlements
+   * (same durability posture as `isEntitled()`; per-entitlement
+   * `validUntil` is the caller's to honour from the returned objects).
    */
   list(customerId) {
     const entry = this.byCustomer.get(customerId);
     if (!entry) return [];
-    if (Date.now() > entry.expiresAt) return [];
     return entry.all.slice();
   }
   /**
-   * Whether a fresh entry exists for the customer. Useful for
-   * deciding whether to warm before a hot path.
+   * Whether the customer's entry is still within `ttlMs` — i.e. a
+   * re-fetch is NOT yet due. Useful for deciding whether to warm before
+   * a hot path. A `false` result does NOT mean the cache is empty or
+   * that `isEntitled()` will return false — it only means the data is
+   * past its refresh hint. See `needsRefresh()` for the inverse.
    */
   isFresh(customerId) {
     const entry = this.byCustomer.get(customerId);
-    return Boolean(entry && Date.now() <= entry.expiresAt);
+    return Boolean(entry && Date.now() <= entry.refreshDueAt);
   }
   /**
-   * Replace (or insert) the cache entry for a customer. Sets the
-   * `expiresAt` to `now + ttlMs`. Re-inserting an existing customerId
-   * "touches" it — the entry moves to the end of insertion order
-   * (Map semantics) so it's treated as most-recently-used for LRU
-   * eviction. Fires listeners.
+   * Whether the customer should be re-fetched: either there is no
+   * cached entry, or the entry is past its `ttlMs` refresh hint, or the
+   * most recent refresh attempt for them failed (retry it).
+   *
+   * This is purely advisory — `getEntitlements()` decides when to act
+   * on it. It NEVER gates `isEntitled()`, which serves last-known-good
+   * regardless.
+   */
+  needsRefresh(customerId) {
+    const entry = this.byCustomer.get(customerId);
+    if (!entry) return true;
+    if (entry.refreshFailedAt > 0) return true;
+    return Date.now() > entry.refreshDueAt;
+  }
+  /**
+   * Replace (or insert) the cache entry for a customer with a fresh
+   * server response. Sets `refreshDueAt` to `now + ttlMs` and CLEARS
+   * any failed-refresh marker — a success ends the stale state.
+   *
+   * Called ONLY after a SUCCESSFUL server read — a failed fetch is
+   * routed to `markRefreshFailed` instead and never reaches here, so
+   * last-known-good is preserved through an outage.
+   *
+   * Re-inserting an existing customerId "touches" it — the entry moves
+   * to the end of insertion order (Map semantics) so it's treated as
+   * most-recently-used for LRU eviction. Fires listeners.
    */
   setForCustomer(customerId, entitlements) {
     const now = Date.now();
     this.byCustomer.delete(customerId);
     this.byCustomer.set(customerId, {
       all: entitlements.slice(),
-      active: new Set(entitlements.filter((e) => e.isActive).map((e) => e.key)),
-      expiresAt: now + this.ttlMs,
-      populatedAt: now
+      refreshDueAt: now + this.ttlMs,
+      populatedAt: now,
+      refreshFailedAt: 0
     });
     while (this.byCustomer.size > this.maxCustomers) {
       const oldestKey = this.byCustomer.keys().next().value;
@@ -1915,6 +2113,68 @@ var EntitlementCache = class {
     }
     this.notify(customerId, entitlements);
   }
+  /**
+   * Record that a refresh attempt for a customer FAILED (Crossdeck
+   * unreachable / transient error). `getEntitlements()` calls this in
+   * its catch path.
+   *
+   * It does NOT touch the customer's cached entitlements — last-known-
+   * good keeps serving — it only stamps `refreshFailedAt` so the
+   * customer shows up as stale in `diagnostics()` rather than the
+   * staleness being a silent unbounded window.
+   *
+   * If the customer has no entry yet (a genuine cold miss whose first
+   * fetch failed) a stub entry with no entitlements is created purely
+   * to carry the failed-refresh marker — so "we tried and Crossdeck was
+   * down" is observable even before any successful warm. The stub holds
+   * an empty entitlement set, so `isEntitled()` still correctly returns
+   * false for it; there is genuinely nothing to serve.
+   */
+  markRefreshFailed(customerId) {
+    const now = Date.now();
+    const entry = this.byCustomer.get(customerId);
+    if (entry) {
+      entry.refreshFailedAt = now;
+      return;
+    }
+    this.byCustomer.set(customerId, {
+      all: [],
+      refreshDueAt: now + this.ttlMs,
+      populatedAt: 0,
+      refreshFailedAt: now
+    });
+    while (this.byCustomer.size > this.maxCustomers) {
+      const oldestKey = this.byCustomer.keys().next().value;
+      if (oldestKey === void 0) break;
+      this.byCustomer.delete(oldestKey);
+      this.evicted += 1;
+    }
+  }
+  /**
+   * Whether a customer is knowingly serving older-than-trustworthy
+   * data. True when the most recent refresh ATTEMPT for them failed
+   * (Crossdeck unreachable since the last success — the outage case,
+   * distinct from a benign idle customer simply past `ttlMs`), OR when
+   * their last-known-good has aged past `staleAfterMs`.
+   *
+   * `isStale` NEVER changes what `isEntitled()` returns — the cache
+   * still serves last-known-good. It exists so the staleness is
+   * observable via `diagnostics()` instead of an unbounded silent
+   * window where a revoked customer (event-based revoke, no
+   * `validUntil`) holds access with nobody able to see it.
+   *
+   * Returns false for an unknown customer — nothing cached, nothing
+   * stale.
+   */
+  isStale(customerId) {
+    const entry = this.byCustomer.get(customerId);
+    if (!entry) return false;
+    return this.entryIsStale(entry);
+  }
+  /** Epoch ms of a customer's last failed refresh, or 0 if none / unknown. */
+  refreshFailedAt(customerId) {
+    return this.byCustomer.get(customerId)?.refreshFailedAt ?? 0;
+  }
   /**
    * Drop a single customer's entry. Fires listeners with an empty
    * list so subscribers know that customer's cache is gone.
@@ -1980,7 +2240,57 @@ var EntitlementCache = class {
   get maxSize() {
     return this.maxCustomers;
   }
+  /** Configured staleness window in ms. */
+  get staleWindowMs() {
+    return this.staleAfterMs;
+  }
+  /**
+   * Count of cached customers currently flagged stale — most recent
+   * refresh failed, or data aged past `staleAfterMs`. The cache keeps
+   * serving last-known-good for them; this is the observability number
+   * `diagnostics()` surfaces.
+   */
+  get staleCustomerCount() {
+    let count = 0;
+    for (const entry of this.byCustomer.values()) {
+      if (this.entryIsStale(entry)) count += 1;
+    }
+    return count;
+  }
+  /** Whether ANY cached customer is currently stale. */
+  get isAnyStale() {
+    for (const entry of this.byCustomer.values()) {
+      if (this.entryIsStale(entry)) return true;
+    }
+    return false;
+  }
+  /**
+   * Most recent failed-refresh timestamp across all customers (epoch
+   * ms), or 0 if every cached customer's last refresh succeeded.
+   */
+  get lastRefreshFailedAt() {
+    let max = 0;
+    for (const entry of this.byCustomer.values()) {
+      if (entry.refreshFailedAt > max) max = entry.refreshFailedAt;
+    }
+    return max;
+  }
   // ---------- internals ----------
+  /**
+   * Stale iff the entry's most recent refresh attempt failed, OR its
+   * last-known-good has aged past `staleAfterMs`.
+   *
+   * `refreshFailedAt` is non-zero ONLY between a failed refresh and the
+   * next successful one (`setForCustomer` zeroes it), so `> 0` alone
+   * means "a failure occurred since the last success" — no need to
+   * compare against `populatedAt`, which would mis-fire when a failure
+   * and a populate land in the same millisecond. A marker-only stub
+   * (populatedAt 0, failure stamped) is stale via this first clause.
+   */
+  entryIsStale(entry) {
+    if (entry.refreshFailedAt > 0) return true;
+    return entry.populatedAt > 0 && Date.now() - entry.populatedAt > this.staleAfterMs;
+  }
   notify(customerId, snapshot) {
     if (this.listeners.size === 0) return;
     const snap = snapshot.slice();
@@ -2071,6 +2381,16 @@ var CrossdeckServer = class extends EventEmitter {
   flushOnExit;
   superProps;
   entitlementCache;
+  /**
+   * Optional developer-supplied durable store for last-known-good
+   * entitlements (Redis / their DB / a KV). `undefined` when not
+   * configured — the SDK then has no cold-start durability on
+   * serverless, which it states explicitly at boot.
+   *
+   * Touched ONLY from the async `getEntitlements()` — never from the
+   * synchronous `isEntitled()`.
+   */
+  entitlementStore;
   debug;
   /**
    * Alias map — `developerUserId` / `anonymousId` → canonical
@@ -2124,8 +2444,10 @@ var CrossdeckServer = class extends EventEmitter {
     this.breadcrumbs = new BreadcrumbBuffer(options.breadcrumbsMaxSize ?? 50);
     this.superProps = new SuperPropertyStore();
     this.entitlementCache = new EntitlementCache({
-      ttlMs: options.entitlementCacheTtlMs ?? 6e4
+      ttlMs: options.entitlementCacheTtlMs ?? 6e4,
+      staleAfterMs: options.entitlementStaleAfterMs
     });
+    this.entitlementStore = options.entitlementStore ?? null;
     this.debug = options.debug === true ? new ConsoleDebugLogger() : new NullDebugLogger();
     if (options.debug === true) this.debug.enabled = true;
     this.debug.emit(
@@ -2201,7 +2523,60 @@ var CrossdeckServer = class extends EventEmitter {
             { message: err instanceof Error ? err.message : String(err) }
           );
         });
+        this.emitBootTelemetry();
+      });
+    }
+  }
+  /**
+   * Emit the one-time `sdk.boot` telemetry event and, when the runtime
+   * is serverless with no `entitlementStore`, the honest "no cold-start
+   * durability" warning.
+   *
+   * Why a `track()` event and not the heartbeat: `GET /v1/sdk/heartbeat`
+   * carries no request body, so it cannot transport a structured
+   * `durability` fact. The event pipeline can — every `track()` event
+   * lands as an aggregatable document the backend can query, so
+   * Crossdeck can compute fleet-wide "% serverless-with-no-durable-
+   * store" from `sdk.boot` events (denominator = all `sdk.boot`,
+   * numerator = those with `durability.coldStartDurable === false`).
+   * The event rides the existing batched + retried + idempotent queue
+   * and is drained by flush-on-exit, so it survives a serverless
+   * teardown — it is NOT a local-only debug log.
+   *
+   * `isServerless` AND no store is the gap: a cold start begins with an
+   * empty in-memory cache and a brief Crossdeck outage in that window
+   * would read a paying customer as un-entitled. That gap is
+   * unavoidable without a store — so the SDK STATES it (a
+   * `sdk.no_durable_store` debug warning) rather than hiding it.
+   *
+   * Called once, from the deferred boot block — so it inherits the
+   * `testMode` / `bootHeartbeat:false` opt-outs and never fires before
+   * the constructor returns.
+   */
+  emitBootTelemetry() {
+    const isServerless = this.runtime.isServerless;
+    const hasStore = this.entitlementStore !== null;
+    const coldStartDurable = hasStore || !isServerless;
+    if (isServerless && !hasStore) {
+      this.debug.emit(
+        "sdk.no_durable_store",
+        `Running on a serverless host (${this.runtime.host}) with no entitlementStore. The entitlement cache is in-memory only, so a cold start begins empty: if Crossdeck is briefly unreachable during that window, isEntitled() can read a paying customer as un-entitled. Wire \`entitlementStore\` (Redis / your DB / a KV) to close this gap.`,
+        { host: this.runtime.host, isServerless, durableStore: false }
+      );
+    }
+    try {
+      this.track({
+        name: "sdk.boot",
+        anonymousId: this.processAnonymousId,
+        properties: {
+          "durability.entitlementStore": hasStore,
+          "durability.coldStartDurable": coldStartDurable,
+          "durability.runtimeIsServerless": isServerless,
+          "durability.runtimeHost": this.runtime.host,
+          "durability.entitlementCacheTtlMs": this.entitlementCache.ttl
+        }
       });
+    } catch {
     }
   }
   // ============================================================
@@ -2259,13 +2634,77 @@ var CrossdeckServer = class extends EventEmitter {
   // alias so a subsequent `isEntitled({ userId }, "pro")` resolves
   // to the same cache entry.
   // ============================================================
+  /**
+   * Fetch a customer's entitlements from Crossdeck and warm the cache.
+   *
+   * Durability — this is where last-known-good lives, NOT in the
+   * synchronous `isEntitled()`:
+   *   - On a SUCCESSFUL fetch: the entitlement cache is populated and,
+   *     if an `entitlementStore` is configured, the result is persisted
+   *     to it (`await store.save(...)`). The cache + store now hold
+   *     server-confirmed truth.
+   *   - On a network FAILURE: the cache is marked refresh-failed for the
+   *     customer (so `diagnostics()` shows the staleness), then — if a
+   *     store is configured — last-known-good is loaded back from it
+   *     (`await store.load(...)`). If the store yields a snapshot, the
+   *     cache is populated from it and that snapshot is RETURNED as a
+   *     normal `EntitlementsListResponse` — a cold-start / outage no
+   *     longer fails a paying customer. If there is no store, or the
+   *     store is empty, the network error is rethrown unchanged so the
+   *     caller still sees the failure.
+   *
+   * The store is touched only here, inside the `await` that already
+   * existed. `isEntitled()` remains a pure synchronous `Map` read.
+   */
   async getEntitlements(hints, options) {
-    const response = await this.http.request("GET", "/entitlements", {
-      query: this.identityPayload(hints),
-      signal: options?.signal,
-      timeoutMs: options?.timeoutMs
-    });
+    let response;
+    try {
+      response = await this.http.request("GET", "/entitlements", {
+        query: this.identityPayload(hints),
+        signal: options?.signal,
+        timeoutMs: options?.timeoutMs
+      });
+    } catch (err) {
+      const failedCustomerId = this.resolveFailedRefreshCustomerId(hints);
+      if (failedCustomerId) {
+        this.entitlementCache.markRefreshFailed(failedCustomerId);
+      }
+      const recovered = await this.loadEntitlementsFromStore(hints);
+      if (recovered) {
+        const recoveredResponse = {
+          object: "list",
+          data: recovered.entitlements,
+          crossdeckCustomerId: recovered.crossdeckCustomerId,
+          env: recovered.env
+        };
+        this.populateEntitlementCache(hints, recoveredResponse);
+        this.entitlementCache.markRefreshFailed(recovered.crossdeckCustomerId);
+        this.debug.emit(
+          "sdk.entitlement_store_recovered",
+          `Crossdeck unreachable \u2014 served ${recovered.crossdeckCustomerId} from the durable store (${recovered.entitlements.length} entitlement(s), last refreshed ${new Date(recovered.savedAt).toISOString()}).`,
+          {
+            customerId: recovered.crossdeckCustomerId,
+            savedAt: recovered.savedAt,
+            error: err instanceof Error ? err.message : String(err)
+          }
+        );
+        return recoveredResponse;
+      }
+      if (failedCustomerId && this.entitlementCache.isStale(failedCustomerId)) {
+        this.debug.emit(
+          "sdk.entitlement_cache_stale",
+          `Crossdeck unreachable \u2014 entitlement cache for ${failedCustomerId} is now stale. ` + (this.entitlementStore ? "No durable snapshot was available to recover from." : "No entitlementStore is configured, so there is no durable fallback.") + " isEntitled() keeps serving last-known-good; staleness is visible in diagnostics().",
+          {
+            customerId: failedCustomerId,
+            durableStore: this.entitlementStore !== null,
+            error: err instanceof Error ? err.message : String(err)
+          }
+        );
+      }
+      throw err;
+    }
     this.populateEntitlementCache(hints, response);
+    await this.saveEntitlementsToStore(hints, response);
     return response;
   }
   async getCustomerEntitlements(customerId, options) {
@@ -2779,7 +3218,14 @@ var CrossdeckServer = class extends EventEmitter {
         count: this.entitlementCache.customerCount,
         lastUpdated: this.entitlementCache.lastUpdated,
         ttlMs: this.entitlementCache.ttl,
-        listenerErrors: this.entitlementCache.listenerErrors
+        listenerErrors: this.entitlementCache.listenerErrors,
+        staleCustomers: this.entitlementCache.staleCustomerCount,
+        isStale: this.entitlementCache.isAnyStale,
+        lastRefreshFailedAt: this.entitlementCache.lastRefreshFailedAt,
+        durableStore: this.entitlementStore !== null,
+        // Cold-start durable iff a store is wired, OR the host is
+        // long-lived (the process, hence the in-memory cache, survives).
+        coldStartDurable: this.entitlementStore !== null || !this.runtime.isServerless
       },
       events: this.eventQueue.getStats(),
       errors: {
@@ -2993,6 +3439,90 @@ var CrossdeckServer = class extends EventEmitter {
     } catch {
     }
   }
+  /**
+   * Persist a successful entitlements fetch to the durable store, if
+   * one is configured. No-op when there is no store.
+   *
+   * Saved under EVERY identity the caller might later look up by — the
+   * canonical `crossdeckCustomerId` plus any `userId` / `anonymousId`
+   * hint. The Node cache resolves a hint to a canonical ID via an
+   * in-memory alias map; on a cold start that map is empty, so a
+   * failure-path `load()` must be able to hit the store with the raw
+   * hint the caller passed. Saving under all keys makes that work.
+   *
+   * Best-effort: a store `save()` that throws is swallowed (logged in
+   * debug) — it weakens durability for that customer but must never
+   * fail an otherwise-successful `getEntitlements()`.
+   */
+  async saveEntitlementsToStore(hints, response) {
+    if (!this.entitlementStore) return;
+    const customerId = response.crossdeckCustomerId;
+    if (!customerId) return;
+    const snapshot = {
+      v: 1,
+      crossdeckCustomerId: customerId,
+      entitlements: response.data,
+      env: response.env,
+      savedAt: Date.now()
+    };
+    const keys = /* @__PURE__ */ new Set([customerId]);
+    if (hints.customerId) keys.add(hints.customerId);
+    if (hints.userId) keys.add(hints.userId);
+    if (hints.anonymousId) keys.add(hints.anonymousId);
+    for (const key of keys) {
+      try {
+        await this.entitlementStore.save(key, snapshot);
+      } catch (err) {
+        this.debug.emit(
+          "sdk.entitlement_store_recovered",
+          `entitlementStore.save failed for key ${key} \u2014 durability weakened for this customer.`,
+          { key, error: err instanceof Error ? err.message : String(err) }
+        );
+      }
+    }
+  }
+  /**
+   * Load last-known-good entitlements from the durable store on a
+   * network-failure path. Returns the first snapshot found across the
+   * caller's identity keys, or `null` if there is no store / no stored
+   * snapshot / every read failed.
+   *
+   * Tries the canonical `customerId` hint first, then `userId`, then
+   * `anonymousId` — the order callers most commonly key by. A corrupt
+   * or wrong-shaped blob is treated as a miss (the store is developer-
+   * supplied; the SDK validates rather than trusts).
+   */
+  async loadEntitlementsFromStore(hints) {
+    if (!this.entitlementStore) return null;
+    const keys = [];
+    if (hints.customerId) keys.push(hints.customerId);
+    if (hints.userId) keys.push(hints.userId);
+    if (hints.anonymousId) keys.push(hints.anonymousId);
+    for (const key of keys) {
+      let loaded = null;
+      try {
+        loaded = await this.entitlementStore.load(key);
+      } catch {
+        continue;
+      }
+      if (isValidStoredEntitlements(loaded)) return loaded;
+    }
+    return null;
+  }
+  /**
+   * Resolve the customer ID to stamp a failed-refresh marker against.
+   *
+   * Prefers a canonical ID the cache already knows (so the marker lands
+   * on the existing warm entry), then falls back to whatever raw hint
+   * the caller supplied — on a true cold-start failure there is no
+   * cache entry yet, and marking under the hint still makes "we tried
+   * for this customer and Crossdeck was down" observable.
+   */
+  resolveFailedRefreshCustomerId(hints) {
+    const known = this.resolveCacheCustomerId(hints);
+    if (known) return known;
+    return hints.customerId ?? hints.userId ?? hints.anonymousId ?? null;
+  }
   touchAlias(alias, customerId) {
     this.customerIdAliases.delete(alias);
     this.customerIdAliases.set(alias, customerId);
@@ -3094,6 +3624,11 @@ function sanitizePropertyBag(input, fieldName) {
     });
   }
 }
+function isValidStoredEntitlements(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return v.v === 1 && typeof v.crossdeckCustomerId === "string" && v.crossdeckCustomerId.length > 0 && Array.isArray(v.entitlements) && (v.env === "production" || v.env === "sandbox") && typeof v.savedAt === "number";
+}
 function categoryFor(name) {
   if (name.startsWith("page.") || name.startsWith("navigation.")) return "navigation";
   if (name.startsWith("element.") || name.startsWith("ui.click")) return "ui.click";