@cross-deck/react-native 1.0.0 → 1.5.0

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   AsyncStorageAdapter: () => AsyncStorageAdapter,
   Crossdeck: () => Crossdeck,
   CrossdeckClient: () => CrossdeckClient,
+  CrossdeckContracts: () => CrossdeckContracts,
   CrossdeckError: () => CrossdeckError,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
   MemoryStorage: () => MemoryStorage,
@@ -100,7 +101,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.0.0";
+var SDK_VERSION = "1.4.2";
 var SDK_NAME = "@cross-deck/react-native";
 
 // src/http.ts
@@ -126,6 +127,12 @@ var HttpClient = class {
       "Crossdeck-Sdk-Version": `${SDK_NAME}@${this.config.sdkVersion}`,
       Accept: "application/json"
     };
+    if (this.config.bundleId) {
+      headers["X-Crossdeck-Bundle-Id"] = this.config.bundleId;
+    }
+    if (this.config.packageName) {
+      headers["X-Crossdeck-Package-Name"] = this.config.packageName;
+    }
     if (options.idempotencyKey) {
       headers["Idempotency-Key"] = options.idempotencyKey;
     }
@@ -334,34 +341,230 @@ function randomChars(count) {
   return out.join("");
 }
 
+// src/hash.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function utf8Bytes(input) {
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(input);
+  }
+  const out = [];
+  for (let i = 0; i < input.length; i++) {
+    let codePoint = input.charCodeAt(i);
+    if (codePoint >= 55296 && codePoint <= 56319 && i + 1 < input.length) {
+      const next = input.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        codePoint = 65536 + (codePoint - 55296 << 10) + (next - 56320);
+        i++;
+      }
+    }
+    if (codePoint < 128) {
+      out.push(codePoint);
+    } else if (codePoint < 2048) {
+      out.push(192 | codePoint >> 6);
+      out.push(128 | codePoint & 63);
+    } else if (codePoint < 65536) {
+      out.push(224 | codePoint >> 12);
+      out.push(128 | codePoint >> 6 & 63);
+      out.push(128 | codePoint & 63);
+    } else {
+      out.push(240 | codePoint >> 18);
+      out.push(128 | codePoint >> 12 & 63);
+      out.push(128 | codePoint >> 6 & 63);
+      out.push(128 | codePoint & 63);
+    }
+  }
+  return new Uint8Array(out);
+}
+function sha256Hex(input) {
+  const bytes = utf8Bytes(input);
+  const bitLength = bytes.length * 8;
+  const blockCount = Math.floor((bytes.length + 9 + 63) / 64);
+  const padded = new Uint8Array(blockCount * 64);
+  padded.set(bytes);
+  padded[bytes.length] = 128;
+  const high = Math.floor(bitLength / 4294967296);
+  const low = bitLength >>> 0;
+  const lenOffset = padded.length - 8;
+  padded[lenOffset + 0] = high >>> 24 & 255;
+  padded[lenOffset + 1] = high >>> 16 & 255;
+  padded[lenOffset + 2] = high >>> 8 & 255;
+  padded[lenOffset + 3] = high & 255;
+  padded[lenOffset + 4] = low >>> 24 & 255;
+  padded[lenOffset + 5] = low >>> 16 & 255;
+  padded[lenOffset + 6] = low >>> 8 & 255;
+  padded[lenOffset + 7] = low & 255;
+  const H = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const W = new Uint32Array(64);
+  for (let block = 0; block < blockCount; block++) {
+    const offset = block * 64;
+    for (let t = 0; t < 16; t++) {
+      W[t] = (padded[offset + t * 4] << 24 | padded[offset + t * 4 + 1] << 16 | padded[offset + t * 4 + 2] << 8 | padded[offset + t * 4 + 3]) >>> 0;
+    }
+    for (let t = 16; t < 64; t++) {
+      const w15 = W[t - 15];
+      const w2 = W[t - 2];
+      const s0 = (w15 >>> 7 | w15 << 25) ^ (w15 >>> 18 | w15 << 14) ^ w15 >>> 3;
+      const s1 = (w2 >>> 17 | w2 << 15) ^ (w2 >>> 19 | w2 << 13) ^ w2 >>> 10;
+      W[t] = W[t - 16] + s0 + W[t - 7] + s1 >>> 0;
+    }
+    let a = H[0], b = H[1], c = H[2], d = H[3];
+    let e = H[4], f = H[5], g = H[6], h = H[7];
+    for (let t = 0; t < 64; t++) {
+      const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + S1 + ch + K[t] + W[t] >>> 0;
+      const S0 = (a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    H[0] = H[0] + a >>> 0;
+    H[1] = H[1] + b >>> 0;
+    H[2] = H[2] + c >>> 0;
+    H[3] = H[3] + d >>> 0;
+    H[4] = H[4] + e >>> 0;
+    H[5] = H[5] + f >>> 0;
+    H[6] = H[6] + g >>> 0;
+    H[7] = H[7] + h >>> 0;
+  }
+  let hex = "";
+  for (let i = 0; i < 8; i++) {
+    hex += H[i].toString(16).padStart(8, "0");
+  }
+  return hex;
+}
+
 // src/entitlement-cache.ts
 var DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1e3;
-var EntitlementCache = class {
+var ANON_SUFFIX = "_anon";
+var INDEX_SUFFIX = "_index";
+var EntitlementCache = class _EntitlementCache {
   /**
-   * @param storage      Device storage adapter.
-   * @param storageKey   Full key the persisted blob lives under.
-   * @param staleAfterMs Age past which last-known-good is flagged stale
-   *                     even without a failed refresh. Default 24h.
+   * @param storage          Device storage adapter.
+   * @param storageKeyPrefix Prefix used to derive per-user storage keys
+   *                         (`<prefix>:<sha256(userId)>`). Default
+   *                         `crossdeck:entitlements`. The trailing
+   *                         user suffix is filled at identify() /
+   *                         reset() time — see [[setUserKey]].
+   * @param staleAfterMs     Age past which last-known-good is flagged stale
+   *                         even without a failed refresh. Default 24h.
    */
-  constructor(storage, storageKey = "crossdeck:entitlements", staleAfterMs = DEFAULT_STALE_AFTER_MS) {
+  constructor(storage, storageKeyPrefix = "crossdeck:entitlements", staleAfterMs = DEFAULT_STALE_AFTER_MS) {
     this.all = [];
     this.lastUpdated = 0;
     this.lastRefreshFailedAt = 0;
     this.listeners = /* @__PURE__ */ new Set();
     this.listenerErrorCount = 0;
-    this.hydrated = false;
+    this.hydratedSuffixes = /* @__PURE__ */ new Set();
+    this.currentSuffix = ANON_SUFFIX;
     this.storage = storage;
-    this.storageKey = storageKey;
+    this.storageKeyPrefix = storageKeyPrefix;
     this.staleAfterMs = staleAfterMs;
   }
+  /** The full storage key the current-user blob is persisted under. */
+  get storageKey() {
+    return `${this.storageKeyPrefix}:${this.currentSuffix}`;
+  }
+  /** Key of the index blob — a JSON array of every suffix we've
+   * written. Used by clearAll() to scope a logout-wipe. */
+  get indexKey() {
+    return `${this.storageKeyPrefix}:${INDEX_SUFFIX}`;
+  }
+  /** Derive a stable suffix for a developerUserId via SHA-256. */
+  static suffixForUserId(userId) {
+    if (userId == null || userId === "") return ANON_SUFFIX;
+    return sha256Hex(userId);
+  }
   /**
-   * Load last-known-good from device storage. Run once during
-   * `Crossdeck.init()` so `isEntitled()` answers correctly from the
-   * first call. Any corrupt / unparseable blob degrades silently to
-   * an empty cache — boot must never throw.
+   * Load last-known-good from device storage for the CURRENT
+   * suffix. Run during `Crossdeck.init()` (anonymous slot) and
+   * after every [[setUserKey]] switch. Idempotent per suffix —
+   * a repeat call for the same suffix is a no-op.
    */
   async hydrate() {
-    if (this.hydrated) return;
+    const suffix = this.currentSuffix;
+    if (this.hydratedSuffixes.has(suffix)) return;
     try {
       const raw = await this.storage.getItem(this.storageKey);
       if (raw) {
@@ -373,7 +576,33 @@ var EntitlementCache = class {
       }
     } catch {
     }
-    this.hydrated = true;
+    this.hydratedSuffixes.add(suffix);
+  }
+  /**
+   * Switch the cache to a different user's storage slot. Bank-grade
+   * three-layer isolation (v1.4.0 Phase 1.3):
+   *   (a) Physical key separation — `<prefix>:<sha256(userId)>` so
+   *       a user-switch can't physically read prior user's data
+   *       even if the in-memory clear was skipped.
+   *   (b) Unconditional in-memory clear — invoked whenever the
+   *       active suffix changes, even on same-id re-identify.
+   *   (c) Re-hydrate from the new slot — a returning user observes
+   *       their last-known-good cache from storage immediately.
+   *
+   * Caller (identify() / reset()) MUST `await` this BEFORE the
+   * next `setFromList()` so the write lands under the right key.
+   */
+  async setUserKey(userId) {
+    const nextSuffix = _EntitlementCache.suffixForUserId(userId);
+    this.all = [];
+    this.lastUpdated = 0;
+    this.lastRefreshFailedAt = 0;
+    if (nextSuffix !== this.currentSuffix) {
+      this.currentSuffix = nextSuffix;
+      this.hydratedSuffixes.delete(nextSuffix);
+    }
+    await this.hydrate();
+    this.notify();
   }
   /**
    * Sync read — true iff the entitlement is currently granting
@@ -443,19 +672,51 @@ var EntitlementCache = class {
     this.lastUpdated = Date.now();
     this.lastRefreshFailedAt = 0;
     this.persist();
+    void this.recordSuffixInIndex(this.currentSuffix);
     this.notify();
   }
   /**
-   * Wipe — used on `reset()` (logout) and on an identity switch.
-   * Clears BOTH memory and durable storage so a prior user's
-   * entitlements can never leak to the next person on this device.
+   * Wipe the CURRENT user's slot. Used internally when a single
+   * user's cache needs to be invalidated. The full-logout path is
+   * [[clearAll]].
    */
   clear() {
     this.all = [];
     this.lastUpdated = 0;
     this.lastRefreshFailedAt = 0;
+    const suffix = this.currentSuffix;
     void this.storage.removeItem(this.storageKey).catch(() => {
     });
+    void this.removeSuffixFromIndex(suffix);
+    this.notify();
+  }
+  /**
+   * Logout-grade wipe — bank-grade contract: removes EVERY per-user
+   * entitlement slot the SDK has ever written on this device, then
+   * clears the index. Used by `Crossdeck.reset()` so a logout on a
+   * shared device can never leave another user's entitlements
+   * readable (layer (c) of the v1.4.0 isolation fix).
+   *
+   * Async to honour the AsyncStorage contract; safe to `void` if
+   * the caller doesn't need to await teardown completion.
+   */
+  async clearAll() {
+    this.all = [];
+    this.lastUpdated = 0;
+    this.lastRefreshFailedAt = 0;
+    this.currentSuffix = ANON_SUFFIX;
+    this.hydratedSuffixes.clear();
+    const suffixes = await this.readIndex();
+    await Promise.all(
+      suffixes.map(
+        (s) => this.storage.removeItem(`${this.storageKeyPrefix}:${s}`).catch(() => {
+        })
+      )
+    );
+    await this.storage.removeItem(`${this.storageKeyPrefix}:${ANON_SUFFIX}`).catch(() => {
+    });
+    await this.storage.removeItem(this.indexKey).catch(() => {
+    });
     this.notify();
   }
   /**
@@ -488,6 +749,41 @@ var EntitlementCache = class {
     void this.storage.setItem(this.storageKey, blob).catch(() => {
     });
   }
+  /** Read the index of all per-user suffixes the SDK has written. */
+  async readIndex() {
+    try {
+      const raw = await this.storage.getItem(this.indexKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((x) => typeof x === "string");
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+  /** Add a suffix to the persisted index. Idempotent. */
+  async recordSuffixInIndex(suffix) {
+    const existing = await this.readIndex();
+    if (existing.includes(suffix)) return;
+    existing.push(suffix);
+    await this.storage.setItem(this.indexKey, JSON.stringify(existing)).catch(() => {
+    });
+  }
+  /** Remove a suffix from the persisted index. No-op if absent. */
+  async removeSuffixFromIndex(suffix) {
+    const existing = await this.readIndex();
+    const next = existing.filter((s) => s !== suffix);
+    if (next.length === existing.length) return;
+    if (next.length === 0) {
+      await this.storage.removeItem(this.indexKey).catch(() => {
+      });
+    } else {
+      await this.storage.setItem(this.indexKey, JSON.stringify(next)).catch(() => {
+      });
+    }
+  }
   notify() {
     if (this.listeners.size === 0) return;
     const snapshot = this.all.slice();
@@ -502,6 +798,34 @@ var EntitlementCache = class {
   }
 };
 
+// src/idempotency-key.ts
+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 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/retry-policy.ts
 var DEFAULT_BASE = 1e3;
 var DEFAULT_MAX = 6e4;
@@ -1869,6 +2193,14 @@ var CrossdeckClient = class {
         this.state.errors?.uninstall();
       } catch {
       }
+      try {
+        this.state.appStateSubscription?.remove();
+      } catch {
+      }
+      try {
+        void this.state.events.flush();
+      } catch {
+      }
     }
     if (!options.publicKey || !options.publicKey.startsWith("cd_pub_")) {
       throw new CrossdeckError({
@@ -1910,11 +2242,20 @@ var CrossdeckClient = class {
       storagePrefix: options.storagePrefix ?? "crossdeck:",
       autoHeartbeat: options.autoHeartbeat ?? true,
       eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
-      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
+      // v1.4.0 Phase 3.3 — flush interval default parity at 2000ms
+      // across every SDK. Per-instance override stays.
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 2e3,
       sdkVersion: options.sdkVersion ?? SDK_VERSION,
       appVersion: options.appVersion ?? null,
       platform: options.platform ?? detectPlatform(),
-      timeoutMs: options.timeoutMs ?? 15e3
+      timeoutMs: options.timeoutMs ?? 15e3,
+      // Per-platform identity claims for the bank-grade identity
+      // lock. Empty string means "not supplied" — the HTTP layer
+      // skips the header in that case and the backend will reject
+      // with bundle_id_not_allowed / package_name_not_allowed at
+      // first request if the project requires the lock.
+      bundleId: options.bundleId ?? "",
+      packageName: options.packageName ?? ""
     };
     const debug = new ConsoleDebugLogger();
     debug.enabled = options.debug === true;
@@ -1922,7 +2263,12 @@ var CrossdeckClient = class {
       publicKey: opts.publicKey,
       baseUrl: opts.baseUrl,
       sdkVersion: opts.sdkVersion,
-      timeoutMs: opts.timeoutMs
+      timeoutMs: opts.timeoutMs,
+      // Per-platform identity claims — sent as X-Crossdeck-Bundle-Id
+      // / X-Crossdeck-Package-Name. Backend enforces these against
+      // the app key's stored identity (bank-grade fail-closed).
+      bundleId: options.bundleId,
+      packageName: options.packageName
     });
     const effectiveStorage = persistIdentity ? storage : new MemoryStorage();
     const identity = new IdentityStore(effectiveStorage, opts.storagePrefix);
@@ -1987,12 +2333,32 @@ var CrossdeckClient = class {
       options: opts,
       debug,
       developerUserId: null,
+      sessionId: null,
       lastServerTime: null,
       lastClientTime: null,
       started: false,
       hydrated: false,
-      ready: Promise.resolve()
+      ready: Promise.resolve(),
+      appStateSubscription: null
     };
+    try {
+      const RN = require("react-native");
+      const AppState = RN?.AppState;
+      if (AppState && typeof AppState.addEventListener === "function") {
+        const sub = AppState.addEventListener("change", (next) => {
+          if (next === "background" || next === "inactive") {
+            try {
+              void this.state?.events.flush().catch(() => {
+              });
+              debug.emit("sdk.queue_persisted", "persisted on AppState background");
+            } catch {
+            }
+          }
+        });
+        this.state.appStateSubscription = sub;
+      }
+    } catch {
+    }
     const wantErrorCapture = options.errorCapture !== false;
     if (wantErrorCapture) {
       const tracker = new ErrorTracker({
@@ -2069,14 +2435,10 @@ var CrossdeckClient = class {
     };
     if (options?.email) body.email = options.email;
     if (traits) body.traits = traits;
+    await s.entitlements.setUserKey(userId);
     const result = await s.http.request("POST", "/identity/alias", {
       body
     });
-    const priorCdcust = s.identity.crossdeckCustomerId;
-    const cacheHasEntries = s.entitlements.list().length > 0;
-    if (priorCdcust && result.crossdeckCustomerId && priorCdcust !== result.crossdeckCustomerId || !priorCdcust && cacheHasEntries) {
-      s.entitlements.clear();
-    }
     s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
     s.identity.setDeveloperUserId(userId);
     s.developerUserId = userId;
@@ -2291,6 +2653,32 @@ var CrossdeckClient = class {
    * stamped. Common-case `track()` after hydration runs entirely
    * synchronously.
    */
+  /**
+   * Emit `crossdeck.contract_failed` with the canonical property
+   * shape. Same wire shape every Crossdeck SDK uses for contract
+   * verification telemetry — see `contracts/README.md`. No new
+   * endpoint, goes through the standard track() pipeline.
+   */
+  reportContractFailure(input) {
+    const props = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "react-native",
+      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("crossdeck.contract_failed", props);
+  }
   track(name, properties) {
     const s = this.requireStarted();
     if (!name) {
@@ -2300,11 +2688,14 @@ var CrossdeckClient = class {
         message: "track(name) requires a non-empty name."
       });
     }
+    const callTimeSnapshot = {
+      sessionId: s.sessionId
+    };
     if (!s.hydrated) {
-      void s.ready.then(() => this.trackPostHydration(s, name, properties));
+      void s.ready.then(() => this.trackPostHydration(s, name, properties, callTimeSnapshot));
       return;
     }
-    this.trackPostHydration(s, name, properties);
+    this.trackPostHydration(s, name, properties, callTimeSnapshot);
   }
   /**
    * The body of `track()` — everything after the synchronous
@@ -2312,7 +2703,7 @@ var CrossdeckClient = class {
    * portion until async identity hydration completes (RN-specific —
    * see `track()` jsdoc).
    */
-  trackPostHydration(s, name, properties) {
+  trackPostHydration(s, name, properties, callTimeSnapshot) {
     const isError = name.startsWith("error.");
     const consentGateOk = isError ? s.consent.errors : s.consent.analytics;
     if (!consentGateOk) {
@@ -2359,6 +2750,9 @@ var CrossdeckClient = class {
     if (Object.keys(groupIds).length > 0) {
       enriched.$groups = groupIds;
     }
+    if (callTimeSnapshot.sessionId) {
+      enriched.sessionId = callTimeSnapshot.sessionId;
+    }
     Object.assign(enriched, validation.properties);
     const finalProperties = s.scrubPii ? scrubPiiFromProperties(enriched) : enriched;
     const event = {
@@ -2409,14 +2803,24 @@ var CrossdeckClient = class {
         message: "syncPurchases (google) requires a purchaseToken string from Google Billing."
       });
     }
+    const body = { ...input, rail };
+    const idempotencyKey = deriveIdempotencyKeyForPurchase(body);
     const result = await s.http.request("POST", "/purchases/sync", {
-      // Spread input FIRST so the explicit `rail` default below wins
-      // — `{ ...input, rail }` puts the default last so an explicit
-      // `rail: undefined` from the caller doesn't override.
-      body: { ...input, rail }
+      body,
+      idempotencyKey
     });
     s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
     s.entitlements.setFromList(result.entitlements);
+    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("purchase.completed", props);
+    } catch {
+    }
     s.debug.emit(
       "sdk.purchase_evidence_sent",
       `${rail === "apple" ? "StoreKit" : "Google Billing"} purchase evidence forwarded. Waiting for backend verification.`,
@@ -2424,6 +2828,42 @@ var CrossdeckClient = class {
     );
     return result;
   }
+  /**
+   * v1.4.0 Phase 3.4 — set the active session id. RN doesn't own
+   * session lifecycle (that's the host's AppState + nav library);
+   * the host calls `setSessionId()` from its AppState change
+   * listener so every subsequent `track()` event carries the
+   * `sessionId` property — matches the web SDK's session-anchored
+   * funnel queries.
+   *
+   * ```ts
+   * import { AppState } from "react-native";
+   *
+   * let sessionId = uuid();
+   * AppState.addEventListener("change", (next) => {
+   *   if (next === "active") {
+   *     // New session if backgrounded > 30 min.
+   *     sessionId = uuid();
+   *     Crossdeck.setSessionId(sessionId);
+   *   } else if (next === "background") {
+   *     void Crossdeck.flush();
+   *   }
+   * });
+   * Crossdeck.setSessionId(sessionId);
+   * ```
+   *
+   * Pass `null` to clear (between sessions, on logout, etc).
+   */
+  setSessionId(sessionId) {
+    const s = this.requireStarted();
+    s.sessionId = sessionId ?? null;
+    if (s.debug.enabled) {
+      s.debug.emit(
+        "sdk.configured",
+        sessionId ? `Session id set to ${sessionId}; subsequent track events will carry it.` : "Session id cleared; subsequent track events will omit it."
+      );
+    }
+  }
   /** Toggle verbose diagnostic logging. */
   setDebugMode(enabled) {
     const s = this.requireStarted();
@@ -2466,7 +2906,7 @@ var CrossdeckClient = class {
       }
     }
     this.state.identity.reset();
-    this.state.entitlements.clear();
+    void this.state.entitlements.clearAll();
     this.state.events.reset();
     this.state.superProps.clear();
     this.state.breadcrumbs.clear();
@@ -2591,11 +3031,413 @@ function detectPlatform() {
     return "web";
   }
 }
+
+// src/_contracts-bundled.ts
+var BUNDLED_IN = "@cross-deck/react-native@1.5.0";
+var SDK_VERSION2 = "1.5.0";
+var BUNDLED_CONTRACTS = Object.freeze([
+  {
+    "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/react-native@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/react-native@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/react-native@1.5.0"
+  },
+  {
+    "id": "init-reentry-drains-prior-queue",
+    "pillar": "lifecycle",
+    "status": "enforced",
+    "claim": "Web + RN init() re-entry drains the prior EventQueue's pending setTimeout BEFORE replacing this.state. Pre-v1.4.0 the teardown handled autoTracker/webVitals/errors/unloadFlush but NOT events, so the prior queue's timer would fire AFTER the state swap \u2014 sending old-init events against new-init http + identity references (cross-identity leak during HMR / config swap / multi-tenant SDK shells). The teardown CANNOT call persistent.clear() \u2014 the durable queue belongs to the SDK lifetime, not the init() lifetime, and a survived crash mid-flush re-hydrates on the next init.",
+    "appliesTo": [
+      "web",
+      "react-native"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/crossdeck.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init drains the prior queue's pending timer before swapping state"
+      },
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init does NOT wipe the durable event store"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
+    "bundledIn": "@cross-deck/react-native@1.5.0"
+  },
+  {
+    "id": "per-user-cache-isolation",
+    "pillar": "entitlements",
+    "status": "enforced",
+    "claim": "Every identify(userId) switches the entitlement cache to a physically separate per-user storage slot \u2014 `crossdeck:entitlements:<sha256(userId)>` \u2014 and unconditionally wipes the in-memory snapshot. A user-switch on a shared device CANNOT cross-read a prior user's cached entitlements, even if the in-memory clear is somehow skipped, because the storage keys are physically separate. reset() wipes every per-user slot via the persisted index.",
+    "appliesTo": [
+      "web",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/entitlement-cache.ts",
+      "sdks/web/src/hash.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/entitlement-cache.ts",
+      "sdks/react-native/src/hash.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EntitlementCache.swift",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EntitlementCache.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "clearAll() removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "a second cache instance reading A's storage suffix CANNOT see B's data"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifyB_makesAEntitlementsUnreachable"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifiedWritesLandUnderPerUserSha256Key"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_clearAll_removesEveryPerUserStorageKeyPlusIndex"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identified writes land under per-user sha256 key"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identify B makes A entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "clearAll removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "a fresh cache bound to A's key CANNOT read B's blob"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
+    "bundledIn": "@cross-deck/react-native@1.5.0"
+  },
+  {
+    "id": "rn-session-id-enrichment",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "RN SDK's track() pipeline attaches a `sessionId` property to every event when the host has called `setSessionId(...)` \u2014 parity with the web SDK's session-anchored funnel queries. Pre-v1.4.0 the enrichment merged device + super + groups + caller but never carried sessionId, so cross-platform funnels on session anchors returned zero RN rows. The host owns session lifecycle (AppState + nav library); the SDK exposes setSessionId() / setSessionId(null) for the host to drive. Caller-supplied sessionId in properties still wins on conflict (matches the Phase 3.2 caller > super > device precedence chain).",
+    "appliesTo": [
+      "react-native"
+    ],
+    "codeRef": [
+      "sdks/react-native/src/crossdeck.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/react-native/tests/session-id-enrichment.test.ts",
+        "name": "track() events carry sessionId after setSessionId() is called"
+      },
+      {
+        "file": "sdks/react-native/tests/session-id-enrichment.test.ts",
+        "name": "track() events do NOT carry sessionId before setSessionId() is called"
+      },
+      {
+        "file": "sdks/react-native/tests/session-id-enrichment.test.ts",
+        "name": "setSessionId(null) clears the active session"
+      },
+      {
+        "file": "sdks/react-native/tests/session-id-enrichment.test.ts",
+        "name": "caller-supplied sessionId property overrides setSessionId() value (Phase 3.2 precedence)"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.4",
+    "bundledIn": "@cross-deck/react-native@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/react-native@1.5.0"
+  }
+]);
+
+// 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)
+    );
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AsyncStorageAdapter,
   Crossdeck,
   CrossdeckClient,
+  CrossdeckContracts,
   CrossdeckError,
   DEFAULT_BASE_URL,
   MemoryStorage,