@cross-deck/web 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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.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

@@ -12,7 +12,11 @@ npm install @cross-deck/web
 import { Crossdeck } from "@cross-deck/web";
 
 // 1. Boot once at app start
-Crossdeck.start({ publicKey: "cd_pub_live_…" });
+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. After the user logs in, link the device to your user ID
 await Crossdeck.identify("user_847");
@@ -37,7 +41,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
@@ -75,13 +79,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 +96,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 +138,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.
+
+### `await Crossdeck.syncPurchases(input)`
 
-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).
+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 +168,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 +201,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 +235,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
 });
 ```

package/dist/index.d.mts

@@ -53,12 +53,36 @@ interface HeartbeatResponse {
     serverTime: number;
 }
 /**
- * Configuration for Crossdeck.start. Most fields have sensible defaults
- * — only `publicKey` is mandatory.
+ * Configuration for Crossdeck.init. Three fields are mandatory —
+ * `appId`, `publicKey`, and `environment` — per NorthStar §11.1.
+ *
+ * The pair of (appId, environment) is what we put on the wire envelope
+ * (NorthStar §13.1) so the backend can correlate events against the
+ * specific app surface and refuse mismatched env declarations loudly.
  */
 interface CrossdeckOptions {
+    /**
+     * Your Crossdeck App ID (e.g. "app_web_xxx"). Required.
+     *
+     * Issued in the dashboard when you create an app. Goes on the wire
+     * envelope so the backend correlates events with the specific app
+     * surface — useful when one project has multiple apps (web + iOS +
+     * Android) sharing the same publishable key family.
+     */
+    appId: string;
     /** Your Crossdeck publishable key (cd_pub_…). Required. */
     publicKey: string;
+    /**
+     * Explicit environment declaration. Required.
+     *
+     * Must match the publishable key's prefix:
+     *   cd_pub_test_…  → "sandbox"
+     *   cd_pub_live_…  → "production"
+     *
+     * Mismatch is rejected at init time so a typo'd key can't silently
+     * route prod telemetry into sandbox dashboards.
+     */
+    environment: Environment;
     /**
      * Override the API base URL. Default is https://api.cross-deck.com/v1.
      * Useful for self-hosted setups or pointing at the local emulator
@@ -109,6 +133,12 @@ interface CrossdeckOptions {
      * Useful for slicing dashboards by build.
      */
     appVersion?: string;
+    /**
+     * Enable verbose diagnostic logging via the NorthStar §16 debug-signal
+     * vocabulary. Default: false. Equivalent to calling
+     * `Crossdeck.setDebugMode(true)` after init.
+     */
+    debug?: boolean;
 }
 /** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
 interface AutoTrackOptions {
@@ -165,7 +195,11 @@ interface Diagnostics {
  *
  *   import { Crossdeck } from "@cross-deck/web";
  *
- *   Crossdeck.start({ publicKey: "cd_pub_live_…" });
+ *   Crossdeck.init({
+ *     appId: "app_web_xxx",
+ *     publicKey: "cd_pub_live_…",
+ *     environment: "production",
+ *   });
  *
  *   await Crossdeck.identify("user_847");
  *   const ents = await Crossdeck.getEntitlements();
@@ -177,11 +211,12 @@ interface Diagnostics {
  *
  * Usage (Node):
  *
- *   import { Crossdeck } from "@cross-deck/web";
- *   import { MemoryStorage } from "@cross-deck/web";
+ *   import { Crossdeck, MemoryStorage } from "@cross-deck/web";
  *
- *   Crossdeck.start({
+ *   Crossdeck.init({
+ *     appId: "app_node_xxx",
  *     publicKey: "cd_pub_test_…",
+ *     environment: "sandbox",
  *     storage: new MemoryStorage(),  // session-only persistence
  *     autoHeartbeat: false,           // skip the boot ping in scripts
  *   });
@@ -190,9 +225,19 @@ interface Diagnostics {
 declare class CrossdeckClient {
     private state;
     /**
-     * Boot the SDK. Idempotent — calling start twice with the same options
+     * Boot the SDK. Idempotent — calling init twice with the same options
      * is a no-op; calling with different options replaces the previous
      * configuration.
+     *
+     * NorthStar §11.1: signature is `Crossdeck.init({ appId, publicKey,
+     * environment })`. The trio is validated up-front so a typo'd key or a
+     * mismatched env fails fast at boot rather than at first event-flush.
+     */
+    init(options: CrossdeckOptions): void;
+    /**
+     * @deprecated Use `init()` instead. NorthStar §4 standardised the
+     * lifecycle method name across SDKs as `init` (formerly `start` /
+     * `configure`). `start` will be removed in a future major version.
      */
     start(options: CrossdeckOptions): void;
     /**
@@ -216,17 +261,43 @@ declare class CrossdeckClient {
     /**
      * Queue a telemetry event. Returns immediately — the network round-
      * trip happens in the background. To flush before the page unloads,
-     * call flushEvents().
+     * call flush().
      */
     track(name: string, properties?: EventProperties): void;
-    /** Force-flush queued events. Useful to call from page-unload handlers. */
+    /**
+     * Force-flush queued events. Useful to call from page-unload handlers.
+     *
+     * NorthStar §4: standard method name across all Crossdeck SDKs.
+     */
+    flush(): Promise<void>;
+    /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
     flushEvents(): Promise<void>;
-    /** Forward an Apple StoreKit 2 transaction for verification + projection. */
+    /**
+     * Forward purchase evidence to the backend for verification + entitlement
+     * projection. NorthStar §4 + §13 canonical name.
+     *
+     * Today the web SDK only supports Apple StoreKit 2 forwarding (web apps
+     * that sit alongside an iOS app). Stripe doesn't need this method —
+     * Stripe webhooks deliver evidence server-side without a client round-trip.
+     */
+    syncPurchases(input: {
+        rail?: "apple";
+        signedTransactionInfo: string;
+        signedRenewalInfo?: string;
+        appAccountToken?: string;
+    }): Promise<PurchaseResult>;
+    /** @deprecated Use `syncPurchases()` instead. NorthStar §4 standardised the name. */
     purchaseApple(input: {
         signedTransactionInfo: string;
         signedRenewalInfo?: string;
         appAccountToken?: string;
     }): Promise<PurchaseResult>;
+    /**
+     * Toggle verbose diagnostic logging — NorthStar §16. When enabled, the
+     * SDK emits a fixed vocabulary of debug signals to console.info that the
+     * dashboard's onboarding checklist can also surface as live events.
+     */
+    setDebugMode(enabled: boolean): void;
     /**
      * Send the boot heartbeat. Called automatically by start() unless
      * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
@@ -328,7 +399,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

package/dist/index.d.ts

@@ -53,12 +53,36 @@ interface HeartbeatResponse {
     serverTime: number;
 }
 /**
- * Configuration for Crossdeck.start. Most fields have sensible defaults
- * — only `publicKey` is mandatory.
+ * Configuration for Crossdeck.init. Three fields are mandatory —
+ * `appId`, `publicKey`, and `environment` — per NorthStar §11.1.
+ *
+ * The pair of (appId, environment) is what we put on the wire envelope
+ * (NorthStar §13.1) so the backend can correlate events against the
+ * specific app surface and refuse mismatched env declarations loudly.
  */
 interface CrossdeckOptions {
+    /**
+     * Your Crossdeck App ID (e.g. "app_web_xxx"). Required.
+     *
+     * Issued in the dashboard when you create an app. Goes on the wire
+     * envelope so the backend correlates events with the specific app
+     * surface — useful when one project has multiple apps (web + iOS +
+     * Android) sharing the same publishable key family.
+     */
+    appId: string;
     /** Your Crossdeck publishable key (cd_pub_…). Required. */
     publicKey: string;
+    /**
+     * Explicit environment declaration. Required.
+     *
+     * Must match the publishable key's prefix:
+     *   cd_pub_test_…  → "sandbox"
+     *   cd_pub_live_…  → "production"
+     *
+     * Mismatch is rejected at init time so a typo'd key can't silently
+     * route prod telemetry into sandbox dashboards.
+     */
+    environment: Environment;
     /**
      * Override the API base URL. Default is https://api.cross-deck.com/v1.
      * Useful for self-hosted setups or pointing at the local emulator
@@ -109,6 +133,12 @@ interface CrossdeckOptions {
      * Useful for slicing dashboards by build.
      */
     appVersion?: string;
+    /**
+     * Enable verbose diagnostic logging via the NorthStar §16 debug-signal
+     * vocabulary. Default: false. Equivalent to calling
+     * `Crossdeck.setDebugMode(true)` after init.
+     */
+    debug?: boolean;
 }
 /** Auto-tracking flags. See CrossdeckOptions.autoTrack. */
 interface AutoTrackOptions {
@@ -165,7 +195,11 @@ interface Diagnostics {
  *
  *   import { Crossdeck } from "@cross-deck/web";
  *
- *   Crossdeck.start({ publicKey: "cd_pub_live_…" });
+ *   Crossdeck.init({
+ *     appId: "app_web_xxx",
+ *     publicKey: "cd_pub_live_…",
+ *     environment: "production",
+ *   });
  *
  *   await Crossdeck.identify("user_847");
  *   const ents = await Crossdeck.getEntitlements();
@@ -177,11 +211,12 @@ interface Diagnostics {
  *
  * Usage (Node):
  *
- *   import { Crossdeck } from "@cross-deck/web";
- *   import { MemoryStorage } from "@cross-deck/web";
+ *   import { Crossdeck, MemoryStorage } from "@cross-deck/web";
  *
- *   Crossdeck.start({
+ *   Crossdeck.init({
+ *     appId: "app_node_xxx",
  *     publicKey: "cd_pub_test_…",
+ *     environment: "sandbox",
  *     storage: new MemoryStorage(),  // session-only persistence
  *     autoHeartbeat: false,           // skip the boot ping in scripts
  *   });
@@ -190,9 +225,19 @@ interface Diagnostics {
 declare class CrossdeckClient {
     private state;
     /**
-     * Boot the SDK. Idempotent — calling start twice with the same options
+     * Boot the SDK. Idempotent — calling init twice with the same options
      * is a no-op; calling with different options replaces the previous
      * configuration.
+     *
+     * NorthStar §11.1: signature is `Crossdeck.init({ appId, publicKey,
+     * environment })`. The trio is validated up-front so a typo'd key or a
+     * mismatched env fails fast at boot rather than at first event-flush.
+     */
+    init(options: CrossdeckOptions): void;
+    /**
+     * @deprecated Use `init()` instead. NorthStar §4 standardised the
+     * lifecycle method name across SDKs as `init` (formerly `start` /
+     * `configure`). `start` will be removed in a future major version.
      */
     start(options: CrossdeckOptions): void;
     /**
@@ -216,17 +261,43 @@ declare class CrossdeckClient {
     /**
      * Queue a telemetry event. Returns immediately — the network round-
      * trip happens in the background. To flush before the page unloads,
-     * call flushEvents().
+     * call flush().
      */
     track(name: string, properties?: EventProperties): void;
-    /** Force-flush queued events. Useful to call from page-unload handlers. */
+    /**
+     * Force-flush queued events. Useful to call from page-unload handlers.
+     *
+     * NorthStar §4: standard method name across all Crossdeck SDKs.
+     */
+    flush(): Promise<void>;
+    /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
     flushEvents(): Promise<void>;
-    /** Forward an Apple StoreKit 2 transaction for verification + projection. */
+    /**
+     * Forward purchase evidence to the backend for verification + entitlement
+     * projection. NorthStar §4 + §13 canonical name.
+     *
+     * Today the web SDK only supports Apple StoreKit 2 forwarding (web apps
+     * that sit alongside an iOS app). Stripe doesn't need this method —
+     * Stripe webhooks deliver evidence server-side without a client round-trip.
+     */
+    syncPurchases(input: {
+        rail?: "apple";
+        signedTransactionInfo: string;
+        signedRenewalInfo?: string;
+        appAccountToken?: string;
+    }): Promise<PurchaseResult>;
+    /** @deprecated Use `syncPurchases()` instead. NorthStar §4 standardised the name. */
     purchaseApple(input: {
         signedTransactionInfo: string;
         signedRenewalInfo?: string;
         appAccountToken?: string;
     }): Promise<PurchaseResult>;
+    /**
+     * Toggle verbose diagnostic logging — NorthStar §16. When enabled, the
+     * SDK emits a fixed vocabulary of debug signals to console.info that the
+     * dashboard's onboarding checklist can also surface as live events.
+     */
+    setDebugMode(enabled: boolean): void;
     /**
      * Send the boot heartbeat. Called automatically by start() unless
      * autoHeartbeat:false. Safe to call manually as a "we're still here" ping.
@@ -328,7 +399,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.3.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**