@cross-deck/web 0.1.1 → 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");
@@ -33,29 +37,71 @@ That's the full happy path.
 
 ## What it does
 
+- **Auto-tracking, on by default.** Sessions, page views, and device info (OS, browser, locale, timezone, screen size, app version) ship from boot. No instrumentation needed for the basics. Disable any of them via `autoTrack: { sessions: false }` etc.
 - **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
+
+| Event | When |
+|---|---|
+| `session.started` | On boot. Carries `sessionId`. |
+| `session.ended` | On `pagehide` / `beforeunload`, OR when returning to a tab after >30 min idle. Carries `sessionId` and `durationMs`. |
+| `page.viewed` | On initial load + every SPA navigation (`history.pushState`, `replaceState`, `popstate`). Carries `path`, `url`, `search`, `hash`, `title`, `referrer`. |
+
+Every event — auto-tracked and developer-emitted — is enriched with the device-info payload below. Quick tab switches (Cmd-Tab, switching browser tabs) don't end the session — only real closes do, matching GA4's session-window convention.
+
+## Auto-attached device info
+
+Every event's `properties` is enriched with whatever the SDK can detect:
+
+```ts
+{
+  os: "macOS" | "iOS" | "Android" | "Windows" | "Linux",
+  osVersion: "14.4",
+  browser: "Safari" | "Chrome" | "Firefox" | "Edge" | "Opera",
+  browserVersion: "17.5",
+  locale: "en-US",
+  timezone: "Africa/Johannesburg",
+  screenWidth: 2560,
+  screenHeight: 1440,
+  viewportWidth: 1440,
+  viewportHeight: 900,
+  devicePixelRatio: 2,
+  appVersion: "1.2.3",   // only when you set Crossdeck.start({ appVersion })
+}
+```
+
+No fingerprinting, no IP collection on the event document, no canvas hashing. Privacy by default. Caller-supplied properties always override auto-detected ones, so you can override `appVersion` per event if you A/B builds.
+
 ## 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
+  // …or granular: autoTrack: { sessions: false } keeps page views + device info
   autoHeartbeat: true,                // default; set false for high-frequency boots
   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?)`
@@ -92,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
@@ -120,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()`
 
@@ -149,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";
@@ -183,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
@@ -90,6 +114,40 @@ interface CrossdeckOptions {
     eventFlushIntervalMs?: number;
     /** Override the SDK version reported on heartbeats. Default: package version. */
     sdkVersion?: string;
+    /**
+     * Auto-tracking. Default: every flag is `true` in browsers, all
+     * silently no-op in Node.
+     *
+     * Pass `false` to disable everything, or a partial object to override
+     * individual flags:
+     *
+     *   Crossdeck.start({
+     *     publicKey: "...",
+     *     autoTrack: { pageViews: false }, // sessions + deviceInfo still on
+     *   });
+     */
+    autoTrack?: boolean | Partial<AutoTrackOptions>;
+    /**
+     * Your app's version (e.g. "1.2.3"). Auto-attached to every event as
+     * `properties.appVersion` when `autoTrack.deviceInfo` is enabled.
+     * 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 {
+    /** Emit `session.started` / `session.ended` automatically. Default true (browser only). */
+    sessions: boolean;
+    /** Emit `page.viewed` on initial load + SPA navigation. Default true (browser only). */
+    pageViews: boolean;
+    /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
+    deviceInfo: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -137,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();
@@ -149,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
  *   });
@@ -162,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;
     /**
@@ -188,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.
@@ -300,7 +399,41 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.1.1";
+declare const SDK_VERSION = "0.3.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
-export { type AliasResult, type AuditRail, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };
+/**
+ * Device + environment enrichment.
+ *
+ * Auto-attached to every event the SDK emits when `autoTrack.deviceInfo` is
+ * enabled (default). Caller-supplied event properties always override
+ * auto-detected ones (so a developer can manually set `app.version` per
+ * event if they want to A/B between builds).
+ *
+ * Privacy posture:
+ *   - No fingerprinting (no canvas hashes, no font enumeration).
+ *   - No precise geolocation (only timezone + locale, both of which the
+ *     browser exposes to every page anyway).
+ *   - No IP collection — the backend logs the request IP for rate-limit
+ *     purposes; it isn't stored on the event document.
+ *   - All fields are typed enums or short strings; we never echo back
+ *     full User-Agent strings to avoid surfacing fingerprintable detail
+ *     in dashboards.
+ */
+interface DeviceInfo {
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    locale?: string;
+    timezone?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    devicePixelRatio?: number;
+    /** Caller-supplied. Set via Crossdeck.start({ appVersion: "1.2.3" }). */
+    appVersion?: string;
+}
+
+export { type AliasResult, type AuditRail, type AutoTrackOptions, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };

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
@@ -90,6 +114,40 @@ interface CrossdeckOptions {
     eventFlushIntervalMs?: number;
     /** Override the SDK version reported on heartbeats. Default: package version. */
     sdkVersion?: string;
+    /**
+     * Auto-tracking. Default: every flag is `true` in browsers, all
+     * silently no-op in Node.
+     *
+     * Pass `false` to disable everything, or a partial object to override
+     * individual flags:
+     *
+     *   Crossdeck.start({
+     *     publicKey: "...",
+     *     autoTrack: { pageViews: false }, // sessions + deviceInfo still on
+     *   });
+     */
+    autoTrack?: boolean | Partial<AutoTrackOptions>;
+    /**
+     * Your app's version (e.g. "1.2.3"). Auto-attached to every event as
+     * `properties.appVersion` when `autoTrack.deviceInfo` is enabled.
+     * 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 {
+    /** Emit `session.started` / `session.ended` automatically. Default true (browser only). */
+    sessions: boolean;
+    /** Emit `page.viewed` on initial load + SPA navigation. Default true (browser only). */
+    pageViews: boolean;
+    /** Auto-attach os/browser/locale/screen/etc to every event's `properties`. Default true (browser only). */
+    deviceInfo: boolean;
 }
 /** Minimal interface for any pluggable key-value persistence. */
 interface KeyValueStorage {
@@ -137,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();
@@ -149,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
  *   });
@@ -162,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;
     /**
@@ -188,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.
@@ -300,7 +399,41 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.1.1";
+declare const SDK_VERSION = "0.3.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
-export { type AliasResult, type AuditRail, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };
+/**
+ * Device + environment enrichment.
+ *
+ * Auto-attached to every event the SDK emits when `autoTrack.deviceInfo` is
+ * enabled (default). Caller-supplied event properties always override
+ * auto-detected ones (so a developer can manually set `app.version` per
+ * event if they want to A/B between builds).
+ *
+ * Privacy posture:
+ *   - No fingerprinting (no canvas hashes, no font enumeration).
+ *   - No precise geolocation (only timezone + locale, both of which the
+ *     browser exposes to every page anyway).
+ *   - No IP collection — the backend logs the request IP for rate-limit
+ *     purposes; it isn't stored on the event document.
+ *   - All fields are typed enums or short strings; we never echo back
+ *     full User-Agent strings to avoid surfacing fingerprintable detail
+ *     in dashboards.
+ */
+interface DeviceInfo {
+    os?: string;
+    osVersion?: string;
+    browser?: string;
+    browserVersion?: string;
+    locale?: string;
+    timezone?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    devicePixelRatio?: number;
+    /** Caller-supplied. Set via Crossdeck.start({ appVersion: "1.2.3" }). */
+    appVersion?: string;
+}
+
+export { type AliasResult, type AuditRail, type AutoTrackOptions, Crossdeck, CrossdeckClient, CrossdeckError, type CrossdeckErrorPayload, type CrossdeckErrorType, type CrossdeckOptions, DEFAULT_BASE_URL, type DeviceInfo, type Diagnostics, type EntitlementsListResponse, type Environment, type EventProperties, type HeartbeatResponse, type IdentifyOptions, type KeyValueStorage, MemoryStorage, type Platform, type PublicEntitlement, type PurchaseResult, SDK_NAME, SDK_VERSION };