@cross-deck/web 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `@cross-deck/web` 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).
+
+## [0.4.0] — 2026-05-09
+
+Reactive entitlements. Pre-0.4.0, calling `Crossdeck.isEntitled("pro")` directly inside a React render path showed the empty-cache result forever — React had no way to know the cache had populated asynchronously after `init()`. This release closes that gap with a first-class subscribe API on the SDK and a React subpackage that uses it.
+
+### Added
+
+- **`Crossdeck.onEntitlementsChange(listener)`** — synchronous subscribe API. Returns an idempotent unsubscribe function. Listeners fire AFTER each cache mutation (`getEntitlements`, `syncPurchases`, `reset`). Listener errors are swallowed. NOT fired on subscribe — read state inline if you need the initial value. See `sdks/SDK_TRUTH.md` for the full contract.
+- **`@cross-deck/web/react` subpath export** — first-class React hooks built on top of the subscribe API:
+    - `useEntitlement(key): boolean` — re-renders the component the moment the cache mutates so a JSX snippet like `useEntitlement("pro") && <ProBadge />` actually works.
+    - `useEntitlements(): readonly string[]` — reactive list of all active entitlement keys.
+  - SSR-safe: hook returns `false` / `[]` on the server and hydrates correctly on the client. Pre-init returns the empty default until `Crossdeck.init()` runs and a cache mutation lands.
+- **`EntitlementCache.subscribe(listener)`** — internal listener API on the cache itself. Powers `onEntitlementsChange`. Iterates over a snapshot of the listener set so listeners that unsubscribe themselves during dispatch don't break the iteration.
+- **Tests** — 7 new cases covering listener semantics: fires on `setFromList`, fires on `clear`, NOT fired on subscribe, idempotent unsubscribe, listener errors are non-fatal, self-unsubscribe-during-dispatch is safe.
+
+### Why this exists
+
+Without a subscribe API, every framework binding (React, SwiftUI, Compose, Vue, Solid) had to invent its own re-render trigger by polling or hooking into private SDK internals. The cache is the only place that knows precisely when `isEntitled()` would change its answer; making it the source of the notification is the correct contract. iOS and Android SDKs MUST adopt the same pattern internally before 1.0 and MUST expose framework bindings (`@Observable` / SwiftUI for iOS, `StateFlow<Boolean>` / Compose for Android) that mirror the React hook's semantics. See the SDK NorthStar Addendum §11.4.
+
+### Build
+
+- `tsup` now emits two entry points (`dist/index.{cjs,mjs}` and `dist/react.{cjs,mjs}`) with a custom `outExtension` matching the `package.json` exports map.
+- React is now an optional peer dependency (`react >=18`).
+
+### Compatibility
+
+Source-compatible with 0.3.0. No breaking changes — `onEntitlementsChange` and the React hooks are purely additive.
+
+## [0.3.0] — 2026-05-08
+
+This release reconciles the web SDK with the Crossdeck SDK NorthStar Addendum (§4 Shared Contract, §11.1 Web SDK pattern, §13.1 wire envelope, §15 sensitive properties, §16 debug signal vocabulary). The public surface now matches what the iOS, Android, and Node SDKs will expose — `init`, `flush`, `syncPurchases`, `setDebugMode`.
+
+### Added
+
+- **`Crossdeck.init({ appId, publicKey, environment })`** — canonical lifecycle method per NorthStar §4. The trio is required and validated up-front: a publishable-key prefix that disagrees with the declared `environment` throws `CrossdeckError({ code: "environment_mismatch" })` at boot, so a typo can't silently route prod data into sandbox dashboards.
+- **`Crossdeck.flush()`** — alias of the old `flushEvents()`, matching the standardised name.
+- **`Crossdeck.syncPurchases(input)`** — replaces `purchaseApple`. Posts to `/v1/purchases/sync` and accepts an optional `rail` field for future Stripe/Google support.
+- **`Crossdeck.setDebugMode(enabled)`** + `debug` init option — toggle the §16 debug signal vocabulary (`sdk.configured`, `sdk.first_event_sent`, `sdk.no_identity`, `sdk.purchase_evidence_sent`, `sdk.environment_mismatch`, `sdk.sensitive_property_warning`).
+- **Sensitive-property warnings** — when debug mode is on, `track()` warns once per call if any property key matches `email|password|token|secret|card|phone` (NorthStar §15). The event is still sent unmodified; the warning surfaces accidental PII in the dashboard onboarding feed.
+- **NorthStar §13.1 wire envelope** — every `/v1/events` POST now includes `appId`, `environment`, and `sdk: { name, version }` at the batch level. The backend validates these against the API-key-resolved app and rejects mismatches with `permission_error / env_mismatch`.
+
+### Changed
+
+- `Crossdeck.start()` is now a deprecated alias of `init()` and emits a `console.warn` once per call. The signature is unchanged, but the new `appId` and `environment` options are still required even when calling `start`.
+- `Crossdeck.purchaseApple()` is now a deprecated alias of `syncPurchases({ rail: "apple", ... })`. The new method posts to `/v1/purchases/sync`; the legacy `/v1/purchases` route is kept on the backend for v0.2.x callers.
+- The `not_started` configuration error code is now `not_initialized` to match the rename.
+
+### Removed
+
+Nothing. v0.3.0 is fully source-compatible with v0.2.x callers — the legacy method names log a deprecation but continue to work. Plan to drop them in v0.5.0.
+
+## [0.2.0] — 2026-05-06
+
+- Added auto-tracking: sessions, page views, and device-info enrichment are on by default in browsers. See `autoTrack` config to disable individually or wholesale.
+- Stable `Diagnostics` shape regardless of whether `start()` has been called — pre-start values are sensible empties.
+
+## [0.1.0] — 2026-05-05
+
+Initial public release.

package/README.md

@@ -11,24 +11,66 @@ npm install @cross-deck/web
 ```ts
 import { Crossdeck } from "@cross-deck/web";
 
-// 1. Boot once at app start
-Crossdeck.start({ publicKey: "cd_pub_live_…" });
+// 1. Boot once at app start. Synchronous and idempotent.
+Crossdeck.init({
+  appId: "app_web_xxx",         // from the Crossdeck dashboard
+  publicKey: "cd_pub_live_…",   // publishable key, safe in client code
+  environment: "production",    // "production" or "sandbox"
+});
+
+// 2. Telemetry — fire-and-forget, batched in the background.
+Crossdeck.track("paywall_viewed", { variant: "v3" });
+
+// 3. Auth + entitlements happen inside an async boot function (or a
+//    React useEffect, or any other async context). Top-level await is
+//    not portable across all bundlers.
+async function bootCrossdeck() {
+  // Wire identify() to YOUR auth state — never hardcode a placeholder.
+  await Crossdeck.identify(currentUser.id);
+  await Crossdeck.getEntitlements();   // warm the local cache
+
+  // 4. Sync access checks (microsecond reads from cache).
+  if (Crossdeck.isEntitled("pro")) {
+    showProFeatures();
+  }
+}
+```
 
-// 2. After the user logs in, link the device to your user ID
-await Crossdeck.identify("user_847");
+### React quick start
 
-// 3. Read entitlements (warms the local cache)
-await Crossdeck.getEntitlements();
+For React apps, install Crossdeck once at the root and use the
+`useEntitlement` hook from `@cross-deck/web/react` so components
+re-render when entitlements arrive:
 
-// 4. Sync access checks (microsecond reads from cache)
-if (Crossdeck.isEntitled("pro")) {
-  showProFeatures();
+```tsx
+"use client"
+import { useEffect } from "react";
+import { Crossdeck } from "@cross-deck/web";
+import { useEntitlement } from "@cross-deck/web/react";
+
+export function CrossdeckProvider({ children }) {
+  useEffect(() => {
+    Crossdeck.init({
+      appId: "app_web_xxx",
+      publicKey: "cd_pub_live_…",
+      environment: "production",
+    });
+    Crossdeck.getEntitlements();   // warm the cache (fire-and-forget)
+  }, []);
+  return children;
 }
 
-// 5. Telemetry — fire-and-forget, batched in the background
-Crossdeck.track("paywall_viewed", { variant: "v3" });
+export function ProBadge() {
+  const isPro = useEntitlement("pro");
+  return isPro ? <span className="badge">Pro</span> : null;
+}
 ```
 
+`useEntitlement` subscribes to the SDK's reactive cache via
+`Crossdeck.onEntitlementsChange()`, so every component using the hook
+re-renders the moment entitlements change. SSR-safe: returns `false`
+on the server and hydrates correctly on the client.
+
 That's the full happy path.
 
 ## What it does
@@ -37,7 +79,7 @@ That's the full happy path.
 - **One identity for every device + user.** Pre-login events get an `anonymousId`. After login, `identify()` links them to your user ID through Crossdeck's identity graph. The SDK persists both so subsequent app launches resume where you left off.
 - **Synchronous entitlement reads.** `getEntitlements()` populates a local cache. `isEntitled("pro")` is a Set lookup — no network call, no waiting.
 - **Batched telemetry.** `track()` queues events in memory; the SDK flushes every 5 seconds (configurable) or when the buffer hits 20 events. Network failures re-queue the batch — events aren't lost on a flaky connection.
-- **Boot heartbeat.** On `start()` the SDK pings `/v1/sdk/heartbeat` so the dashboard's Apps page can show you "last seen" per install. Disable with `autoHeartbeat: false`.
+- **Boot heartbeat.** On `init()` the SDK pings `/v1/sdk/heartbeat` so the dashboard's Apps page can show you "last seen" per install. Disable with `autoHeartbeat: false`.
 - **Stripe-style errors.** Every async method throws `CrossdeckError` with `type`, `code`, `requestId`, and `status` — same shape as Stripe's SDKs, so generic error handlers transfer.
 
 ## Auto-tracked events
@@ -67,7 +109,7 @@ Every event's `properties` is enriched with whatever the SDK can detect:
   viewportWidth: 1440,
   viewportHeight: 900,
   devicePixelRatio: 2,
-  appVersion: "1.2.3",   // only when you set Crossdeck.start({ appVersion })
+  appVersion: "1.2.3",   // only when you set Crossdeck.init({ appVersion })
 }
 ```
 
@@ -75,13 +117,15 @@ No fingerprinting, no IP collection on the event document, no canvas hashing. Pr
 
 ## API
 
-### `Crossdeck.start(options)`
+### `Crossdeck.init(options)`
 
-Boot the client. Idempotent — calling twice with the same options is fine.
+Boot the client. Idempotent — calling twice with the same options is fine. (`Crossdeck.start()` is kept as a deprecated alias for v0.2.x callers.)
 
 ```ts
-Crossdeck.start({
+Crossdeck.init({
+  appId: "app_web_xxx",               // required — from the dashboard
   publicKey: "cd_pub_live_…",         // required
+  environment: "production",          // required — "production" | "sandbox"
   baseUrl: "https://api.cross-deck.com/v1",  // override for self-host or emulator
   appVersion: "1.2.3",                // attached to every event as properties.appVersion
   autoTrack: true,                    // default — sessions, page views, device info
@@ -90,9 +134,12 @@ Crossdeck.start({
   eventFlushBatchSize: 20,            // default
   eventFlushIntervalMs: 5_000,        // default
   storage: customStorage,             // override the persistence adapter
+  debug: false,                       // verbose §16 debug signals when true
 });
 ```
 
+Crossdeck checks the key prefix matches `environment`: `cd_pub_test_…` must declare `"sandbox"`, `cd_pub_live_…` must declare `"production"`. Mismatches throw `CrossdeckError({ code: "environment_mismatch" })` at init time so a typo can't silently route prod telemetry into sandbox dashboards.
+
 The publishable key is safe to ship in client code. Crossdeck enforces origin allowlists (web), bundle-ID binding (mobile), and rate limits at the edge — see [docs/api-keys](https://cross-deck.com/docs/api-keys/) for the full security model.
 
 ### `await Crossdeck.identify(userId, options?)`
@@ -129,24 +176,26 @@ Synchronous read from the local cache. Returns `false` until you've called `getE
 
 ### `Crossdeck.track(name, properties?)`
 
-Queue a telemetry event. Returns immediately. Events flush in batches; force a flush with `flushEvents()`:
+Queue a telemetry event. Returns immediately. Events flush in batches; force a flush with `flush()`:
 
 ```ts
 Crossdeck.track("checkout_started", { product: "annual_pro" });
 // …later, e.g. before page unload:
 window.addEventListener("beforeunload", () => {
-  void Crossdeck.flushEvents();
+  void Crossdeck.flush();
 });
 ```
 
 Event names match `[A-Za-z0-9_.\-:]+`, max 128 chars. Properties are JSON-serialisable, max 8 KB per event after JSON encoding.
 
-### `await Crossdeck.purchaseApple(input)`
+In `debug: true` mode the SDK warns (one signal per call) when property keys look like PII — `email`, `password`, `token`, `secret`, `card`, `phone`. Crossdeck never strips fields automatically; the warning is so accidental leaks surface during development, not in prod logs.
 
-Forward a StoreKit 2 transaction directly to Crossdeck for verification — closes the purchase-to-entitled latency from seconds to milliseconds (faster than waiting for the App Store webhook).
+### `await Crossdeck.syncPurchases(input)`
+
+Forward purchase evidence (Apple StoreKit 2) directly to Crossdeck for verification — closes the purchase-to-entitled latency from seconds to milliseconds (faster than waiting for the App Store webhook). (`purchaseApple()` is kept as a deprecated alias.)
 
 ```ts
-await Crossdeck.purchaseApple({
+await Crossdeck.syncPurchases({
   signedTransactionInfo: transaction.jsonRepresentation,  // from StoreKit 2
   signedRenewalInfo: subscription.signedRenewalInfo,      // optional
   appAccountToken: "uuid-…",                              // optional
@@ -157,15 +206,19 @@ Stripe and Google purchases are verified via webhooks (Stripe Connect platform e
 
 ### `await Crossdeck.heartbeat()`
 
-Manually send a heartbeat. Called automatically by `start()` unless `autoHeartbeat: false`. Returns the readiness summary the dashboard uses to display SDK installation status.
+Manually send a heartbeat. Called automatically by `init()` unless `autoHeartbeat: false`. Returns the readiness summary the dashboard uses to display SDK installation status.
 
 ### `Crossdeck.reset()`
 
 Wipe persisted identity + entitlement cache + queued events. Call on logout. The next session generates a fresh `anonymousId` and starts a clean identity-graph entry.
 
-### `Crossdeck.flushEvents()`
+### `Crossdeck.flush()`
+
+Force-flush the in-memory event queue. Useful before page unload or when shutting down a script. (`flushEvents()` is kept as a deprecated alias.)
+
+### `Crossdeck.setDebugMode(enabled)`
 
-Force-flush the in-memory event queue. Useful before page unload or when shutting down a script.
+Toggle the verbose debug-signal vocabulary at runtime (NorthStar §16). When enabled, the SDK emits a fixed set of `console.info` lines tagged `[crossdeck:sdk.<signal>]` for `sdk.configured`, `sdk.first_event_sent`, `sdk.no_identity`, `sdk.purchase_evidence_sent`, `sdk.environment_mismatch`, and `sdk.sensitive_property_warning`.
 
 ### `Crossdeck.diagnostics()`
 
@@ -186,7 +239,7 @@ Diagnostic snapshot — useful for development consoles and bug reports:
 
 ## Errors
 
-Every async method can throw `CrossdeckError`. Synchronous methods throw on configuration mistakes (calling before `start()`, invalid key prefix).
+Every async method can throw `CrossdeckError`. Synchronous methods throw on configuration mistakes (calling before `init()`, invalid key prefix, env mismatch).
 
 ```ts
 import { CrossdeckError } from "@cross-deck/web";
@@ -220,9 +273,11 @@ The SDK works the same way in Node 18+:
 ```ts
 import { Crossdeck, MemoryStorage } from "@cross-deck/web";
 
-Crossdeck.start({
+Crossdeck.init({
+  appId: process.env.CROSSDECK_APP_ID!,
   publicKey: process.env.CROSSDECK_PUBLIC_KEY!,
-  storage: new MemoryStorage(),  // session-only, no localStorage
+  environment: "sandbox",         // or "production"
+  storage: new MemoryStorage(),   // session-only, no localStorage
   autoHeartbeat: false,           // skip the boot ping in scripts
 });
 ```