@cross-deck/web 0.2.0 → 0.4.0

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 {
@@ -158,6 +188,48 @@ interface Diagnostics {
     };
 }
 
+/**
+ * Local cache of active entitlements so isEntitled() can answer
+ * synchronously after the first read. Cache is updated:
+ *   - On successful getEntitlements()
+ *   - On successful purchase()
+ *   - Manually via setFromList() (used by callers that batch updates)
+ *
+ * The cache holds only ACTIVE entitlements — inactive ones are excluded
+ * by the backend before they hit us. isEntitled returns false for
+ * anything not in the set.
+ *
+ * Reactive listener API
+ * ---------------------
+ * `subscribe(listener)` registers a callback that fires every time the
+ * cache mutates (setFromList or clear). This is the foundation for the
+ * `useEntitlement` React hook in `@cross-deck/web/react` and any other
+ * framework binding consumers need: SwiftUI's `@Observable`, Vue's
+ * `ref()`, Solid's signals, etc.
+ *
+ * Why we need it: isEntitled() is a sync cache read — but if a React
+ * component calls it in a render path, React has no way to know when
+ * the cache populates asynchronously after `getEntitlements()` lands.
+ * Without a subscribe API the component shows the empty-cache result
+ * forever (until something else triggers a re-render). With it, the
+ * binding can re-render when the data actually arrives.
+ *
+ * Listener semantics:
+ *   - Fired AFTER the cache has been mutated (listener sees fresh state)
+ *   - Fire-and-forget: thrown errors in a listener don't crash the SDK
+ *     (they're swallowed; the next listener still runs)
+ *   - The unsubscribe function returned from subscribe() is idempotent
+ *   - Listeners are NOT fired on subscribe — caller is expected to
+ *     read current state synchronously from isEntitled()/list() if it
+ *     wants the initial render to reflect cached data
+ *
+ * Thread / re-entrancy safety: this is a synchronous in-memory Set with
+ * no I/O. The async paths that update it are serialised through the
+ * SDK's request queue — callers won't see torn reads.
+ */
+
+type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
+
 /**
  * Public API surface for @cross-deck/web.
  *
@@ -165,7 +237,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 +253,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 +267,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;
     /**
@@ -213,20 +300,74 @@ declare class CrossdeckClient {
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
     listEntitlements(): PublicEntitlement[];
+    /**
+     * Subscribe to entitlement-cache changes. Returns an unsubscribe fn.
+     *
+     * The listener is invoked AFTER the cache mutates — once after a
+     * successful `getEntitlements()` warms it, again after `syncPurchases()`
+     * delivers fresh entitlements, and once on `reset()` to fire the
+     * empty-cache state for logout flows.
+     *
+     * It is NOT invoked synchronously on subscribe. Callers that need
+     * the current state should read it via `isEntitled()` / `listEntitlements()`
+     * inline; the listener fires only on FUTURE changes.
+     *
+     * This is the foundation of the `useEntitlement` React hook in
+     * `@cross-deck/web/react` — without it, React (or SwiftUI / Compose
+     * / Vue) would have no way to re-render when entitlements arrive
+     * asynchronously after init. The naive pattern of calling
+     * `Crossdeck.isEntitled("pro")` directly inside a render path
+     * shows the empty-cache result forever; binding the result to
+     * component state via `onEntitlementsChange` is the correct
+     * pattern.
+     *
+     * Idempotent unsubscribe — calling the returned function multiple
+     * times is safe.
+     *
+     * Listener errors are swallowed (a buggy listener can't crash the
+     * SDK or other listeners).
+     */
+    onEntitlementsChange(listener: EntitlementsListener): () => void;
     /**
      * 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 +469,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 {
@@ -158,6 +188,48 @@ interface Diagnostics {
     };
 }
 
+/**
+ * Local cache of active entitlements so isEntitled() can answer
+ * synchronously after the first read. Cache is updated:
+ *   - On successful getEntitlements()
+ *   - On successful purchase()
+ *   - Manually via setFromList() (used by callers that batch updates)
+ *
+ * The cache holds only ACTIVE entitlements — inactive ones are excluded
+ * by the backend before they hit us. isEntitled returns false for
+ * anything not in the set.
+ *
+ * Reactive listener API
+ * ---------------------
+ * `subscribe(listener)` registers a callback that fires every time the
+ * cache mutates (setFromList or clear). This is the foundation for the
+ * `useEntitlement` React hook in `@cross-deck/web/react` and any other
+ * framework binding consumers need: SwiftUI's `@Observable`, Vue's
+ * `ref()`, Solid's signals, etc.
+ *
+ * Why we need it: isEntitled() is a sync cache read — but if a React
+ * component calls it in a render path, React has no way to know when
+ * the cache populates asynchronously after `getEntitlements()` lands.
+ * Without a subscribe API the component shows the empty-cache result
+ * forever (until something else triggers a re-render). With it, the
+ * binding can re-render when the data actually arrives.
+ *
+ * Listener semantics:
+ *   - Fired AFTER the cache has been mutated (listener sees fresh state)
+ *   - Fire-and-forget: thrown errors in a listener don't crash the SDK
+ *     (they're swallowed; the next listener still runs)
+ *   - The unsubscribe function returned from subscribe() is idempotent
+ *   - Listeners are NOT fired on subscribe — caller is expected to
+ *     read current state synchronously from isEntitled()/list() if it
+ *     wants the initial render to reflect cached data
+ *
+ * Thread / re-entrancy safety: this is a synchronous in-memory Set with
+ * no I/O. The async paths that update it are serialised through the
+ * SDK's request queue — callers won't see torn reads.
+ */
+
+type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
+
 /**
  * Public API surface for @cross-deck/web.
  *
@@ -165,7 +237,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 +253,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 +267,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;
     /**
@@ -213,20 +300,74 @@ declare class CrossdeckClient {
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
     listEntitlements(): PublicEntitlement[];
+    /**
+     * Subscribe to entitlement-cache changes. Returns an unsubscribe fn.
+     *
+     * The listener is invoked AFTER the cache mutates — once after a
+     * successful `getEntitlements()` warms it, again after `syncPurchases()`
+     * delivers fresh entitlements, and once on `reset()` to fire the
+     * empty-cache state for logout flows.
+     *
+     * It is NOT invoked synchronously on subscribe. Callers that need
+     * the current state should read it via `isEntitled()` / `listEntitlements()`
+     * inline; the listener fires only on FUTURE changes.
+     *
+     * This is the foundation of the `useEntitlement` React hook in
+     * `@cross-deck/web/react` — without it, React (or SwiftUI / Compose
+     * / Vue) would have no way to re-render when entitlements arrive
+     * asynchronously after init. The naive pattern of calling
+     * `Crossdeck.isEntitled("pro")` directly inside a render path
+     * shows the empty-cache result forever; binding the result to
+     * component state via `onEntitlementsChange` is the correct
+     * pattern.
+     *
+     * Idempotent unsubscribe — calling the returned function multiple
+     * times is safe.
+     *
+     * Listener errors are swallowed (a buggy listener can't crash the
+     * SDK or other listeners).
+     */
+    onEntitlementsChange(listener: EntitlementsListener): () => void;
     /**
      * 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 +469,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";
 
 /**