@cross-deck/react-native 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+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.0.0] — 2026-05-24
+
+First public release. Built bank-grade from day one — every audit
+pattern landed during the `@cross-deck/web` + `@cross-deck/node`
+KPMG review is baked in. Three Crossdeck pillars in one SDK,
+modelled on the shipping `@cross-deck/web` API surface so a
+cross-platform team writes identical call-sites:
+
+```ts
+import { Crossdeck } from "@cross-deck/react-native";
+
+Crossdeck.init({
+  appId: "app_rn_xxx",
+  publicKey: "cd_pub_live_…",
+  environment: "production",
+});
+
+await Crossdeck.identify("user_847");
+if (Crossdeck.isEntitled("pro")) showPro();
+Crossdeck.track("paywall_shown", { variant: "v3" });
+```
+
+### Subscriptions & entitlements
+
+- **Durable last-known-good entitlement cache.** `EntitlementCache.hydrate()`
+  loads from AsyncStorage during `init()`, so `isEntitled()` is correct
+  from the first call after `init()` resolves — no cold-start window
+  where a returning Pro customer reads as free.
+- **An outage can never fail a paying customer down to free.** A
+  failed `getEntitlements()` never clears the cache; only a successful
+  fetch replaces it. Each entitlement is still honoured against its
+  own `validUntil`, so a timed-out trial still ends.
+- **`onEntitlementsChange(listener)`** subscriber API for reactive UI
+  binding — fires after `getEntitlements()` / `syncPurchases()` /
+  `reset()`. Listener errors are swallowed (a buggy consumer can't
+  crash the SDK or other listeners) and counted in `diagnostics()`.
+- **`syncPurchases({ rail, signedTransactionInfo | purchaseToken })`**
+  forwards Apple StoreKit 2 or Google Billing evidence for backend
+  verification + entitlement projection.
+- **`isEntitled(key)`** + **`listEntitlements()`** are synchronous
+  reads of the in-memory cache. Subscribe via `onEntitlementsChange`
+  for reactive bindings.
+
+### Analytics
+
+- **Bank-grade event queue.** `pendingBatch` slot keeps the in-flight
+  batch with the SAME `Idempotency-Key` across retries (Stripe
+  pattern) — backend dedupe on `(projectId, eventId)` handles the
+  belt-and-suspenders. Persisted blob always carries
+  `[...pendingBatch, ...buffer]` via AsyncStorage so an app crash
+  mid-flight replays the in-flight batch on the next launch.
+- **4xx hard-stop.** 400 / 401 / 403 / 404 / 422 etc. drop the batch
+  loudly: `onPermanentFailure` callback + `console.error` regardless
+  of debug mode + `dropped` counter increments. Pre-fix (web/node
+  1.2.x and earlier) every error retried forever with the same key.
+- **Exponential backoff with full jitter** on retryable failures
+  (5xx / network / 408 / 429). Honours server `Retry-After` when
+  bigger than the computed window, capped at 24h as a sanity guard.
+- **Hard buffer cap (1000 events).** Past the cap we evict the
+  OLDEST events and increment `dropped` so the developer can see the
+  loss in `diagnostics()`.
+- **Super properties** (`register` / `unregister`) and **groups**
+  (`group(type, id, traits)`) — Mixpanel pattern, attached to every
+  event automatically. Both cleared on `reset()`.
+
+### Error capture
+
+- **`ErrorUtils.setGlobalHandler`** chains in front of RN's default
+  handler (the red-box developer overlay) so uncaught errors AND
+  unhandled promise rejections are captured WITHOUT breaking the
+  dev experience. Stack frames parsed via the Hermes / JSC / V8
+  unified parser.
+- **`globalThis.fetch` wrap** catches 5xx + network failures. The
+  configured `selfHostname` (derived from `init({ baseUrl })`) is
+  excluded so a Crossdeck-side outage doesn't recurse through its
+  own fetch-wrap. Strict hostname compare (no substring matches —
+  `api.cross-deck.com.attacker.example` doesn't falsely match).
+- **Per-fingerprint rate limit** (5 per minute by default) defends
+  against runaway loops. Per-session cap (100) bounds the worst
+  case.
+- **`captureError(err)` / `captureMessage(msg)`** manual API for
+  try/catch blocks + soft signals.
+- **`setErrorBeforeSend(hook)`** with the bank-grade getter contract
+  — a hook installed AFTER `init()` fires on the next captured
+  error. Pre-fix on web/node 1.2.x the hook was captured by value
+  and silently inert if installed late.
+- **Breadcrumb buffer (50 entries)** auto-populated by every
+  `track()` call + every `fetch` request (with the self-skip
+  filter). Attached to every error report.
+
+### Privacy & compliance
+
+- **PII scrub** — defensive regex pass over every string property
+  value before flush. Email-shaped → `<email>`, card-number-shaped
+  → `<card>` (sentinel tokens aligned with the backend so dashboard
+  aggregation works across SDK-scrub and backend-scrub paths).
+  **Recursive walk**: nested plain objects + arrays-of-objects are
+  visited, so a `{user:{email:"x@y.com"}}` payload ships scrubbed.
+- **`Crossdeck.consent({...})`** — three independent dimensions
+  (analytics / marketing / errors), each defaulting to `true`
+  (granted). `consent({analytics: false})` drops every subsequent
+  `track()` silently.
+- **`Crossdeck.forget()`** — GDPR / CCPA right to be forgotten.
+  Calls `/v1/identity/forget` + wipes every local state surface.
+
+### Diagnostics
+
+- **`Crossdeck.diagnostics()`** — stable shape whether or not
+  `init()` has been called. Returns identity (anonymousId,
+  crossdeckCustomerId, developerUserId), clock skew (server vs
+  client `Date.now()` at last heartbeat), entitlement cache
+  freshness, queue stats (buffered, dropped, in-flight, last error,
+  consecutive failures, next retry).
+- **Boot heartbeat** verifies the publishable key against the
+  Crossdeck API the moment the SDK is constructed. The dashboard's
+  "Verify install" check turns green within ~200ms without the
+  caller having to add an explicit call. Disable via
+  `autoHeartbeat: false` for CI / tests.
+
+### Cross-cutting
+
+- **`SDK_VERSION` codegen'd from `package.json`** via
+  `scripts/sync-sdk-versions.mjs` — the wire `Crossdeck-Sdk-Version`
+  header can never drift from the published bundle. CI gate via
+  `--check` mode catches drift before publish.
+- **Identity continuity via AsyncStorage** (optional peer dep) with
+  graceful in-memory fallback when AsyncStorage isn't installed
+  (Storybook snapshots, vitest under node).
+- **TypeScript-first** — strict mode, `noUncheckedIndexedAccess`,
+  every public type exported.
+
+### Coverage gaps explicitly deferred
+
+- **Auto-track sessions + deep-links** (AppState lifecycle + Linking
+  API) deferred to 1.1.0. v1.0 expects the developer to wire
+  `Crossdeck.track("screen.viewed", {...})` from their nav lib's
+  listener. Adding AppState + Linking properly is its own design
+  decision (background-foreground policy, session timeout semantics,
+  cold-start vs warm-start distinction).
+- **Bundle-size budget gate** — RN apps don't have a per-byte CDN
+  cost the way web does; size discipline is a v1.1 add.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VistaApps (Pty) Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @cross-deck/react-native
+
+[![npm](https://img.shields.io/npm/v/@cross-deck/react-native.svg)](https://www.npmjs.com/package/@cross-deck/react-native)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Crossdeck's React Native SDK — **verified subscriptions, entitlements,
+error capture, and product telemetry across iOS + Android JS apps in
+one package**. Same SDK surface as [`@cross-deck/web`](https://github.com/VistaApps-za/crossdeck-web)
++ [`@cross-deck/node`](https://github.com/VistaApps-za/crossdeck-node)
+— cross-platform teams write identical call-sites.
+
+```ts
+import { Crossdeck } from "@cross-deck/react-native";
+
+Crossdeck.init({
+  appId: "app_rn_xxx",
+  publicKey: "cd_pub_live_…",
+  environment: "production",
+});
+
+await Crossdeck.identify("user_847");
+const ents = await Crossdeck.getEntitlements();
+if (Crossdeck.isEntitled("pro")) showPro();
+Crossdeck.track("paywall_shown", { variant: "v3" });
+```
+
+## Install
+
+```sh
+npm install @cross-deck/react-native @react-native-async-storage/async-storage
+```
+
+```sh
+# Expo
+npx expo install @cross-deck/react-native @react-native-async-storage/async-storage
+```
+
+`@react-native-async-storage/async-storage` is an **optional** peer
+dependency. Without it the SDK falls back to in-memory storage
+(identity + queue don't survive app restarts; events queued offline
+are lost on cold launch). Install it for production.
+
+## Three pillars in one SDK
+
+| Pillar | Surface |
+|---|---|
+| Subscriptions & entitlements | `getEntitlements()`, `isEntitled(key)`, `listEntitlements()`, `onEntitlementsChange(listener)`, `syncPurchases({rail, signedTransactionInfo, purchaseToken})` |
+| Behavioural analytics | `track(name, properties)`, `identify(userId, options)`, `register(props)`, `group(type, id, traits)`, `consent({...})` |
+| Error capture | Auto: `ErrorUtils.setGlobalHandler` + `globalThis.fetch` wrap. Manual: `captureError(err)`, `captureMessage(msg)`, `setTag`, `setContext`, `addBreadcrumb`, `setErrorBeforeSend` |
+
+## Bank-grade defaults
+
+Every Crossdeck SDK ships these patterns by default:
+
+- **Durable last-known-good entitlement cache.** A returning Pro
+  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.
+- **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)`.
+- **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.
+  No silent infinite-retry-with-growing-backlog.
+- **PII scrub default-on.** Email-shaped and card-number-shaped
+  substrings rewritten to `<email>` / `<card>` (sentinel tokens
+  match the backend's defence-in-depth scrubber). Recursive — nested
+  `{user:{email:...}}` payloads ship scrubbed.
+- **Error self-skip from baseUrl.** Requests to the SDK's own
+  Crossdeck endpoint never trigger captureHttp — otherwise a
+  Crossdeck outage would recurse forever.
+- **Boot heartbeat.** Verifies the publishable key against the
+  Crossdeck API the moment the SDK is constructed. The dashboard's
+  "Verify install" check turns green within ~200ms.
+
+## Init options
+
+| Option | Default | Notes |
+|---|---|---|
+| `appId` | — | **Required.** From the Crossdeck dashboard. |
+| `publicKey` | — | **Required.** `cd_pub_live_…` or `cd_pub_test_…`. |
+| `environment` | — | **Required.** `"production"` or `"sandbox"`. Must match key prefix. |
+| `baseUrl` | `https://api.cross-deck.com/v1` | Override for self-hosted setups. |
+| `persistIdentity` | `true` | Set false to defer AsyncStorage writes until after a consent gate. |
+| `storage` | AsyncStorage (auto-detected) | Pass a SecureStore / MMKV adapter for higher-security app shells. |
+| `storagePrefix` | `"crossdeck:"` | Key namespace inside the storage adapter. |
+| `autoHeartbeat` | `true` | Disable for CI / tests. |
+| `eventFlushBatchSize` | `20` | Flush when buffer reaches this size. |
+| `eventFlushIntervalMs` | `5000` | Idle interval before flushing a partial batch. |
+| `appVersion` | — | Your app's version (e.g. `"1.2.3"`). Auto-attached to every event as `properties.appVersion`. |
+| `platform` | auto-detected | Override the `Platform.OS` detection. |
+| `timeoutMs` | `15000` | Per-request HTTP timeout. |
+| `debug` | `false` | Verbose diagnostic logging via the §16 debug-signal vocabulary. |
+| `scrubPii` | `true` | Disable only if your pipeline does its own PII redaction downstream. |
+| `errorCapture` | `true` | Disable if you have a separate error tracker (Sentry, Bugsnag) and don't want duplicates. |
+
+## Lifecycle
+
+`init()` returns void but kicks off async hydration (identity, super-
+props, entitlement cache, persisted event queue). Every async method
+(`identify`, `track`, `flush`, `getEntitlements`, etc.) awaits the
+internal `ready` promise — callers can fire methods immediately after
+`init()` without manual sequencing.
+
+Sync methods (`isEntitled`, `getSuperProperties`, `diagnostics`)
+read in-memory state. Until `init()` has fired they return sensible
+empties.
+
+## Foreground/background lifecycle (v1.0)
+
+v1.0 ships WITHOUT auto-session tracking. Wire your nav library's
+listener into:
+
+```ts
+import { AppState } from "react-native";
+
+AppState.addEventListener("change", (state) => {
+  if (state === "background") {
+    void Crossdeck.flush();
+  }
+});
+```
+
+Auto sessions + deep-link tracking land in v1.1 as opt-in
+`autoTrack: { sessions, deepLinks }`.
+
+## Diagnostics
+
+```ts
+Crossdeck.diagnostics();
+// {
+//   started: true,
+//   anonymousId: "anon_1mqz3…",
+//   crossdeckCustomerId: "cdcust_abc",
+//   developerUserId: "user_847",
+//   sdkVersion: "1.0.0",
+//   baseUrl: "https://api.cross-deck.com/v1",
+//   platform: "ios",
+//   clock: { lastServerTime: 1779…, lastClientTime: 1779…, skewMs: 12 },
+//   entitlements: { count: 2, lastUpdated: 1779…, stale: false, listenerErrors: 0 },
+//   events: { buffered: 0, dropped: 0, inFlight: 0, lastFlushAt: 1779…, lastError: null, consecutiveFailures: 0, nextRetryAt: null }
+// }
+```
+
+## Documentation
+
+- [Full SDK reference](https://cross-deck.com/docs/react-native-sdk)
+- [Identify users](https://cross-deck.com/docs/identify-users)
+- [Track events](https://cross-deck.com/docs/track-events)
+- [Entitlements gating](https://cross-deck.com/docs/entitlements)
+- [Error capture](https://cross-deck.com/docs/errors)
+
+## License
+
+MIT © VistaApps (Pty) Ltd