@cross-deck/web 1.5.6 → 1.6.1

package/dist/index.d.mts

@@ -232,9 +232,9 @@ declare const CrossdeckContracts: {
     /** Filter by lifecycle status. */
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
     /** Semver of the SDK release these contracts were bundled with. */
-    readonly sdkVersion: "1.5.3";
+    readonly sdkVersion: "1.6.1";
     /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
-    readonly bundledIn: "@cross-deck/web@1.5.3";
+    readonly bundledIn: "@cross-deck/web@1.6.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks (Vitest `afterEach`, XCTest
@@ -634,6 +634,12 @@ declare class CrossdeckClient {
      * 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.
+     *
+     * Throws `not_initialized` (CrossdeckError, type
+     * `configuration_error`) if called before `Crossdeck.init()`. The
+     * `useEntitlement` React hook and the Vue composable both swallow
+     * this and return `false`; bare callers must guard for it (or call
+     * after `init()` resolves).
      */
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
@@ -643,8 +649,21 @@ declare class CrossdeckClient {
      *
      * 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.
+     * delivers fresh entitlements, once on `reset()` to fire the empty-
+     * cache state for logout flows, AND once on `identify()` after the
+     * per-user cache slot rotates and re-hydrates from device storage.
+     *
+     * IMPORTANT — the `identify()` fire is a TRAP if you treat it as
+     * authoritative network state. `identify()` does NOT fetch entitlements;
+     * it switches the per-user cache slot and rehydrates from device
+     * storage (which is empty for a brand-new install, and last-known-good
+     * — possibly stale — for a returning user). A listener that gates a
+     * paywall on the first fire after an identity switch will read
+     * `false` for a paying customer on a fresh device and let them past
+     * the gate as free. The network-truth fire is the one that follows
+     * the next `getEntitlements()` resolution. Either call
+     * `getEntitlements()` explicitly after `identify()`, or have your
+     * gating code tolerate the empty-then-populated transition.
      *
      * It is NOT invoked synchronously on subscribe. Callers that need
      * the current state should read it via `isEntitled()` / `listEntitlements()`
@@ -748,6 +767,22 @@ declare class CrossdeckClient {
      * `entitlements`. Pre-start values are sensible empties.
      */
     diagnostics(): Diagnostics;
+    /**
+     * The stable reference to hand Stripe at checkout so the resulting
+     * purchase attributes to THIS person. Stamp it on the Checkout Session
+     * as `metadata.crossdeck_ref` (see docs/connect-stripe) — the platform
+     * webhook reads it back, validates it, and attaches the subscription to
+     * the right customer instead of stranding it on an anonymous record.
+     *
+     * Returns the strongest identifier the SDK currently holds, in the same
+     * precedence the server resolves by:
+     *   crossdeckCustomerId (cdcust_…) > developerUserId > anonymousId
+     * anonymousId is always present, so this always returns a usable,
+     * non-empty reference — even before identify(). Identify the user as
+     * early as you can, though, so the reference is their stable identity
+     * and not a per-device anon id.
+     */
+    getCheckoutReference(): string;
     private requireStarted;
     /**
      * Build the identity query for /v1/entitlements. Priority:
@@ -886,7 +921,7 @@ declare class MemoryStorage implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.5.3";
+declare const SDK_VERSION = "1.6.1";
 declare const SDK_NAME = "@cross-deck/web";
 
 /**

package/dist/index.d.ts

@@ -232,9 +232,9 @@ declare const CrossdeckContracts: {
     /** Filter by lifecycle status. */
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
     /** Semver of the SDK release these contracts were bundled with. */
-    readonly sdkVersion: "1.5.3";
+    readonly sdkVersion: "1.6.1";
     /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
-    readonly bundledIn: "@cross-deck/web@1.5.3";
+    readonly bundledIn: "@cross-deck/web@1.6.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks (Vitest `afterEach`, XCTest
@@ -634,6 +634,12 @@ declare class CrossdeckClient {
      * 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.
+     *
+     * Throws `not_initialized` (CrossdeckError, type
+     * `configuration_error`) if called before `Crossdeck.init()`. The
+     * `useEntitlement` React hook and the Vue composable both swallow
+     * this and return `false`; bare callers must guard for it (or call
+     * after `init()` resolves).
      */
     isEntitled(key: string): boolean;
     /** Snapshot of the local entitlement cache. */
@@ -643,8 +649,21 @@ declare class CrossdeckClient {
      *
      * 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.
+     * delivers fresh entitlements, once on `reset()` to fire the empty-
+     * cache state for logout flows, AND once on `identify()` after the
+     * per-user cache slot rotates and re-hydrates from device storage.
+     *
+     * IMPORTANT — the `identify()` fire is a TRAP if you treat it as
+     * authoritative network state. `identify()` does NOT fetch entitlements;
+     * it switches the per-user cache slot and rehydrates from device
+     * storage (which is empty for a brand-new install, and last-known-good
+     * — possibly stale — for a returning user). A listener that gates a
+     * paywall on the first fire after an identity switch will read
+     * `false` for a paying customer on a fresh device and let them past
+     * the gate as free. The network-truth fire is the one that follows
+     * the next `getEntitlements()` resolution. Either call
+     * `getEntitlements()` explicitly after `identify()`, or have your
+     * gating code tolerate the empty-then-populated transition.
      *
      * It is NOT invoked synchronously on subscribe. Callers that need
      * the current state should read it via `isEntitled()` / `listEntitlements()`
@@ -748,6 +767,22 @@ declare class CrossdeckClient {
      * `entitlements`. Pre-start values are sensible empties.
      */
     diagnostics(): Diagnostics;
+    /**
+     * The stable reference to hand Stripe at checkout so the resulting
+     * purchase attributes to THIS person. Stamp it on the Checkout Session
+     * as `metadata.crossdeck_ref` (see docs/connect-stripe) — the platform
+     * webhook reads it back, validates it, and attaches the subscription to
+     * the right customer instead of stranding it on an anonymous record.
+     *
+     * Returns the strongest identifier the SDK currently holds, in the same
+     * precedence the server resolves by:
+     *   crossdeckCustomerId (cdcust_…) > developerUserId > anonymousId
+     * anonymousId is always present, so this always returns a usable,
+     * non-empty reference — even before identify(). Identify the user as
+     * early as you can, though, so the reference is their stable identity
+     * and not a per-device anon id.
+     */
+    getCheckoutReference(): string;
     private requireStarted;
     /**
      * Build the identity query for /v1/entitlements. Priority:
@@ -886,7 +921,7 @@ declare class MemoryStorage implements KeyValueStorage {
  *
  * Do NOT edit by hand — `node scripts/sync-sdk-versions.mjs`.
  */
-declare const SDK_VERSION = "1.5.3";
+declare const SDK_VERSION = "1.6.1";
 declare const SDK_NAME = "@cross-deck/web";
 
 /**