@cross-deck/web 1.0.1 → 1.1.0

package/dist/index.d.mts

@@ -276,6 +276,14 @@ interface Diagnostics {
     entitlements: {
         count: number;
         lastUpdated: number;
+        /**
+         * True when the durable cache is knowingly serving older-than-
+         * trustworthy data — the last refresh attempt failed (Crossdeck
+         * unreachable) or last-known-good has aged past the staleness
+         * window. The cache still serves last-known-good; this makes the
+         * staleness observable instead of a silent unbounded window.
+         */
+        stale: boolean;
         /**
          * Cumulative count of listener invocations that threw. Swallowed
          * inside the cache (a buggy consumer must not crash the SDK) but
@@ -300,43 +308,53 @@ 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)
+ * Durable last-known-good cache of the customer's entitlements.
  *
- * 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.
+ * This cache is NOT a second source of truth. Crossdeck remains the
+ * only source; this is the SDK's local copy of what the server last
+ * told us — a cache that doesn't forget during a network partition.
  *
- * 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.
+ * Durability contract (the RevenueCat model):
+ *   - Every successful server read is persisted to device storage
+ *     (localStorage, via the SDK's storage adapter).
+ *   - On SDK boot the cache hydrates from storage synchronously, so
+ *     isEntitled() answers correctly from the very first call — there
+ *     is no cold-start window where a returning Pro customer reads as
+ *     free.
+ *   - When the server is unreachable, the SDK keeps serving the last
+ *     entitlements it successfully fetched. A failed refresh never
+ *     reaches setFromList(), so it cannot clear the cache; only a
+ *     SUCCESSFUL fetch replaces it. An outage can never fail a paying
+ *     customer down to free.
+ *   - Staleness alone never returns false. Each entitlement is honoured
+ *     against its OWN validUntil instead — a time-based trial expiry
+ *     still applies even mid-partition, a still-valid Pro entitlement
+ *     rides the outage out.
+ *   - Staleness is VISIBLE, not silent. validUntil covers time-based
+ *     expiry; it does NOT cover an event-based revoke (chargeback,
+ *     refund, fraud) — that has no validUntil, so the cache would keep
+ *     serving a revoked customer through an outage. Serving them is the
+ *     right trade (don't lock real payers out), but unbounded-and-
+ *     invisible is the bug. So: once a refresh ATTEMPT fails (or the
+ *     data ages past staleAfterMs) the cache is marked stale —
+ *     isStale / freshness are surfaced in diagnostics(). It keeps
+ *     serving last-known-good; the staleness is just no longer hidden.
  *
- * 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.
+ * The cache is wiped only on reset() (logout) and on an identity switch
+ * — never by a TTL.
  *
- * 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.
+ * Reactive listener API
+ * ---------------------
+ * `subscribe(listener)` registers a callback fired every time the cache
+ * mutates (setFromList or clear) — the foundation for the
+ * `useEntitlement` React hook and other framework bindings. Semantics:
+ *   - Fired AFTER the mutation, so the listener sees fresh state.
+ *   - Fire-and-forget: a throwing listener is swallowed (and counted)
+ *     so a buggy consumer can't crash the SDK or other listeners.
+ *   - Unsubscribe is idempotent.
+ *   - Listeners are NOT fired on subscribe — a caller that wants the
+ *     initial state reads isEntitled() / list() synchronously, which
+ *     work from boot thanks to hydration above.
  */
 
 type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
@@ -723,8 +741,12 @@ declare class CrossdeckClient {
      */
     getEntitlements(): Promise<PublicEntitlement[]>;
     /**
-     * Synchronous read from the local cache. Returns false if the cache
-     * has never been populated (call getEntitlements first to warm it).
+     * Synchronous read from the durable local cache — answers from
+     * last-known-good. The cache hydrates from device storage on boot and
+     * survives a Crossdeck outage, so a returning paying customer reads
+     * true even before the session's first network round-trip. Returns
+     * false only for a genuinely new install that has never completed a
+     * getEntitlements(), or for an entitlement past its own validUntil.
      */
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
@@ -955,7 +977,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**

package/dist/index.d.ts

@@ -276,6 +276,14 @@ interface Diagnostics {
     entitlements: {
         count: number;
         lastUpdated: number;
+        /**
+         * True when the durable cache is knowingly serving older-than-
+         * trustworthy data — the last refresh attempt failed (Crossdeck
+         * unreachable) or last-known-good has aged past the staleness
+         * window. The cache still serves last-known-good; this makes the
+         * staleness observable instead of a silent unbounded window.
+         */
+        stale: boolean;
         /**
          * Cumulative count of listener invocations that threw. Swallowed
          * inside the cache (a buggy consumer must not crash the SDK) but
@@ -300,43 +308,53 @@ 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)
+ * Durable last-known-good cache of the customer's entitlements.
  *
- * 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.
+ * This cache is NOT a second source of truth. Crossdeck remains the
+ * only source; this is the SDK's local copy of what the server last
+ * told us — a cache that doesn't forget during a network partition.
  *
- * 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.
+ * Durability contract (the RevenueCat model):
+ *   - Every successful server read is persisted to device storage
+ *     (localStorage, via the SDK's storage adapter).
+ *   - On SDK boot the cache hydrates from storage synchronously, so
+ *     isEntitled() answers correctly from the very first call — there
+ *     is no cold-start window where a returning Pro customer reads as
+ *     free.
+ *   - When the server is unreachable, the SDK keeps serving the last
+ *     entitlements it successfully fetched. A failed refresh never
+ *     reaches setFromList(), so it cannot clear the cache; only a
+ *     SUCCESSFUL fetch replaces it. An outage can never fail a paying
+ *     customer down to free.
+ *   - Staleness alone never returns false. Each entitlement is honoured
+ *     against its OWN validUntil instead — a time-based trial expiry
+ *     still applies even mid-partition, a still-valid Pro entitlement
+ *     rides the outage out.
+ *   - Staleness is VISIBLE, not silent. validUntil covers time-based
+ *     expiry; it does NOT cover an event-based revoke (chargeback,
+ *     refund, fraud) — that has no validUntil, so the cache would keep
+ *     serving a revoked customer through an outage. Serving them is the
+ *     right trade (don't lock real payers out), but unbounded-and-
+ *     invisible is the bug. So: once a refresh ATTEMPT fails (or the
+ *     data ages past staleAfterMs) the cache is marked stale —
+ *     isStale / freshness are surfaced in diagnostics(). It keeps
+ *     serving last-known-good; the staleness is just no longer hidden.
  *
- * 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.
+ * The cache is wiped only on reset() (logout) and on an identity switch
+ * — never by a TTL.
  *
- * 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.
+ * Reactive listener API
+ * ---------------------
+ * `subscribe(listener)` registers a callback fired every time the cache
+ * mutates (setFromList or clear) — the foundation for the
+ * `useEntitlement` React hook and other framework bindings. Semantics:
+ *   - Fired AFTER the mutation, so the listener sees fresh state.
+ *   - Fire-and-forget: a throwing listener is swallowed (and counted)
+ *     so a buggy consumer can't crash the SDK or other listeners.
+ *   - Unsubscribe is idempotent.
+ *   - Listeners are NOT fired on subscribe — a caller that wants the
+ *     initial state reads isEntitled() / list() synchronously, which
+ *     work from boot thanks to hydration above.
  */
 
 type EntitlementsListener = (entitlements: PublicEntitlement[]) => void;
@@ -723,8 +741,12 @@ declare class CrossdeckClient {
      */
     getEntitlements(): Promise<PublicEntitlement[]>;
     /**
-     * Synchronous read from the local cache. Returns false if the cache
-     * has never been populated (call getEntitlements first to warm it).
+     * Synchronous read from the durable local cache — answers from
+     * last-known-good. The cache hydrates from device storage on boot and
+     * survives a Crossdeck outage, so a returning paying customer reads
+     * true even before the session's first network round-trip. Returns
+     * false only for a genuinely new install that has never completed a
+     * getEntitlements(), or for an entitlement past its own validUntil.
      */
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
@@ -955,7 +977,7 @@ declare class MemoryStorage implements KeyValueStorage {
  * fetch shim, no transitive deps.
  */
 declare const SDK_NAME = "@cross-deck/web";
-declare const SDK_VERSION = "1.0.0";
+declare const SDK_VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://api.cross-deck.com/v1";
 
 /**