@cross-deck/node 1.2.0 → 1.5.0

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   CROSSDECK_ERROR_CODES: () => CROSSDECK_ERROR_CODES,
   CrossdeckAuthenticationError: () => CrossdeckAuthenticationError,
   CrossdeckConfigurationError: () => CrossdeckConfigurationError,
+  CrossdeckContracts: () => CrossdeckContracts,
   CrossdeckError: () => CrossdeckError,
   CrossdeckInternalError: () => CrossdeckInternalError,
   CrossdeckNetworkError: () => CrossdeckNetworkError,
@@ -363,9 +364,11 @@ function byteLength(s) {
   return s.length * 4;
 }
 
-// src/http.ts
+// src/_version.ts
+var SDK_VERSION = "1.4.2";
 var SDK_NAME = "@cross-deck/node";
-var SDK_VERSION = "1.2.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";
@@ -878,6 +881,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
@@ -896,6 +900,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);
@@ -974,6 +992,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") {
@@ -1263,16 +1289,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,
@@ -1390,9 +1418,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;
       }
@@ -1618,6 +1647,22 @@ 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
 var import_node_os = require("os");
@@ -2352,6 +2397,63 @@ var EntitlementCache = class {
   }
 };
 
+// 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>";
+function scrubPii(value) {
+  if (!value) return value;
+  return value.replace(EMAIL_PATTERN, REPLACEMENT_EMAIL).replace(CARD_PATTERN, REPLACEMENT_CARD);
+}
+function scrubPiiFromProperties(properties) {
+  const out = {};
+  for (const k of Object.keys(properties)) {
+    out[k] = scrubValue(properties[k]);
+  }
+  return out;
+}
+function scrubValue(v) {
+  if (typeof v === "string") return scrubPii(v);
+  if (Array.isArray(v)) return v.map(scrubValue);
+  if (v && typeof v === "object" && v.constructor === Object) {
+    return scrubPiiFromProperties(v);
+  }
+  return v;
+}
+
+// src/idempotency-key.ts
+var import_node_crypto = require("crypto");
+function formatAsUuid(hex) {
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join("-");
+}
+function sha256Hex(input) {
+  return (0, import_node_crypto.createHash)("sha256").update(input, "utf8").digest("hex");
+}
+function deriveIdempotencyKeyForPurchase(body) {
+  let identifier;
+  if (body.rail === "apple") {
+    identifier = body.signedTransactionInfo ?? "";
+  } else if (body.rail === "google") {
+    identifier = body.purchaseToken ?? "";
+  } else {
+    identifier = "";
+  }
+  if (!identifier) {
+    throw new Error(
+      `deriveIdempotencyKeyForPurchase: no stable identifier in body (rail=${body.rail}). Apple needs signedTransactionInfo; Google needs purchaseToken.`
+    );
+  }
+  const namespaced = `crossdeck:purchases/sync:${body.rail}:${identifier}`;
+  return formatAsUuid(sha256Hex(namespaced));
+}
+
 // src/debug.ts
 var SENSITIVE_KEY_PATTERNS = [
   /^email$/i,
@@ -2411,6 +2513,10 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
   baseUrl;
   appId;
   env;
+  /** PII scrubber toggle. Default true — parity with Web/RN/Swift.
+   * Pre-v1.4.0 the Node SDK shipped track() payloads UNREDACTED,
+   * a privacy contract drift versus the README. */
+  scrubPii;
   secretKeyPrefix;
   /**
    * Process-stable pseudo-anonymous ID. Used as the default identity
@@ -2456,6 +2562,15 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
   errorContext = {};
   errorTags = {};
   errorBeforeSend = null;
+  /**
+   * Dedup gate for `sdk.shutdown`. Both `shutdown()` (async) and
+   * `shutdownSync()` need to emit so direct callers of EITHER see
+   * the event (the async path's listener guarantees pre-launch
+   * tests, the sync path covers `Symbol.dispose` + tests that call
+   * `shutdownSync()` directly). Without this flag, `shutdown()`'s
+   * tail call into `shutdownSync()` would emit twice.
+   */
+  didEmitShutdown = false;
   constructor(options) {
     super();
     if (!options.secretKey || !options.secretKey.startsWith("cd_sk_")) {
@@ -2470,6 +2585,7 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.env = inferEnvFromKey(options.secretKey);
     this.secretKeyPrefix = maskSecretKey(options.secretKey);
+    this.scrubPii = options.scrubPii !== false;
     this.http = new HttpClient({
       secretKey: options.secretKey,
       baseUrl: this.baseUrl,
@@ -2509,9 +2625,16 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     this.eventQueue = new EventQueue({
       http: this.http,
       batchSize: options.eventFlushBatchSize ?? 20,
-      intervalMs: options.eventFlushIntervalMs ?? 1500,
+      // v1.4.0 Phase 3.3 — flush interval default parity at 2000ms
+      // across every SDK. Per-instance override stays.
+      intervalMs: options.eventFlushIntervalMs ?? 2e3,
       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) => {
@@ -2527,6 +2650,20 @@ var CrossdeckServer = class extends import_node_events.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.");
       }
@@ -2541,14 +2678,20 @@ var CrossdeckServer = class extends import_node_events.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();
     }
@@ -2561,6 +2704,7 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
       });
       this.flushOnExit.install();
     }
+    this.emitDurabilityWarning();
     if (options.testMode !== true && options.bootHeartbeat !== false) {
       setImmediate(() => {
         void this.heartbeat().catch((err) => {
@@ -2570,25 +2714,16 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
             { message: err instanceof Error ? err.message : String(err) }
           );
         });
-        this.emitBootTelemetry();
+        this.emitBootTelemetryEvent();
       });
     }
   }
   /**
-   * 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.
+   * 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
@@ -2596,14 +2731,15 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
    * 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.
+   * 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.
    */
-  emitBootTelemetry() {
+  emitDurabilityWarning() {
     const isServerless = this.runtime.isServerless;
     const hasStore = this.entitlementStore !== null;
-    const coldStartDurable = hasStore || !isServerless;
     if (isServerless && !hasStore) {
       this.debug.emit(
         "sdk.no_durable_store",
@@ -2611,6 +2747,26 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         { 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",
@@ -2850,6 +3006,38 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
    *     `uncaughtException` has no per-request context; without the
    *     auto-fill, the event would be rejected at queue enqueue.
    */
+  /**
+   * Emit `crossdeck.contract_failed` with the canonical property
+   * shape. Same wire shape every Crossdeck SDK uses for contract
+   * verification telemetry — see `contracts/README.md` for the
+   * full pattern. No new endpoint, no special path; goes through
+   * the standard server-side `track()` pipeline.
+   */
+  reportContractFailure(input) {
+    const props = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "node",
+      failure_reason: input.failureReason,
+      run_context: input.runContext,
+      run_id: input.runId
+    };
+    if (input.testRef) {
+      props.test_file = input.testRef.file;
+      props.test_name = input.testRef.name;
+    }
+    if (input.extra) {
+      for (const [k, v] of Object.entries(input.extra)) {
+        if (props[k] === void 0) props[k] = v;
+      }
+    }
+    this.track({
+      name: "crossdeck.contract_failed",
+      properties: props
+      // No identity hint — these events are about the SDK / dogfood
+      // run itself, not a specific end-user.
+    });
+  }
   track(event) {
     if (!event.name) {
       throw new CrossdeckError({
@@ -2858,7 +3046,8 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         message: "track(event) requires a non-empty event.name."
       });
     }
-    const sanitized = sanitizePropertyBag(event.properties, "event properties") ?? {};
+    const validated = sanitizePropertyBag(event.properties, "event properties") ?? {};
+    const sanitized = this.scrubPii ? scrubPiiFromProperties(validated) : validated;
     if (this.debug.enabled) {
       const flagged = findSensitivePropertyKeys(sanitized);
       if (flagged.length > 0) {
@@ -2922,7 +3111,13 @@ var CrossdeckServer = class extends import_node_events.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", {
@@ -2987,11 +3182,26 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         message: "syncPurchases requires a signedTransactionInfo string."
       });
     }
-    return this.http.request("POST", "/purchases/sync", {
-      body: { rail: input.rail ?? "apple", ...input },
+    const rail = input.rail ?? "apple";
+    const body = { ...input, rail };
+    const idempotencyKey = options?.idempotencyKey ?? deriveIdempotencyKeyForPurchase(body);
+    const result = await this.http.request("POST", "/purchases/sync", {
+      body,
+      idempotencyKey,
       signal: options?.signal,
       timeoutMs: options?.timeoutMs
     });
+    try {
+      const sourceProductId = result.entitlements[0]?.source.productId;
+      const sourceSubscriptionId = result.entitlements[0]?.source.subscriptionId;
+      const props = { rail };
+      if (sourceProductId) props.productId = sourceProductId;
+      if (sourceSubscriptionId) props.subscriptionId = sourceSubscriptionId;
+      if (result.idempotent_replay) props.idempotent_replay = true;
+      this.track({ name: "purchase.completed", properties: props });
+    } catch {
+    }
+    return result;
   }
   // ============================================================
   // Manual entitlement controls + audit — direct HTTP
@@ -3283,12 +3493,56 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     };
   }
   /**
-   * Tear down handlers and clear in-memory state. Tests + custom
-   * lifecycle callers only. Production code should rely on
-   * `flush-on-exit` instead.
+   * Tear down handlers and clear in-memory state.
+   *
+   * **v1.4.0 bank-grade contract:** `shutdown()` AWAITS `flush()`
+   * before dropping the queue, so callers don't silently lose
+   * every queued event on a clean shutdown. The pre-v1.4.0
+   * behaviour (sync `eventQueue.reset()` with no flush) was the
+   * default for both `shutdown()` and `[Symbol.dispose]`; only
+   * `await using` + `[Symbol.asyncDispose]` flushed correctly.
+   *
+   * Production servers should still prefer `await server.flush()`
+   * (visible) followed by `server.shutdown()` so the flush
+   * outcome is observable — `shutdown()`'s internal flush swallows
+   * errors as a best-effort drain.
+   *
+   * Use [[shutdownSync]] only when the runtime cannot await
+   * (e.g. inside `Symbol.dispose` — see below).
    */
-  shutdown(reason = "shutdown") {
-    this.emit("sdk.shutdown", { reason });
+  async shutdown(reason = "shutdown") {
+    if (!this.didEmitShutdown) {
+      this.emit("sdk.shutdown", { reason });
+      this.didEmitShutdown = true;
+    }
+    try {
+      await this.flush();
+    } catch {
+    }
+    this.shutdownSync(reason);
+  }
+  /**
+   * Synchronous teardown — drops the in-memory queue WITHOUT
+   * flushing, then clears all in-memory state. Used by
+   * `[Symbol.dispose]` (which has no await) and tests that need
+   * an unconditional sync wipe. Production code should use
+   * [[shutdown]] (async) instead so queued events are flushed.
+   *
+   * A queue with items at sync-shutdown logs a warning recommending
+   * `[Symbol.asyncDispose]` or `await server.shutdown()` — silent
+   * loss is incompatible with the bank-grade contract.
+   */
+  shutdownSync(reason = "shutdown") {
+    if (!this.didEmitShutdown) {
+      this.emit("sdk.shutdown", { reason });
+      this.didEmitShutdown = true;
+    }
+    const queuedCount = this.eventQueue.getStats().buffered;
+    if (queuedCount > 0 && reason !== "asyncDispose") {
+      console.warn(
+        `[crossdeck] shutdownSync() dropped ${queuedCount} queued event(s) without flushing. Use \`await server.shutdown()\` or \`await using server = ...\` with \`[Symbol.asyncDispose]\` to drain the buffer before teardown.`
+      );
+    }
     this.errorTracker?.uninstall();
     this.flushOnExit?.uninstall();
     this.eventQueue.reset();
@@ -3402,28 +3656,28 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
    *   // ... use server ...
    *   // at end of block, server[Symbol.dispose]() runs automatically
    *
-   * `Symbol.dispose` is synchronous so we can't await `flush()` here
-   * — for that, use `await using` + `[Symbol.asyncDispose]()`. This
-   * sync variant just calls `shutdown()` (handler cleanup +
-   * in-memory state wipe).
+   * **`Symbol.dispose` is synchronous so it CANNOT await the queue
+   * flush.** A queue with pending events at sync-dispose time will
+   * be DROPPED — `shutdownSync` warns to the console when this
+   * happens. For the common case of "drain the queue before
+   * exit", switch to `await using` + `[Symbol.asyncDispose]` (or
+   * call `await server.shutdown()` explicitly before the variable
+   * goes out of scope).
    */
   [Symbol.dispose]() {
-    this.shutdown("dispose");
+    this.shutdownSync("dispose");
   }
   /**
    * Async disposal hook — runs when an `await using` declaration
-   * exits scope. Awaits `flush()` THEN runs `shutdown()`. Use this
-   * variant when the caller needs the queue drained before exit
-   * (the common case for serverless handlers).
+   * exits scope. Awaits the bank-grade `shutdown()` which flushes
+   * the queue THEN tears down. Use this variant for any code path
+   * that owns queued events at exit (serverless handlers,
+   * background workers, end-of-request hooks).
    *
    *   await using server = new CrossdeckServer({ ... });
    */
   async [Symbol.asyncDispose]() {
-    try {
-      await this.flush();
-    } catch {
-    }
-    this.shutdown("asyncDispose");
+    await this.shutdown("asyncDispose");
   }
   // ============================================================
   reportCapturedError(captured) {
@@ -3583,10 +3837,21 @@ var CrossdeckServer = class extends import_node_events.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;
@@ -3832,18 +4097,43 @@ var _CROSSDECK_ERROR_CODES = Object.freeze([
     retryable: false
   },
   // ----- Webhook verification (Node-specific) -----
+  // v1.4.0 Phase 7.2 — distinguishable codes. Pre-v1.4.0 the
+  // helper used webhook_invalid_signature for nearly every failure
+  // mode so a customer couldn't separate replay-attack signals
+  // from wrong-secret signals in alerting.
   {
-    code: "webhook_invalid_signature",
+    code: "webhook_signature_mismatch",
     type: "authentication_error",
-    description: "The webhook signature header did not verify against the supplied secret.",
-    resolution: "Confirm the secret matches the one in your Crossdeck dashboard \u2192 Webhooks page. If the request is genuinely from Crossdeck, the secret is wrong, stale, or recently rotated.",
+    description: "Webhook HMAC didn't verify against any configured secret (wrong-secret / stale rotation signal).",
+    resolution: "Confirm the secret matches dashboard \u2192 Webhooks. If you rotated, include both the old and new secret as an array until receivers cut over.",
     retryable: false
   },
   {
-    code: "webhook_replay_window_exceeded",
+    code: "webhook_timestamp_outside_tolerance",
+    type: "authentication_error",
+    description: "Webhook timestamp drift exceeds the configured replay-tolerance window (default 5 minutes; replay-attack signal).",
+    resolution: "Verify NTP on the receiving host. A spike on this code warrants its own alert separate from signature_mismatch \u2014 replay attacks look like this.",
+    retryable: false
+  },
+  {
+    code: "webhook_timestamp_missing",
     type: "authentication_error",
-    description: "The webhook timestamp is older than the replay-tolerance window (default 5 minutes).",
-    resolution: "The webhook is either replayed or your receiving clock is wildly skewed. Verify NTP on the receiving host. Increase replayToleranceMs only if you accept the replay-attack risk.",
+    description: "Webhook signature header is absent or has no `t=` timestamp segment \u2014 the timestamp gate cannot be verified.",
+    resolution: "Confirm the request actually came from Crossdeck (signature headers are always present on real deliveries). A missing header is either a misconfigured intermediary or a forged request.",
+    retryable: false
+  },
+  {
+    code: "webhook_payload_not_json",
+    type: "authentication_error",
+    description: "Webhook signature verified but the body isn't valid JSON \u2014 payload tampered post-signing or source bug.",
+    resolution: "Inspect the raw payload. If it's not JSON, either the request was modified in transit or the sender has a bug \u2014 file a support ticket with the raw body.",
+    retryable: false
+  },
+  {
+    code: "webhook_invalid_tolerance",
+    type: "configuration_error",
+    description: "verifyWebhookSignature() called with a non-finite / negative / above-24h-cap replayToleranceMs (would silently disable replay protection).",
+    resolution: "Pass a finite number between 0 and 86_400_000ms (24h). Default (5 minutes) is correct for almost every scenario. Pre-v1.4.0 accepted Infinity/NaN and silently dropped the check.",
     retryable: false
   },
   {
@@ -3852,6 +4142,101 @@ var _CROSSDECK_ERROR_CODES = Object.freeze([
     description: "verifyWebhookSignature() was called without a signing secret.",
     resolution: "Pass the secret from your Crossdeck dashboard \u2192 Webhooks page. Never hardcode in source \u2014 read from an env var.",
     retryable: false
+  },
+  {
+    code: "webhook_invalid_signature",
+    type: "authentication_error",
+    description: "DEPRECATED in v1.4.0 \u2014 split into webhook_signature_mismatch / webhook_timestamp_missing / webhook_timestamp_outside_tolerance / webhook_payload_not_json for alerting clarity.",
+    resolution: "Migrate alert rules to the more specific v1.4.0 codes \u2014 they distinguish replay-attack signals from wrong-secret signals.",
+    retryable: false
+  },
+  {
+    code: "webhook_replay_window_exceeded",
+    type: "authentication_error",
+    description: "DEPRECATED in v1.4.0 \u2014 renamed to webhook_timestamp_outside_tolerance.",
+    resolution: "Update alerts to webhook_timestamp_outside_tolerance.",
+    retryable: false
+  },
+  // ----- Backend-emitted codes (v1.4.0 Phase 6.2 backfill) -----
+  // Mirror of backend/src/api/v1-errors.ts ApiErrorCode. Same set
+  // as the Web SDK ships — keep these synchronised so a developer
+  // hitting any code via either SDK gets the same remediation.
+  {
+    code: "missing_api_key",
+    type: "authentication_error",
+    description: "No Authorization header (or Crossdeck-Api-Key header) on the request.",
+    resolution: "Confirm the CrossdeckServer was constructed with a cd_sk_\u2026 secretKey. Re-check env vars in production deployments.",
+    retryable: false
+  },
+  {
+    code: "invalid_api_key",
+    type: "authentication_error",
+    description: "The secret key is malformed, unknown, or doesn't resolve to a project.",
+    resolution: "Copy the key from Crossdeck dashboard \u2192 API keys. Server SDK requires cd_sk_test_ / cd_sk_live_ \u2014 client SDK keys (cd_pub_\u2026) won't work on the Node SDK.",
+    retryable: false
+  },
+  {
+    code: "key_revoked",
+    type: "authentication_error",
+    description: "The secret key was revoked in the dashboard.",
+    resolution: "Mint a fresh key in dashboard \u2192 API keys \u2192 Create new. The revoked key cannot be reactivated.",
+    retryable: false
+  },
+  {
+    code: "env_mismatch",
+    type: "permission_error",
+    description: "The key's env prefix doesn't match the resolved app's configured env.",
+    resolution: "Use a cd_sk_live_ key with a production app, cd_sk_test_ with a sandbox app. Crossing breaks the env lock.",
+    retryable: false
+  },
+  {
+    code: "idempotency_key_in_use",
+    type: "invalid_request_error",
+    description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).",
+    resolution: "Server SDK derives keys deterministically from the body since v1.4.0; this should only fire if you passed options.idempotencyKey explicitly. Use a fresh key per logical operation.",
+    retryable: false
+  },
+  {
+    code: "rate_limited",
+    type: "rate_limit_error",
+    description: "Request rate exceeded the project's per-second cap.",
+    resolution: "Honour Retry-After (managed retries do this automatically). For custom paths, throttle to <100 req/s/key.",
+    retryable: true
+  },
+  {
+    code: "internal_error",
+    type: "internal_error",
+    description: "Server-side issue. Safe to retry with backoff.",
+    resolution: "Managed retries handle this automatically. If a code path surfaces it to your code, contact support with the requestId.",
+    retryable: true
+  },
+  {
+    code: "google_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.",
+    resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The Android SDK auto-track path handles this transparently.",
+    retryable: false
+  },
+  {
+    code: "stripe_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=stripe is unsupported \u2014 Stripe webhooks deliver evidence server-side.",
+    resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically.",
+    retryable: false
+  },
+  {
+    code: "missing_required_param",
+    type: "invalid_request_error",
+    description: "A required field is absent from the request body.",
+    resolution: "The error.message identifies the missing field. Refer to the SDK's TypeScript types for canonical shapes.",
+    retryable: false
+  },
+  {
+    code: "invalid_param_value",
+    type: "invalid_request_error",
+    description: "A field is present but the value failed validation.",
+    resolution: "Read error.message for the field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
+    retryable: false
   }
 ]);
 function isCrossdeckErrorCode(code) {
@@ -3863,8 +4248,9 @@ function getErrorCode(code) {
 }
 
 // src/webhooks.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 var DEFAULT_REPLAY_TOLERANCE_MS = 5 * 60 * 1e3;
+var MAX_REPLAY_TOLERANCE_MS = 24 * 60 * 60 * 1e3;
 function verifyWebhookSignature(payload, signatureHeader, secret, options = {}) {
   const secrets = normaliseSecrets(secret);
   if (secrets.length === 0) {
@@ -3874,46 +4260,68 @@ function verifyWebhookSignature(payload, signatureHeader, secret, options = {})
       message: "verifyWebhookSignature requires a non-empty secret. Read it from process.env.CROSSDECK_WEBHOOK_SECRET \u2014 never hardcode in source."
     });
   }
+  const requestedTolerance = options.replayToleranceMs;
+  let tolerance;
+  if (requestedTolerance === void 0) {
+    tolerance = DEFAULT_REPLAY_TOLERANCE_MS;
+  } else if (typeof requestedTolerance !== "number" || !Number.isFinite(requestedTolerance)) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must be a finite non-negative number \u2264 ${MAX_REPLAY_TOLERANCE_MS} (24h). Got: ${String(requestedTolerance)}. Pre-v1.4.0 accepted Infinity/NaN/null and silently disabled replay protection \u2014 v1.4.0 rejects loudly.`
+    });
+  } else if (requestedTolerance < 0) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must be \u2265 0. Got ${requestedTolerance}.`
+    });
+  } else if (requestedTolerance > MAX_REPLAY_TOLERANCE_MS) {
+    throw new CrossdeckError({
+      type: "configuration_error",
+      code: "webhook_invalid_tolerance",
+      message: `replayToleranceMs must not exceed ${MAX_REPLAY_TOLERANCE_MS}ms (24h). Got ${requestedTolerance}ms \u2014 a window that wide defeats replay protection.`
+    });
+  } else {
+    tolerance = requestedTolerance;
+  }
   const header = normaliseHeader(signatureHeader);
   const parsed = parseSignatureHeader(header);
   if (!parsed) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
-      message: "Webhook signature header is missing or malformed. Expected 'Crossdeck-Signature: t=<unix>,v1=<hex>'."
+      code: "webhook_timestamp_missing",
+      message: "Webhook signature header is missing, malformed, or has no `t=` timestamp segment. Expected 'Crossdeck-Signature: t=<unix>,v1=<hex>'."
     });
   }
-  const tolerance = options.replayToleranceMs ?? DEFAULT_REPLAY_TOLERANCE_MS;
-  if (tolerance > 0) {
-    const now = (options.now ?? Date.now)();
-    const timestampMs = parsed.timestampSec * 1e3;
-    const drift = Math.abs(now - timestampMs);
-    if (drift > tolerance) {
-      throw new CrossdeckError({
-        type: "authentication_error",
-        code: "webhook_replay_window_exceeded",
-        message: `Webhook timestamp is ${drift}ms outside the ${tolerance}ms replay-tolerance window. Either the request is replayed or the receiving clock is skewed \u2014 verify NTP on the host.`
-      });
-    }
+  const now = (options.now ?? Date.now)();
+  const timestampMs = parsed.timestampSec * 1e3;
+  const drift = Math.abs(now - timestampMs);
+  if (drift > tolerance) {
+    throw new CrossdeckError({
+      type: "authentication_error",
+      code: "webhook_timestamp_outside_tolerance",
+      message: `Webhook timestamp is ${drift}ms outside the ${tolerance}ms replay-tolerance window. Either the request is replayed or the receiving clock is skewed \u2014 verify NTP on the host.`
+    });
   }
   const signedPayload = `${parsed.timestampSec}.${payload}`;
   const expectedBuf = Buffer.from(parsed.signature, "hex");
   if (expectedBuf.length === 0) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
+      code: "webhook_signature_mismatch",
       message: "Webhook signature is not a valid hex string."
     });
   }
   const anyMatch = secrets.some((s) => {
-    const computed = (0, import_node_crypto.createHmac)("sha256", s).update(signedPayload).digest();
-    return computed.length === expectedBuf.length && (0, import_node_crypto.timingSafeEqual)(computed, expectedBuf);
+    const computed = (0, import_node_crypto2.createHmac)("sha256", s).update(signedPayload).digest();
+    return computed.length === expectedBuf.length && (0, import_node_crypto2.timingSafeEqual)(computed, expectedBuf);
   });
   if (!anyMatch) {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
-      message: "Webhook signature did not verify. Confirm the secret matches your Crossdeck dashboard \u2192 Webhooks page (and that you're not on a stale rotation)."
+      code: "webhook_signature_mismatch",
+      message: "Webhook signature did not verify against any configured secret. Confirm the secret matches your Crossdeck dashboard \u2192 Webhooks page (and that you're not on a stale rotation)."
     });
   }
   try {
@@ -3921,13 +4329,13 @@ function verifyWebhookSignature(payload, signatureHeader, secret, options = {})
   } catch {
     throw new CrossdeckError({
       type: "authentication_error",
-      code: "webhook_invalid_signature",
+      code: "webhook_payload_not_json",
       message: "Webhook signature verified but the payload is not valid JSON. Either the payload was tampered with after signing, or the webhook source is misconfigured."
     });
   }
 }
 function signWebhookPayload(payload, secret, timestampSec) {
-  return (0, import_node_crypto.createHmac)("sha256", secret).update(`${timestampSec}.${payload}`).digest("hex");
+  return (0, import_node_crypto2.createHmac)("sha256", secret).update(`${timestampSec}.${payload}`).digest("hex");
 }
 function parseSignatureHeader(header) {
   if (!header) return null;
@@ -3959,45 +4367,472 @@ function normaliseSecrets(input) {
   return arr.filter((s) => typeof s === "string" && s.length > 0);
 }
 
-// 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]";
-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;
-}
-function scrubPiiFromProperties(properties) {
-  const out = {};
-  for (const k of Object.keys(properties)) {
-    out[k] = scrubValue(properties[k]);
+// src/_contracts-bundled.ts
+var BUNDLED_IN = "@cross-deck/node@1.5.0";
+var SDK_VERSION2 = "1.5.0";
+var BUNDLED_CONTRACTS = Object.freeze([
+  {
+    "id": "documentation-honesty",
+    "pillar": "webhooks",
+    "status": "enforced",
+    "claim": "Customer-facing documentation honestly tags outbound webhook delivery as ROADMAP (no signer, no worker, no scheduler in backend/src yet). The Node verifier helper exists today for fixture authoring + locking the validation contract surface BEFORE delivery ships \u2014 its jsdoc carries an explicit `[ROADMAP]` disclaimer so a developer reading the source doesn't assume Crossdeck sends webhooks today. The rail-webhooks doc no longer claims state surfaces 'through the dashboard, SDKs, and outbound webhooks' \u2014 outbound is gated to the explicit roadmap section.",
+    "appliesTo": [
+      "node",
+      "backend"
+    ],
+    "codeRef": [
+      "sdks/node/src/webhooks.ts",
+      "docs/rail-webhooks/index.html",
+      "docs/webhooks-receive/index.html"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/node/src/webhooks.ts",
+        "name": "[ROADMAP \u2014 v1.4.0 honesty note]"
+      },
+      {
+        "file": "docs/rail-webhooks/index.html",
+        "name": "Outbound push-to-your-backend webhooks are <strong>roadmap</strong>"
+      },
+      {
+        "file": "docs/webhooks-receive/index.html",
+        "name": "This feature is on the roadmap"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.1",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "error-envelope-shape",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Every v1 REST endpoint returns errors in a Stripe-shape envelope: `{ error: { type, code, message, request_id } }` where `type` is one of authentication_error / permission_error / invalid_request_error / rate_limit_error / internal_error (the wire vocabulary in backend/src/api/v1-errors.ts ApiErrorType). HTTP status parity: invalid_request_error \u2192 400, authentication_error \u2192 401, permission_error \u2192 403, rate_limit_error \u2192 429, internal_error \u2192 500. SDK-side clients parse this shape via `crossdeckErrorFromResponse` (Web/Node/RN) / `crossdeckErrorFrom(response:)` (Swift) / `crossdeckErrorFromResponse` (Android) and surface the request_id verbatim so support traces are end-to-end joinable. Firebase callable endpoints (managed-keys / dashboard auth) use the Firebase HttpsError envelope instead \u2014 this contract applies to REST /v1/* only.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "backend/src/api/v1-errors.ts",
+      "sdks/web/src/errors.ts",
+      "sdks/node/src/errors.ts",
+      "sdks/react-native/src/errors.ts",
+      "sdks/swift/Sources/Crossdeck/Errors.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Errors.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_fallsBackOnGarbageBody"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_reads_XRequestId_fallback"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ErrorTypeWireVocabTest.kt",
+        "name": "backend 500 response parses to INTERNAL_ERROR"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "flush-interval-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Every Crossdeck SDK defaults its event-queue flush interval to 2000ms \u2014 the Stripe-adjacent industry norm. Pre-v1.4.0 the defaults disagreed (Web/Node 1500ms; RN/Swift/Android 5000ms), so cross-platform funnels saw events landing at different cadences. Per-instance override stays \u2014 call sites can still tune it freely.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+        "name": "flushIntervalMs: Int = 2_000"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt",
+        "name": "flushIntervalMs: Long = 2_000L"
+      },
+      {
+        "file": "sdks/web/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/node/src/crossdeck-server.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/react-native/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "idempotency-key-deterministic",
+    "pillar": "revenue",
+    "status": "enforced",
+    "claim": "syncPurchases() on every SDK derives a deterministic Idempotency-Key from the request body (UUID-shaped SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Same input -> same key. Backend short-circuits same-key-same-body retries by returning the cached response (status + body) with `idempotent_replay: true` flag in the body AND `Idempotent-Replayed: true` response header. Same-key-different-body returns 400 `idempotency_key_in_use`. 24-hour TTL matches Stripe. Cache only stores 2xx responses \u2014 4xx/5xx pass through so callers can fix bugs and retry. Helper returns nil/throws on missing identifier (no silent random fallback). Cross-SDK parity is CI-pinned: deriveForPurchase('apple', 'eyJ.jws.sig') MUST equal 'a66b1640-efaf-bb4d-1261-6650033bf111' on every SDK.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "sdks/web/src/idempotency-key.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/idempotency-key.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/node/src/idempotency-key.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt",
+      "backend/src/lib/idempotency-response-cache.ts",
+      "backend/src/api/v1-purchases.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "is deterministic: same body twice -> identical key"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "same identifier under different rails -> different keys"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "never silently falls back to a random key on missing identifier"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "apple JWS produces the canonical pinned UUID across all 5 SDKs"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "is deterministic for the same input"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "injects idempotent_replay: true into a JSON object body"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "matches Stripe's 24-hour idempotency window"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_crossSdkOracle_appleJWS"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_railNamespacing_preventsCrossRailCollisions"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_missingIdentifier_returnsNil"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "cross-SDK oracle for apple JWS"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "missing identifier returns null - never silent random fallback"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "node-pii-scrubber",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Node SDK's track() applies scrubPiiFromProperties on the enqueue path \u2014 parity with Web/RN/Swift. Pre-v1.4.0 the Node SDK was the ONLY one that skipped this, shipping every track() payload UNREDACTED despite the README promising parity. CrossdeckServerOptions.scrubPii defaults to true; explicit false opts out for regulator-required audit trails with a documented blast-radius warning.",
+    "appliesTo": [
+      "node"
+    ],
+    "codeRef": [
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/node/src/types.ts",
+      "sdks/node/src/consent.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/node/tests/track-pii-scrub.test.ts",
+        "name": "by default redacts email-shaped values to <email>"
+      },
+      {
+        "file": "sdks/node/tests/track-pii-scrub.test.ts",
+        "name": "redacts card-number-shaped values to <card>"
+      },
+      {
+        "file": "sdks/node/tests/track-pii-scrub.test.ts",
+        "name": "walks nested maps + arrays"
+      },
+      {
+        "file": "sdks/node/tests/track-pii-scrub.test.ts",
+        "name": "scrubPii: false preserves the raw payload (opt-out)"
+      },
+      {
+        "file": "sdks/node/tests/track-pii-scrub.test.ts",
+        "name": "scrubPii: true is the default when option is omitted"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.1",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "node-shutdown-awaits-flush",
+    "pillar": "lifecycle",
+    "status": "enforced",
+    "claim": "Node SDK's async shutdown() awaits the internal flush() before tearing down the queue. A queue with pending events at sync-shutdown time (shutdownSync() or [Symbol.dispose]) logs a console.warn with the dropped-event count \u2014 silent loss is incompatible with the bank-grade contract. [Symbol.asyncDispose] is equivalent to await server.shutdown().",
+    "appliesTo": [
+      "node"
+    ],
+    "codeRef": [
+      "sdks/node/src/crossdeck-server.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/node/tests/shutdown-flush.test.ts",
+        "name": "async shutdown() flushes queued events before clearing"
+      },
+      {
+        "file": "sdks/node/tests/shutdown-flush.test.ts",
+        "name": "async shutdown() proceeds with teardown even if flush fails"
+      },
+      {
+        "file": "sdks/node/tests/shutdown-flush.test.ts",
+        "name": "sync shutdownSync() warns when the buffer has events at teardown"
+      },
+      {
+        "file": "sdks/node/tests/shutdown-flush.test.ts",
+        "name": "[Symbol.asyncDispose] equals await server.shutdown()"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.4",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "sdk-error-codes-catalogue",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Web + Node SDK error-codes catalogues include EVERY backend-emitted ApiErrorCode with a description + resolution. Pre-v1.4.0 the catalogues documented codes the SDK threw ITSELF but ZERO backend codes \u2014 a developer hitting `invalid_api_key` / `origin_not_allowed` / `bundle_id_not_allowed` / `env_mismatch` / `idempotency_key_in_use` etc. got `undefined` from getErrorCode() and had to hunt for guidance. v1.4.0 backfills the catalogue from backend/src/api/v1-errors.ts so every wire code has a canonical 'what does this mean / what should I do' answer Stripe-style.",
+    "appliesTo": [
+      "web",
+      "node"
+    ],
+    "codeRef": [
+      "sdks/web/src/error-codes.ts",
+      "sdks/node/src/error-codes.ts",
+      "backend/src/api/v1-errors.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "includes backend code"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "invalid_api_key resolution points at the dashboard"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "idempotency_key_in_use resolution mentions Stripe-grade contract"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "identity-lock codes carry permission_error type"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "no entry has an empty description or resolution"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "sync-purchases-funnel-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Manual syncPurchases() emits a `purchase.completed` analytics event on success across ALL SDKs (Web / Node / RN / Swift / Android). Pre-v1.4.0 only Swift/Android auto-track emitted it \u2014 Web/Node/RN manual calls + Swift/Android manual calls fired ZERO analytics. Schema mirrors the auto-track event name + rail/productId/subscriptionId so cross-platform funnels reconcile on every payment path. When the backend short-circuits via the v1.4.0 idempotency cache, the event also carries `idempotent_replay: true`.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "emits purchase.completed after a successful sync"
+      },
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "carries idempotent_replay=true when backend replied from cache"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
+    "bundledIn": "@cross-deck/node@1.5.0"
+  },
+  {
+    "id": "verifier-timestamp-mandatory",
+    "pillar": "webhooks",
+    "status": "enforced",
+    "claim": "Node verifyWebhookSignature() enforces a MANDATORY timestamp window. Pre-v1.4.0 the helper silently disabled replay protection on tolerance=0 (`if (tolerance > 0)` skipped the check) and on Infinity/NaN/null (`Math.abs(...) > Infinity = false`). v1.4.0 rejects non-finite / negative / above-24h-cap tolerances at the boundary with typed `webhook_invalid_tolerance` and always runs the drift check. Verification failures are surfaced via distinguishable codes: `webhook_signature_mismatch` (wrong-secret signal), `webhook_timestamp_outside_tolerance` (replay-attack signal \u2014 alert separately), `webhook_timestamp_missing` (header absent/malformed), `webhook_payload_not_json` (tampered post-signing), `webhook_missing_secret`, `webhook_invalid_tolerance` \u2014 replaces the pre-1.4.0 single `webhook_invalid_signature` catch-all.",
+    "appliesTo": [
+      "node"
+    ],
+    "codeRef": [
+      "sdks/node/src/webhooks.ts",
+      "sdks/node/src/error-codes.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "tolerance of 0 still enforces the replay window (v1.4.0 \u2014 cannot disable)"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "rejects Infinity tolerance (would silently disable replay protection)"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "rejects NaN tolerance"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "rejects negative tolerance"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "rejects tolerance above the 24h cap"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "rejects non-number tolerance (null / string)"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "accepts tolerance exactly at the 24h cap"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "malformed header (no t= or no v1=) throws webhook_timestamp_missing"
+      },
+      {
+        "file": "sdks/node/tests/webhooks.test.ts",
+        "name": "valid signature but non-JSON payload throws webhook_payload_not_json"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.2",
+    "bundledIn": "@cross-deck/node@1.5.0"
   }
-  return out;
-}
-function scrubValue(v) {
-  if (typeof v === "string") return scrubPii(v);
-  if (Array.isArray(v)) return v.map(scrubValue);
-  if (v && typeof v === "object" && v.constructor === Object) {
-    return scrubPiiFromProperties(v);
+]);
+
+// src/contracts.ts
+var CrossdeckContracts = {
+  all() {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === "enforced");
+  },
+  allIncludingHistorical() {
+    return BUNDLED_CONTRACTS;
+  },
+  byId(id) {
+    return BUNDLED_CONTRACTS.find((c) => c.id === id);
+  },
+  byPillar(pillar) {
+    return BUNDLED_CONTRACTS.filter(
+      (c) => c.pillar === pillar && c.status === "enforced"
+    );
+  },
+  withStatus(status) {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === status);
+  },
+  sdkVersion: SDK_VERSION2,
+  bundledIn: BUNDLED_IN,
+  /**
+   * Resolve a failing test back to the contract it exercises.
+   * Used by test-framework hooks to find the contract id of a
+   * failed contract test so `reportContractFailure(...)` can stamp
+   * the right `contract_id` on the emitted event.
+   */
+  findByTestName(name) {
+    return BUNDLED_CONTRACTS.find(
+      (c) => c.testRef.some((ref) => ref.name === name)
+    );
   }
-  return v;
-}
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CROSSDECK_API_VERSION,
   CROSSDECK_ERROR_CODES,
   CrossdeckAuthenticationError,
   CrossdeckConfigurationError,
+  CrossdeckContracts,
   CrossdeckError,
   CrossdeckInternalError,
   CrossdeckNetworkError,