@cross-deck/web 0.3.0 → 0.5.0

package/dist/index.d.mts

@@ -188,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.
  *
@@ -258,6 +300,34 @@ 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,
@@ -267,9 +337,16 @@ declare class CrossdeckClient {
     /**
      * Force-flush queued events. Useful to call from page-unload handlers.
      *
+     * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+     * visibilitychange→hidden / beforeunload). The browser keeps the
+     * request alive after the page tears down, so the final batch
+     * actually lands instead of being cancelled with the unload.
+     *
      * NorthStar §4: standard method name across all Crossdeck SDKs.
      */
-    flush(): Promise<void>;
+    flush(options?: {
+        keepalive?: boolean;
+    }): Promise<void>;
     /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
     flushEvents(): Promise<void>;
     /**
@@ -399,7 +476,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.5.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

package/dist/index.d.ts

@@ -188,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.
  *
@@ -258,6 +300,34 @@ 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,
@@ -267,9 +337,16 @@ declare class CrossdeckClient {
     /**
      * Force-flush queued events. Useful to call from page-unload handlers.
      *
+     * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+     * visibilitychange→hidden / beforeunload). The browser keeps the
+     * request alive after the page tears down, so the final batch
+     * actually lands instead of being cancelled with the unload.
+     *
      * NorthStar §4: standard method name across all Crossdeck SDKs.
      */
-    flush(): Promise<void>;
+    flush(options?: {
+        keepalive?: boolean;
+    }): Promise<void>;
     /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
     flushEvents(): Promise<void>;
     /**
@@ -399,7 +476,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION = "0.5.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

package/dist/index.mjs

@@ -46,7 +46,7 @@ function typeMapForStatus(status) {
 
 // src/http.ts
 var SDK_NAME = "@cross-deck/web";
-var SDK_VERSION = "0.3.0";
+var SDK_VERSION = "0.5.0";
 var DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 var HttpClient = class {
   constructor(config) {
@@ -78,7 +78,8 @@ var HttpClient = class {
       response = await fetch(url, {
         method,
         headers,
-        body: bodyInit
+        body: bodyInit,
+        keepalive: options.keepalive === true
       });
     } catch (err) {
       throw new CrossdeckError({
@@ -200,6 +201,7 @@ var EntitlementCache = class {
     this.active = /* @__PURE__ */ new Set();
     this.all = [];
     this.lastUpdated = 0;
+    this.listeners = /* @__PURE__ */ new Set();
   }
   /** Sync read — true iff the entitlement key is currently active. */
   isEntitled(key) {
@@ -217,20 +219,57 @@ var EntitlementCache = class {
    * Replace the cache with a fresh server response. The backend already
    * filters to active + env-matching, so we don't re-filter — just trust
    * what we got.
+   *
+   * Fires listeners AFTER the mutation so each listener sees the new state.
    */
   setFromList(entitlements) {
     this.all = entitlements.slice();
     this.active = new Set(entitlements.filter((e) => e.isActive).map((e) => e.key));
     this.lastUpdated = Date.now();
+    this.notify();
   }
   /**
    * Wipe — used on reset() (logout). The SDK forgets everything until
    * the next identify + read.
+   *
+   * Fires listeners so React/SwiftUI/etc bindings re-render to the
+   * logged-out state immediately.
    */
   clear() {
     this.active.clear();
     this.all = [];
     this.lastUpdated = 0;
+    this.notify();
+  }
+  /**
+   * Subscribe to cache mutations. Returns an unsubscribe function.
+   *
+   * The listener is invoked AFTER setFromList() or clear() with the
+   * current snapshot. Throwing inside a listener is non-fatal — the
+   * error is swallowed and subsequent listeners still run.
+   *
+   * Used by `@cross-deck/web/react`'s `useEntitlement` hook to
+   * trigger re-renders when entitlements change.
+   */
+  subscribe(listener) {
+    this.listeners.add(listener);
+    let unsubscribed = false;
+    return () => {
+      if (unsubscribed) return;
+      unsubscribed = true;
+      this.listeners.delete(listener);
+    };
+  }
+  notify() {
+    if (this.listeners.size === 0) return;
+    const snapshot = this.all.slice();
+    const listenersSnapshot = [...this.listeners];
+    for (const listener of listenersSnapshot) {
+      try {
+        listener(snapshot);
+      } catch {
+      }
+    }
   }
 };
 
@@ -265,8 +304,12 @@ var EventQueue = class {
    * Flush the buffer to /v1/events. Resolves when the network call
    * completes (success or failure). On failure, events stay in the
    * buffer for the next flush attempt.
+   *
+   * `options.keepalive` marks the underlying fetch as keepalive so the
+   * browser keeps the request alive past page unload. Use this for
+   * terminal flushes (pagehide / visibilitychange→hidden / beforeunload).
    */
-  async flush() {
+  async flush(options = {}) {
     if (this.buffer.length === 0) return null;
     this.cancelTimerIfSet();
     const batch = this.buffer.splice(0);
@@ -282,7 +325,8 @@ var EventQueue = class {
           environment: env.environment,
           sdk: env.sdk,
           events: batch
-        }
+        },
+        keepalive: options.keepalive === true
       });
       this.lastFlushAt = Date.now();
       this.lastError = null;
@@ -712,7 +756,11 @@ var CrossdeckClient = class {
       storagePrefix: options.storagePrefix ?? "crossdeck:",
       autoHeartbeat: options.autoHeartbeat ?? true,
       eventFlushBatchSize: options.eventFlushBatchSize ?? 20,
-      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 5e3,
+      // 1500ms idle window. Short enough that an event queued on page
+      // load still flushes if the user leaves quickly (the keepalive
+      // pagehide handler picks up anything that doesn't); long enough
+      // that bursts of clicks coalesce into one network round-trip.
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 1500,
       sdkVersion: options.sdkVersion ?? SDK_VERSION,
       autoTrack,
       appVersion: options.appVersion ?? null
@@ -754,7 +802,8 @@ var CrossdeckClient = class {
       deviceInfo,
       options: opts,
       debug,
-      developerUserId: null
+      developerUserId: null,
+      uninstallUnloadFlush: null
     };
     debug.emit("sdk.configured", `Crossdeck connected to ${opts.appId} in ${opts.environment} mode.`, {
       appId: opts.appId,
@@ -769,6 +818,9 @@ var CrossdeckClient = class {
       this.state.autoTracker = tracker;
       tracker.install();
     }
+    this.state.uninstallUnloadFlush = installUnloadFlush(() => {
+      void this.flush({ keepalive: true }).catch(() => void 0);
+    });
     if (opts.autoHeartbeat) {
       void this.heartbeat().catch(() => void 0);
     }
@@ -838,6 +890,37 @@ var CrossdeckClient = class {
     const s = this.requireStarted();
     return s.entitlements.list();
   }
+  /**
+   * 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) {
+    const s = this.requireStarted();
+    return s.entitlements.subscribe(listener);
+  }
   /**
    * Queue a telemetry event. Returns immediately — the network round-
    * trip happens in the background. To flush before the page unloads,
@@ -884,11 +967,16 @@ var CrossdeckClient = class {
   /**
    * Force-flush queued events. Useful to call from page-unload handlers.
    *
+   * Pass `{ keepalive: true }` from terminal handlers (pagehide /
+   * visibilitychange→hidden / beforeunload). The browser keeps the
+   * request alive after the page tears down, so the final batch
+   * actually lands instead of being cancelled with the unload.
+   *
    * NorthStar §4: standard method name across all Crossdeck SDKs.
    */
-  async flush() {
+  async flush(options = {}) {
     const s = this.requireStarted();
-    await s.events.flush();
+    await s.events.flush(options);
   }
   /** @deprecated Use `flush()` instead. NorthStar §4 standardised the name. */
   async flushEvents() {
@@ -1071,6 +1159,23 @@ function resolveAutoTrack(input) {
     deviceInfo: input.deviceInfo ?? DEFAULT_AUTO_TRACK.deviceInfo
   };
 }
+function installUnloadFlush(onUnload) {
+  const w = globalThis.window;
+  const doc = globalThis.document;
+  if (!w || !doc) return () => void 0;
+  const onVisChange = () => {
+    if (doc.visibilityState === "hidden") onUnload();
+  };
+  const onTerminal = () => onUnload();
+  doc.addEventListener("visibilitychange", onVisChange);
+  w.addEventListener("pagehide", onTerminal);
+  w.addEventListener("beforeunload", onTerminal);
+  return () => {
+    doc.removeEventListener("visibilitychange", onVisChange);
+    w.removeEventListener("pagehide", onTerminal);
+    w.removeEventListener("beforeunload", onTerminal);
+  };
+}
 export {
   Crossdeck,
   CrossdeckClient,