@cross-deck/react-native 1.0.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to `@cross-deck/react-native` will be documented
 here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.2] — 2026-05-26
+
+Patch — wire `bundleId` + `packageName` (per-platform identity-
+lock fields declared on `CrossdeckOptions` since v1.3.0) into
+the `InternalState` opts merge. tsc accepted the missing fields
+in monorepo CI because the monorepo test workflow doesn't lint
+the RN SDK — only the Web SDK gets type-checked. The public
+crossdeck-react-native publish workflow DOES run `npm run lint`
+and aborted with TS2322. Fix: default both to empty string in
+the opts initialiser (HTTP layer skips the header when empty;
+backend rejects with bundle_id_not_allowed /
+package_name_not_allowed at first request if the project
+requires the lock — intentional fail-closed). v1.4.1 was
+tagged on crossdeck-react-native but never reached npm.
+**No SDK code changes vs v1.4.0 / v1.4.1**.
+
+## [1.4.1] — 2026-05-26
+
+Patch — add automated npm publish workflow to the public
+`crossdeck-react-native` repo so future `vX.Y.Z` tag pushes
+auto-publish to npm via OIDC Trusted Publishing (matches the
+existing `crossdeck-web` pattern). No SDK code changes vs v1.4.0.
+
+**Operator note:** npmjs.com Trusted Publisher rule must be
+configured for `crossdeck-react-native` (owner: VistaApps-za,
+workflow: publish.yml) before the OIDC publish succeeds. First
+publish after this lands will fail with an auth error if the
+rule is missing — that's the prompt to configure it.
+
+## [1.4.0] — 2026-05-26
+
+**Bank-grade reconciliation release.** Joined the v1.4.0 release line with the rest of the Crossdeck SDK suite. 6-pillar KPMG-style audit closed; every behavioural guarantee registered in the monorepo's `contracts/` directory with a CI-enforced audit job.
+
+### Added
+
+- **Per-user entitlement cache isolation.** Storage key is now `crossdeck:entitlements:<sha256(userId)>` — a user-switch on a shared device cannot physically read prior user's cached entitlements even if the in-memory clear is somehow skipped. `reset()` wipes EVERY per-user slot via the persisted index. New pure-JS SHA-256 helper.
+- **Deterministic `Idempotency-Key` on `syncPurchases()`** — same JWS/purchaseToken → same key. Cross-SDK parity oracle CI-pinned.
+- **`PurchaseResult.idempotent_replay?: boolean`** — true when the backend replayed a cached response.
+- **`purchase.completed` event on every successful `syncPurchases()`** — funnel parity with native auto-track.
+- **`setSessionId(sessionId: string | null)`** — host-driven session lifecycle. Call from your AppState change listener so every `track()` event carries the `sessionId` property — funnel parity with the web SDK.
+
+### Changed
+
+- **`init()` re-entry now drains the prior `EventQueue`'s pending timer** before swapping `this.state`. Pre-1.4.0 the timer fired AFTER the state swap, sending old-init events under new-init identity.
+- **Default event-queue flush interval is now 2000ms** (was 5000ms) — cross-SDK parity.
+
 ## [1.0.0] — 2026-05-24
 
 First public release. Built bank-grade from day one — every audit

package/README.md

@@ -56,10 +56,23 @@ Every Crossdeck SDK ships these patterns by default:
   customer reads as Pro on the FIRST `isEntitled()` after `init()`,
   even on a cold launch with no network. A Crossdeck outage can
   never fail a paying customer down to free.
+- **Per-user cache isolation (v1.4.0).** Every `identify(userId)`
+  switches the entitlement cache to a per-user AsyncStorage slot
+  (`crossdeck:entitlements:<sha256(userId)>`) and unconditionally
+  wipes the in-memory snapshot. A user-switch on a shared device
+  CANNOT cross-read a prior user's cache, even if the in-memory
+  clear is somehow skipped — the storage keys are physically
+  separate. `reset()` then wipes every per-user slot on the device
+  (logout-grade).
 - **Queue durability + Stripe-style Idempotency-Key reuse.** Events
   spliced for a flush persist to AsyncStorage with the in-flight
   batch attached, so an app crash mid-flight replays the batch on
   the next launch. Backend dedupes on `(projectId, eventId)`.
+- **Deterministic Idempotency-Key on `syncPurchases` (v1.4.0).**
+  Same signed transaction → same key → backend short-circuits
+  with `idempotent_replay: true` on retry. A network blip or app
+  crash mid-flight that re-fires the same purchase never
+  double-processes.
 - **4xx hard-stop.** Permanent failures (401 key revoked, 400/422
   schema, 403 permission, 404 endpoint) drop the batch + fire
   `onPermanentFailure` + `console.error` regardless of debug mode.

package/dist/contracts.json

@@ -0,0 +1,371 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "generatedAt": "2026-05-26T13:09:42.134Z",
+  "sdk": "@cross-deck/react-native",
+  "sdkVersion": "1.5.0",
+  "bundledIn": "@cross-deck/react-native@1.5.0",
+  "count": 7,
+  "contracts": [
+    {
+      "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 → 400, authentication_error → 401, permission_error → 403, rate_limit_error → 429, internal_error → 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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 — 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() — 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 — 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 — `crossdeck:entitlements:<sha256(userId)>` — 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 — 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(...)` — 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 — 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 — 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 — phase 3.5",
+      "bundledIn": "@cross-deck/react-native@1.5.0"
+    }
+  ]
+}