@cross-deck/react-native 1.0.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,103 @@ 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.5.1] — 2026-05-27
+
+`crossdeck.contract_failed` is now single-fire to a dedicated
+reliability endpoint instead of the customer's `track()` pipeline.
+Independent-controller flow per Privacy Policy §6; schema-locked by
+`contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+`ContractFailureInput.extra` removed (schema-lock forbids unbounded
+fields); `ContractFailureInput.deviceClass` added.
+
+## [1.5.0] — 2026-05-26
+
+Minor — `CrossdeckContracts` + `reportContractFailure(...)` ship as a
+new public surface on every SDK simultaneously. Additive only; no
+behavioural change to existing APIs.
+
+**Added:**
+
+- **`CrossdeckContracts` namespace** — typed access to the bank-grade
+  contract registry. Methods: `all()`, `allIncludingHistorical()`,
+  `byId(id)`, `byPillar(pillar)`, `withStatus(status)`,
+  `findByTestName(name)`. Properties: `sdkVersion`, `bundledIn`
+  (e.g. `"@cross-deck/react-native@1.5.0"`).
+- **`Contract` type + `ContractPillar` / `ContractStatus` /
+  `ContractAppliesTo` unions + `ContractTestRef` + `ContractFailureInput`
+  interfaces** exported from the top-level entry. Treated as
+  binary-stable.
+- **`Crossdeck.reportContractFailure(input)` method** — fires a typed
+  `crossdeck.contract_failed` event through the standard `track()`
+  pipeline when a contract test asserts and fails. Wire properties:
+  `contract_id`, `sdk_version` (auto-stamped), `sdk_platform`
+  (auto-stamped to `"react-native"`), `failure_reason`, `run_context`
+  (`ci` | `dogfood` | `customer-app`), `run_id`, plus optional
+  `test_file` / `test_name`.
+
+**Fixed:**
+
+- Pre-hydration `track()` calls now correctly snapshot the
+  call-time `sessionId` and thread it through the deferred
+  enrichment body. Previously, two `track()` calls separated by
+  `setSessionId(...)` BEFORE hydration completed would both pick up
+  whatever `sessionId` was current at hydration resolution — silently
+  rewriting the first event with the second event's state. This
+  contract is RN-specific (Web/Node have no hydration window).
+
+**Changed:**
+
+- Contract registry source files migrated to camelCase keys
+  (`appliesTo`, `codeRef`, `testRef`, `registeredAt`,
+  `firstRegisteredIn`). The bundled `contracts.json` sidecar uses
+  the new keys; `bundledIn` is build-stamped, never in source.
+
+## [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.
@@ -144,6 +157,60 @@ Crossdeck.diagnostics();
 // }
 ```
 
+## Bank-grade contracts
+
+The SDK ships its own contracts registry — every behavioural guarantee the SDK makes (per-user cache isolation, deterministic Idempotency-Key, queue durability, etc.) lives in `contracts/**/*.json` at the monorepo root and is **bundled into every release**. The customer's lockfile pins SDK code + contracts atomically — drift between what the SDK does and what it claims is structurally impossible. See [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md) for the full architecture.
+
+### `CrossdeckContracts` — typed access to the bundled registry
+
+```ts
+import { CrossdeckContracts } from "@cross-deck/react-native";
+
+CrossdeckContracts.all();                              // enforced contracts only
+CrossdeckContracts.allIncludingHistorical();           // + proposed + retired
+CrossdeckContracts.byId("per-user-cache-isolation");
+CrossdeckContracts.byPillar("entitlements");
+CrossdeckContracts.withStatus("proposed");
+CrossdeckContracts.findByTestName("identify(B) makes A's entitlements unreachable from in-memory");
+CrossdeckContracts.sdkVersion;        // "1.5.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/react-native@1.5.0"
+```
+
+The `Contract` type is exported alongside; the binary-stability promise is documented in [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md).
+
+### `Crossdeck.reportContractFailure(input)` — surface contract test failures
+
+When a contract test asserts and fails — in your CI, a dogfood run, or a customer integration test — fire a typed `crossdeck.contract_failed` event over the **Crossdeck reliability channel**. This is one-way operational telemetry to the Crossdeck operations team (Privacy Policy §6, "Flow B"); it never enters your `track()` pipeline, never shows in your dashboard, never bills against your event quota. The wire shape is schema-locked at [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json):
+
+```ts
+Crossdeck.reportContractFailure({
+  contractId: "per-user-cache-isolation",
+  failureReason: "expected isolation across user switch, got cross-read",
+  runContext: __DEV__ ? "dogfood" : "ci",
+  runId: process.env.GITHUB_RUN_ID ?? Date.now().toString(36),
+  testRef: {
+    file: "tests/entitlement-cache-isolation.test.ts",
+    name: "identify(B) makes A's entitlements unreachable from in-memory",
+  },
+});
+```
+
+No new endpoint, no special ingest path — the event lands in the same pipeline every other `track()` call does. It surfaces immediately in the dashboard's live event feed, the breakdown chart (group by `contract_id`, `sdk_platform`), and any alert rule with `event = crossdeck.contract_failed`.
+
+Properties stamped on the wire:
+
+| Property | Source |
+|----------|--------|
+| `contract_id` | caller |
+| `sdk_version`, `sdk_platform` | auto-stamped (`@cross-deck/react-native` ships `sdk_platform: "react-native"`) |
+| `failure_reason`, `run_context`, `run_id` | caller |
+| `test_file`, `test_name` | set when `testRef` is provided |
+| `device_class` | optional, set by caller (categorical bucket — e.g. `"ios-phone"`, `"android-tablet"`) |
+
+The wire shape is schema-locked at [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json); per-SDK assertion tests gate it on every release. Free-form `extra` keys are not accepted — adding a field requires an amendment to the schema-lock contract first.
+
+For per-test-framework hooks see [`contracts/README.md` § Reporting contract failures](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md#reporting-contract-failures-back-to-crossdeck).
+
 ## Documentation
 
 - [Full SDK reference](https://cross-deck.com/docs/react-native-sdk)