@cross-deck/web 1.4.2 → 1.5.1

package/dist/react.d 2.mts

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+import { C as CrossdeckOptions } from './types-Bu3jbmdq.mjs';
+
+/**
+ * @cross-deck/web/react — React hooks for the Crossdeck SDK.
+ *
+ * Why this exists: `Crossdeck.isEntitled("pro")` is a synchronous cache
+ * read, but the cache populates asynchronously after `getEntitlements()`
+ * lands. React has no way to know the cache changed, so a component
+ * that calls `isEntitled` directly in a render path would show the
+ * empty-cache result forever (until something else triggered a re-render).
+ *
+ * The `useEntitlement` hook below ties cache state to React state via
+ * `onEntitlementsChange`, so the component re-renders the moment the
+ * answer changes. After the first render, every subsequent check is a
+ * sync cache hit — exactly the "microsecond entitlement check" the
+ * SDK promises.
+ *
+ * Side effect: importing this module pulls in `react` as a peer
+ * dependency. Consumers who don't use React shouldn't import it.
+ *
+ * SSR safety: `useEffect` is a no-op during server-side rendering, and
+ * the initial state is conservative (`false` until proven otherwise),
+ * so server output never claims a non-existent entitlement. The hook
+ * hydrates correctly on the client.
+ *
+ * NorthStar §11.4 (reactive bindings): every SDK ships first-class
+ * framework bindings so the canonical snippet stays one line. Web =>
+ * React hook here. iOS => `@Observable` SwiftUI wrapper (when iOS SDK
+ * ships). Android => Compose `State<Boolean>` wrapper (when Android
+ * SDK ships).
+ */
+
+interface CrossdeckProviderProps extends Omit<CrossdeckOptions, "userId"> {
+    /**
+     * Optional. When defined, the provider calls Crossdeck.identify(userId)
+     * after init and on every change. When the prop flips back to undefined
+     * (logout), the provider calls Crossdeck.reset().
+     *
+     * Pass your auth library's stable user id directly:
+     *   <CrossdeckProvider userId={session?.user?.id} … />          // NextAuth
+     *   <CrossdeckProvider userId={user?.uid} … />                  // Firebase
+     *   <CrossdeckProvider userId={supabase.auth.user()?.id} … />   // Supabase
+     *
+     * Anonymous (pre-login) traffic stays anonymous until userId becomes
+     * defined — the SDK's anonymousId follows the same user record once
+     * identify lands, so attribution survives sign-up.
+     */
+    userId?: string | null | undefined;
+    children: ReactNode;
+}
+declare function CrossdeckProvider(props: CrossdeckProviderProps): ReactNode;
+/**
+ * Subscribe a React component to a single entitlement key.
+ *
+ * The hook returns the current `isEntitled(key)` value AND keeps it in
+ * sync with the cache. When `getEntitlements()` lands, when a purchase
+ * adds an entitlement, or when `reset()` is called on logout, every
+ * component using this hook re-renders to reflect the change.
+ *
+ * Usage:
+ *
+ *   import { useEntitlement } from "@cross-deck/web/react";
+ *
+ *   function ProBadge() {
+ *     const isPro = useEntitlement("pro");
+ *     return isPro ? <span className="badge">Pro</span> : null;
+ *   }
+ *
+ * Note that the hook does NOT call `getEntitlements()` itself — that's
+ * a one-time boot warm-up the consumer is expected to trigger after
+ * `Crossdeck.init()` (typically inside a top-level effect in their
+ * Providers wrapper). Once warmed, every component using this hook
+ * gets the answer for free.
+ *
+ * Pre-init: returns `false`. Calling Crossdeck.init() later doesn't
+ * automatically refresh existing hook instances — but as soon as
+ * something mutates the cache (i.e. after a successful
+ * getEntitlements() call on the new SDK instance), the hook fires.
+ */
+declare function useEntitlement(key: string): boolean;
+/**
+ * Subscribe to the full entitlement list. Returns an array of active
+ * entitlement keys, kept in sync with the cache. Useful for iterating
+ * (e.g. rendering a list of unlocked features in a settings page).
+ *
+ * Same pre-init / SSR semantics as `useEntitlement`.
+ */
+declare function useEntitlements(): readonly string[];
+
+export { CrossdeckProvider, useEntitlement, useEntitlements };

package/dist/react.d 2.ts

@@ -0,0 +1,91 @@
+import { ReactNode } from 'react';
+import { C as CrossdeckOptions } from './types-Bu3jbmdq.js';
+
+/**
+ * @cross-deck/web/react — React hooks for the Crossdeck SDK.
+ *
+ * Why this exists: `Crossdeck.isEntitled("pro")` is a synchronous cache
+ * read, but the cache populates asynchronously after `getEntitlements()`
+ * lands. React has no way to know the cache changed, so a component
+ * that calls `isEntitled` directly in a render path would show the
+ * empty-cache result forever (until something else triggered a re-render).
+ *
+ * The `useEntitlement` hook below ties cache state to React state via
+ * `onEntitlementsChange`, so the component re-renders the moment the
+ * answer changes. After the first render, every subsequent check is a
+ * sync cache hit — exactly the "microsecond entitlement check" the
+ * SDK promises.
+ *
+ * Side effect: importing this module pulls in `react` as a peer
+ * dependency. Consumers who don't use React shouldn't import it.
+ *
+ * SSR safety: `useEffect` is a no-op during server-side rendering, and
+ * the initial state is conservative (`false` until proven otherwise),
+ * so server output never claims a non-existent entitlement. The hook
+ * hydrates correctly on the client.
+ *
+ * NorthStar §11.4 (reactive bindings): every SDK ships first-class
+ * framework bindings so the canonical snippet stays one line. Web =>
+ * React hook here. iOS => `@Observable` SwiftUI wrapper (when iOS SDK
+ * ships). Android => Compose `State<Boolean>` wrapper (when Android
+ * SDK ships).
+ */
+
+interface CrossdeckProviderProps extends Omit<CrossdeckOptions, "userId"> {
+    /**
+     * Optional. When defined, the provider calls Crossdeck.identify(userId)
+     * after init and on every change. When the prop flips back to undefined
+     * (logout), the provider calls Crossdeck.reset().
+     *
+     * Pass your auth library's stable user id directly:
+     *   <CrossdeckProvider userId={session?.user?.id} … />          // NextAuth
+     *   <CrossdeckProvider userId={user?.uid} … />                  // Firebase
+     *   <CrossdeckProvider userId={supabase.auth.user()?.id} … />   // Supabase
+     *
+     * Anonymous (pre-login) traffic stays anonymous until userId becomes
+     * defined — the SDK's anonymousId follows the same user record once
+     * identify lands, so attribution survives sign-up.
+     */
+    userId?: string | null | undefined;
+    children: ReactNode;
+}
+declare function CrossdeckProvider(props: CrossdeckProviderProps): ReactNode;
+/**
+ * Subscribe a React component to a single entitlement key.
+ *
+ * The hook returns the current `isEntitled(key)` value AND keeps it in
+ * sync with the cache. When `getEntitlements()` lands, when a purchase
+ * adds an entitlement, or when `reset()` is called on logout, every
+ * component using this hook re-renders to reflect the change.
+ *
+ * Usage:
+ *
+ *   import { useEntitlement } from "@cross-deck/web/react";
+ *
+ *   function ProBadge() {
+ *     const isPro = useEntitlement("pro");
+ *     return isPro ? <span className="badge">Pro</span> : null;
+ *   }
+ *
+ * Note that the hook does NOT call `getEntitlements()` itself — that's
+ * a one-time boot warm-up the consumer is expected to trigger after
+ * `Crossdeck.init()` (typically inside a top-level effect in their
+ * Providers wrapper). Once warmed, every component using this hook
+ * gets the answer for free.
+ *
+ * Pre-init: returns `false`. Calling Crossdeck.init() later doesn't
+ * automatically refresh existing hook instances — but as soon as
+ * something mutates the cache (i.e. after a successful
+ * getEntitlements() call on the new SDK instance), the hook fires.
+ */
+declare function useEntitlement(key: string): boolean;
+/**
+ * Subscribe to the full entitlement list. Returns an array of active
+ * entitlement keys, kept in sync with the cache. Useful for iterating
+ * (e.g. rendering a list of unlocked features in a settings page).
+ *
+ * Same pre-init / SSR semantics as `useEntitlement`.
+ */
+declare function useEntitlements(): readonly string[];
+
+export { CrossdeckProvider, useEntitlement, useEntitlements };

package/dist/react.mjs

@@ -3676,6 +3676,37 @@ var CrossdeckClient = class {
    * trip happens in the background. To flush before the page unloads,
    * call flush().
    */
+  /**
+   * Emit `crossdeck.contract_failed` with the canonical property
+   * shape (`contract_id`, `sdk_version`, `sdk_platform`,
+   * `failure_reason`, `run_context`, `run_id`). Goes through the
+   * standard track() pipeline — same consent gate, same queue,
+   * same ingest, no new endpoint.
+   *
+   * Wire the call from a test hook, dogfood failure path, or
+   * customer contract-verification harness; see
+   * `contracts/README.md` for the per-test-framework hook recipes.
+   */
+  reportContractFailure(input) {
+    const props = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "web",
+      failure_reason: input.failureReason,
+      run_context: input.runContext,
+      run_id: input.runId
+    };
+    if (input.testRef) {
+      props.test_file = input.testRef.file;
+      props.test_name = input.testRef.name;
+    }
+    if (input.extra) {
+      for (const [k, v] of Object.entries(input.extra)) {
+        if (props[k] === void 0) props[k] = v;
+      }
+    }
+    this.track("crossdeck.contract_failed", props);
+  }
   track(name, properties) {
     const s = this.requireStarted();
     if (!name) {