@cross-deck/node 1.1.1 → 1.2.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementsListResponse, w as EntitlementsListener, x as Environment, y as ErrorCaptureConfig, z as ErrorLevel, F as EventProperties, G as ForgetResult, H as GrantDuration, I as GrantEntitlementInput, J as GroupMembership, K as HeartbeatResponse, L as HttpRequestInfo, M as HttpResponseInfo, N as HttpRetriesConfig, O as IdentifyOptions, P as IdentityHints, Q as IngestOptions, R as IngestResponse, S as PublicEntitlement, T as PurchaseResult, U as RequestOptions, V as RevokeEntitlementInput, W as RuntimeHost, X as RuntimeInfo, Y as SDK_NAME, Z as SDK_VERSION, _ as ServerEvent, $ as StackFrame, a0 as SyncPurchaseInput, a1 as makeCrossdeckError } from './crossdeck-server-BXQaFjVx.mjs';
+export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementStore, w as EntitlementsListResponse, x as EntitlementsListener, y as Environment, z as ErrorCaptureConfig, F as ErrorLevel, G as EventProperties, H as ForgetResult, I as GrantDuration, J as GrantEntitlementInput, K as GroupMembership, L as HeartbeatResponse, M as HttpRequestInfo, N as HttpResponseInfo, O as HttpRetriesConfig, P as IdentifyOptions, Q as IdentityHints, R as IngestOptions, S as IngestResponse, T as PublicEntitlement, U as PurchaseResult, V as RequestOptions, W as RevokeEntitlementInput, X as RuntimeHost, Y as RuntimeInfo, Z as SDK_NAME, _ as SDK_VERSION, $ as ServerEvent, a0 as StackFrame, a1 as StoredEntitlements, a2 as SyncPurchaseInput, a3 as makeCrossdeckError } from './crossdeck-server-BZVZEuS-.mjs';
 import 'node:events';
 
 /**
@@ -334,9 +334,12 @@ declare function scrubPiiFromProperties(properties: Record<string, unknown>): Re
  *   - `sdk.webhook_verified`
  *   - `sdk.runtime_detected`
  *   - `sdk.entitlement_cache_warm`
+ *   - `sdk.entitlement_cache_stale`
+ *   - `sdk.entitlement_store_recovered`
+ *   - `sdk.no_durable_store`
  *   - `sdk.super_property_registered`
  */
-type DebugSignal = "sdk.configured" | "sdk.first_event_sent" | "sdk.invalid_key" | "sdk.no_identity" | "sdk.entitlement_cache_used" | "sdk.entitlement_cache_warm" | "sdk.purchase_evidence_sent" | "sdk.environment_mismatch" | "sdk.sensitive_property_warning" | "sdk.property_coerced" | "sdk.flush_retry_scheduled" | "sdk.flush_on_exit_started" | "sdk.flush_on_exit_completed" | "sdk.webhook_verified" | "sdk.runtime_detected" | "sdk.super_property_registered" | "sdk.boot_heartbeat_failed";
+type DebugSignal = "sdk.configured" | "sdk.first_event_sent" | "sdk.invalid_key" | "sdk.no_identity" | "sdk.entitlement_cache_used" | "sdk.entitlement_cache_warm" | "sdk.entitlement_cache_stale" | "sdk.entitlement_store_recovered" | "sdk.no_durable_store" | "sdk.purchase_evidence_sent" | "sdk.environment_mismatch" | "sdk.sensitive_property_warning" | "sdk.property_coerced" | "sdk.flush_retry_scheduled" | "sdk.flush_on_exit_started" | "sdk.flush_on_exit_completed" | "sdk.webhook_verified" | "sdk.runtime_detected" | "sdk.super_property_registered" | "sdk.boot_heartbeat_failed";
 interface DebugContext {
     [key: string]: unknown;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementsListResponse, w as EntitlementsListener, x as Environment, y as ErrorCaptureConfig, z as ErrorLevel, F as EventProperties, G as ForgetResult, H as GrantDuration, I as GrantEntitlementInput, J as GroupMembership, K as HeartbeatResponse, L as HttpRequestInfo, M as HttpResponseInfo, N as HttpRetriesConfig, O as IdentifyOptions, P as IdentityHints, Q as IngestOptions, R as IngestResponse, S as PublicEntitlement, T as PurchaseResult, U as RequestOptions, V as RevokeEntitlementInput, W as RuntimeHost, X as RuntimeInfo, Y as SDK_NAME, Z as SDK_VERSION, _ as ServerEvent, $ as StackFrame, a0 as SyncPurchaseInput, a1 as makeCrossdeckError } from './crossdeck-server-BXQaFjVx.js';
+export { A as AliasIdentityInput, a as AliasResult, b as AuditDecision, c as AuditEntry, B as Breadcrumb, d as BreadcrumbCategory, e as BreadcrumbLevel, C as CROSSDECK_API_VERSION, f as CapturedError, g as CrossdeckAuthenticationError, h as CrossdeckConfigurationError, i as CrossdeckError, j as CrossdeckErrorPayload, k as CrossdeckErrorType, l as CrossdeckInternalError, m as CrossdeckNetworkError, n as CrossdeckPermissionError, o as CrossdeckRateLimitError, p as CrossdeckServer, q as CrossdeckServerOptions, r as CrossdeckValidationError, D as DEFAULT_BASE_URL, s as DEFAULT_TIMEOUT_MS, t as Diagnostics, E as EntitlementCacheOptions, u as EntitlementMutationResult, v as EntitlementStore, w as EntitlementsListResponse, x as EntitlementsListener, y as Environment, z as ErrorCaptureConfig, F as ErrorLevel, G as EventProperties, H as ForgetResult, I as GrantDuration, J as GrantEntitlementInput, K as GroupMembership, L as HeartbeatResponse, M as HttpRequestInfo, N as HttpResponseInfo, O as HttpRetriesConfig, P as IdentifyOptions, Q as IdentityHints, R as IngestOptions, S as IngestResponse, T as PublicEntitlement, U as PurchaseResult, V as RequestOptions, W as RevokeEntitlementInput, X as RuntimeHost, Y as RuntimeInfo, Z as SDK_NAME, _ as SDK_VERSION, $ as ServerEvent, a0 as StackFrame, a1 as StoredEntitlements, a2 as SyncPurchaseInput, a3 as makeCrossdeckError } from './crossdeck-server-BZVZEuS-.js';
 import 'node:events';
 
 /**
@@ -334,9 +334,12 @@ declare function scrubPiiFromProperties(properties: Record<string, unknown>): Re
  *   - `sdk.webhook_verified`
  *   - `sdk.runtime_detected`
  *   - `sdk.entitlement_cache_warm`
+ *   - `sdk.entitlement_cache_stale`
+ *   - `sdk.entitlement_store_recovered`
+ *   - `sdk.no_durable_store`
  *   - `sdk.super_property_registered`
  */
-type DebugSignal = "sdk.configured" | "sdk.first_event_sent" | "sdk.invalid_key" | "sdk.no_identity" | "sdk.entitlement_cache_used" | "sdk.entitlement_cache_warm" | "sdk.purchase_evidence_sent" | "sdk.environment_mismatch" | "sdk.sensitive_property_warning" | "sdk.property_coerced" | "sdk.flush_retry_scheduled" | "sdk.flush_on_exit_started" | "sdk.flush_on_exit_completed" | "sdk.webhook_verified" | "sdk.runtime_detected" | "sdk.super_property_registered" | "sdk.boot_heartbeat_failed";
+type DebugSignal = "sdk.configured" | "sdk.first_event_sent" | "sdk.invalid_key" | "sdk.no_identity" | "sdk.entitlement_cache_used" | "sdk.entitlement_cache_warm" | "sdk.entitlement_cache_stale" | "sdk.entitlement_store_recovered" | "sdk.no_durable_store" | "sdk.purchase_evidence_sent" | "sdk.environment_mismatch" | "sdk.sensitive_property_warning" | "sdk.property_coerced" | "sdk.flush_retry_scheduled" | "sdk.flush_on_exit_started" | "sdk.flush_on_exit_completed" | "sdk.webhook_verified" | "sdk.runtime_detected" | "sdk.super_property_registered" | "sdk.boot_heartbeat_failed";
 interface DebugContext {
     [key: string]: unknown;
 }

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";
@@ -1574,6 +1574,16 @@ function safeStringify3(v) {
 
 // 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;
@@ -1589,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,
@@ -1992,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;
@@ -2002,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);
+  }
+  /**
+   * 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. 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.
+   * 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;
@@ -2057,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.
@@ -2122,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();
@@ -2213,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
@@ -2266,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(
@@ -2343,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 {
     }
   }
   // ============================================================
@@ -2401,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) {
@@ -2921,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: {
@@ -3135,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);
@@ -3236,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";