@cross-deck/node 1.1.1 → 1.3.1

package/dist/index.mjs

@@ -316,9 +316,11 @@ function byteLength(s) {
   return s.length * 4;
 }
 
-// src/http.ts
+// src/_version.ts
+var SDK_VERSION = "1.3.1";
 var SDK_NAME = "@cross-deck/node";
-var SDK_VERSION = "1.1.0";
+
+// src/http.ts
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var CROSSDECK_API_VERSION = "2025-01-01";
@@ -831,6 +833,7 @@ var EventQueue = class {
         sdk: env.sdk
       };
       if (env.appId) body.appId = env.appId;
+      if (env.environment) body.environment = env.environment;
       const result = await this.cfg.http.request("POST", "/events", {
         body,
         idempotencyKey: batchId
@@ -849,6 +852,20 @@ var EventQueue = class {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       this.lastError = message;
+      if (isPermanent4xx(err)) {
+        const droppedCount = batch.length;
+        this.pendingBatch = null;
+        this.pendingBatchId = null;
+        this.inFlight -= droppedCount;
+        this.dropped += droppedCount;
+        this.cfg.onDrop?.(droppedCount);
+        this.cfg.onPermanentFailure?.({
+          status: err.status ?? 0,
+          droppedCount,
+          lastError: message
+        });
+        return null;
+      }
       const retryAfterMs = extractRetryAfterMs(err);
       const delay = this.retry.nextDelay(retryAfterMs);
       this.scheduleRetry(delay);
@@ -927,6 +944,14 @@ function extractRetryAfterMs(err) {
   }
   return void 0;
 }
+function isPermanent4xx(err) {
+  if (!err || typeof err !== "object") return false;
+  const status = err.status;
+  if (typeof status !== "number" || !Number.isFinite(status)) return false;
+  if (status < 400 || status >= 500) return false;
+  if (status === 408 || status === 429) return false;
+  return true;
+}
 function defaultScheduler(fn, ms) {
   const id = setTimeout(fn, ms);
   if (typeof id.unref === "function") {
@@ -1216,16 +1241,18 @@ var ErrorTracker = class {
       const url = typeof input === "string" ? input : input?.url ?? "";
       const method = (init.method || "GET").toUpperCase();
       const start = Date.now();
-      tracker.opts.breadcrumbs.add({
-        timestamp: start,
-        category: "http",
-        message: `${method} ${url}`,
-        data: { url, method }
-      });
+      if (!isSelfRequest(url, tracker.opts.selfHostname)) {
+        tracker.opts.breadcrumbs.add({
+          timestamp: start,
+          category: "http",
+          message: `${method} ${url}`,
+          data: { url, method }
+        });
+      }
       try {
         const response = await origFetch(...args);
         if (response.status >= 500 && tracker.opts.isConsented()) {
-          if (!url.includes("api.cross-deck.com")) {
+          if (!isSelfRequest(url, tracker.opts.selfHostname)) {
             tracker.captureHttp({
               url,
               method,
@@ -1343,9 +1370,10 @@ var ErrorTracker = class {
     if (!this.passesSample(err)) return;
     if (!this.passesRateLimit(err)) return;
     let finalErr = err;
-    if (this.opts.beforeSend) {
+    const hook = this.opts.beforeSend?.();
+    if (hook) {
       try {
-        finalErr = this.opts.beforeSend(err);
+        finalErr = hook(err);
       } catch {
         finalErr = err;
       }
@@ -1571,9 +1599,35 @@ function safeClone(v) {
 function safeStringify3(v) {
   return coerceErrorPayload(v).message;
 }
+function extractSelfHostname(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== "string") return null;
+  try {
+    return new URL(baseUrl).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+function isSelfRequest(requestUrl, selfHostname) {
+  if (!selfHostname || !requestUrl) return false;
+  try {
+    return new URL(requestUrl).hostname.toLowerCase() === selfHostname;
+  } catch {
+    return false;
+  }
+}
 
 // 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 +1643,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 +2047,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 +2059,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 +2157,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 +2284,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 +2425,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 +2488,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(
@@ -2285,6 +2509,11 @@ var CrossdeckServer = class extends EventEmitter {
       intervalMs: options.eventFlushIntervalMs ?? 1500,
       envelope: () => ({
         appId: this.appId,
+        // Ship env on every batch so the backend can cross-check
+        // against the API-key-derived env and reject mismatches
+        // loudly (env_mismatch). Web has always done this; node now
+        // matches so defence-in-depth is symmetric across SDKs.
+        environment: this.env,
         sdk: { name: SDK_NAME, version: this.sdkVersion }
       }),
       onDrop: (count) => {
@@ -2300,6 +2529,20 @@ var CrossdeckServer = class extends EventEmitter {
           nextRetryMs: info.delayMs
         });
       },
+      onPermanentFailure: (info) => {
+        const headline = `[crossdeck] Event batch DROPPED (status ${info.status}): ${info.lastError}. ${info.droppedCount} event(s) lost \u2014 check your secret key + app config.`;
+        console.error(headline);
+        this.debug.emit(
+          "sdk.flush_permanent_failure",
+          headline,
+          { ...info }
+        );
+        this.emit("queue.permanent_failure", {
+          status: info.status,
+          droppedCount: info.droppedCount,
+          error: info.lastError
+        });
+      },
       onFirstFlushSuccess: () => {
         this.debug.emit("sdk.first_event_sent", "First batch landed.");
       }
@@ -2314,14 +2557,20 @@ var CrossdeckServer = class extends EventEmitter {
         report: (err) => this.reportCapturedError(err),
         getContext: () => ({ ...this.errorContext }),
         getTags: () => ({ ...this.errorTags }),
-        beforeSend: null,
-        // wired via setErrorBeforeSend; ErrorTracker reads it through the live ref below
-        isConsented: () => true
-      });
-      const trackerOpts = this.errorTracker.opts;
-      Object.defineProperty(trackerOpts, "beforeSend", {
-        get: () => this.errorBeforeSend,
-        configurable: true
+        // GETTER, not a captured value — `setErrorBeforeSend()` mutates
+        // `this.errorBeforeSend` after init() and the tracker MUST pick
+        // up the new hook on the next error. Pre-fix we worked around
+        // a captured-by-value field with `Object.defineProperty` on the
+        // tracker's private opts; the contract is now a real getter so
+        // we just hand it the closure and the hack is gone.
+        beforeSend: () => this.errorBeforeSend,
+        isConsented: () => true,
+        // Derived from the configured baseUrl at construction time.
+        // Used by the fetch wrapper to skip captureHttp on Crossdeck's
+        // own requests — pre-fix the skip was hardcoded to
+        // `api.cross-deck.com` and broke for customers on staging /
+        // regional / self-hosted base URLs (recursive capture loop).
+        selfHostname: extractSelfHostname(this.baseUrl)
       });
       this.errorTracker.install();
     }
@@ -2334,6 +2583,7 @@ var CrossdeckServer = class extends EventEmitter {
       });
       this.flushOnExit.install();
     }
+    this.emitDurabilityWarning();
     if (options.testMode !== true && options.bootHeartbeat !== false) {
       setImmediate(() => {
         void this.heartbeat().catch((err) => {
@@ -2343,7 +2593,72 @@ var CrossdeckServer = class extends EventEmitter {
             { message: err instanceof Error ? err.message : String(err) }
           );
         });
+        this.emitBootTelemetryEvent();
+      });
+    }
+  }
+  /**
+   * Emit the honest "no cold-start durability" warning when the runtime
+   * is serverless AND no `entitlementStore` is wired. Local-only debug
+   * signal — no network call, no phone-home. Safe to fire from the
+   * constructor before `setImmediate` because there is no I/O on this
+   * path.
+   *
+   * `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.
+   *
+   * Audit P1 #9: this used to live INSIDE `emitBootTelemetry()` which
+   * itself sat inside the `bootHeartbeat` gate, so any developer who
+   * set `bootHeartbeat: false` silently disabled the entire reason
+   * `entitlementStore` exists. Now split: warning fires
+   * unconditionally; the boot phone-home stays gated.
+   */
+  emitDurabilityWarning() {
+    const isServerless = this.runtime.isServerless;
+    const hasStore = this.entitlementStore !== null;
+    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 }
+      );
+    }
+  }
+  /**
+   * Emit the one-time `sdk.boot` telemetry event — the aggregatable
+   * fact the backend pivots on (compute fleet-wide
+   * "% serverless-with-no-durable-store"). Rides the batched + retried
+   * + idempotent queue and is drained by flush-on-exit, so it survives
+   * a serverless teardown.
+   *
+   * Why a `track()` event and not the heartbeat: `GET /v1/sdk/heartbeat`
+   * carries no request body, so it cannot transport a structured
+   * `durability` fact.
+   *
+   * Gated by `bootHeartbeat` (and `testMode`) because it IS a phone-
+   * home — the unconditional surface is `emitDurabilityWarning()`,
+   * which has no network call.
+   */
+  emitBootTelemetryEvent() {
+    const isServerless = this.runtime.isServerless;
+    const hasStore = this.entitlementStore !== null;
+    const coldStartDurable = hasStore || !isServerless;
+    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 +2716,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) {
@@ -2578,7 +2957,13 @@ var CrossdeckServer = class extends EventEmitter {
     const normalized = events.map((event) => this.normalizeIngestEvent(event));
     const body = {
       events: normalized,
-      sdk: { name: SDK_NAME, version: this.sdkVersion }
+      sdk: { name: SDK_NAME, version: this.sdkVersion },
+      // Match the queue's batch envelope (see event-queue.ts) — backend
+      // cross-checks `environment` against the API-key-derived env and
+      // rejects mismatches loudly (env_mismatch). Pre-fix this direct
+      // ingest path skipped env, so a "live key, env: sandbox"
+      // misconfig fell through silently for the bulk-import path.
+      environment: this.env
     };
     if (this.appId) body.appId = this.appId;
     return this.http.request("POST", "/events", {
@@ -2643,8 +3028,9 @@ var CrossdeckServer = class extends EventEmitter {
         message: "syncPurchases requires a signedTransactionInfo string."
       });
     }
+    const rail = input.rail ?? "apple";
     return this.http.request("POST", "/purchases/sync", {
-      body: { rail: input.rail ?? "apple", ...input },
+      body: { ...input, rail },
       signal: options?.signal,
       timeoutMs: options?.timeoutMs
     });
@@ -2921,7 +3307,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 +3528,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);
@@ -3148,10 +3625,21 @@ var CrossdeckServer = class extends EventEmitter {
    * Resolve any hint shape (canonical customerId / userId hint /
    * anonymousId hint / raw string) to a `crossdeckCustomerId` if we
    * have a cache entry for it.
+   *
+   * String overload is STRICT on the canonical-id shape. Pre-fix
+   * `isFresh(raw)` treated any string with a cache entry as a valid
+   * canonical id — if tenant A's userId happened to collide with
+   * tenant B's crossdeckCustomerId, A's call would resolve to B's
+   * cached entitlements. Bounded by the `cdcust_` prefix convention
+   * (which both SDKs and the backend mint, see
+   * backend/src/lib/customers.ts) — anything else is treated purely
+   * as an alias lookup, never as a canonical id. Audit P1 #19.
    */
   resolveCacheCustomerId(hint) {
     if (typeof hint === "string") {
-      if (this.entitlementCache.isFresh(hint)) return hint;
+      if (hint.startsWith("cdcust_") && this.entitlementCache.isFresh(hint)) {
+        return hint;
+      }
       return this.customerIdAliases.get(hint) ?? null;
     }
     if (hint.customerId) return hint.customerId;
@@ -3236,6 +3724,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";
@@ -3522,20 +4015,11 @@ function normaliseSecrets(input) {
 // src/consent.ts
 var EMAIL_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
 var CARD_PATTERN = /\b\d(?:[ -]?\d){12,18}\b/g;
-var REPLACEMENT_EMAIL = "[email]";
-var REPLACEMENT_CARD = "[card]";
+var REPLACEMENT_EMAIL = "<email>";
+var REPLACEMENT_CARD = "<card>";
 function scrubPii(value) {
   if (!value) return value;
-  let out = value;
-  if (EMAIL_PATTERN.test(out)) {
-    out = out.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL);
-  }
-  EMAIL_PATTERN.lastIndex = 0;
-  if (CARD_PATTERN.test(out)) {
-    out = out.replace(CARD_PATTERN, REPLACEMENT_CARD);
-  }
-  CARD_PATTERN.lastIndex = 0;
-  return out;
+  return value.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL).replace(CARD_PATTERN, REPLACEMENT_CARD);
 }
 function scrubPiiFromProperties(properties) {
   const out = {};