@superwall/paywalls-react 0.2.0 → 0.2.5

package/dist/SuperwallPaywall.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import type { PlacementParams } from "@superwall/paywalls-js";
+import type { PaywallPresentationHandlerHooks } from "./hooks.js";
+export interface SuperwallPaywallProps extends PaywallPresentationHandlerHooks {
+    placement: string;
+    params?: PlacementParams;
+    /** Rendered when the user is entitled — i.e. the feature block fires. */
+    children?: ReactNode;
+    /** Rendered while the paywall is loading. Swapped out the moment the paywall presents. */
+    loading?: ReactNode;
+    /**
+     * When true the paywall iframe is mounted inside this component instead of
+     * as a full-viewport overlay. Default: false.
+     */
+    inline?: boolean;
+}
+/**
+ * Declarative feature gate. Calls `register()` on mount and renders
+ * `children` when the user is entitled (already subscribed, purchased
+ * through the paywall, or the placement has no audience match).
+ *
+ * ```tsx
+ * <SuperwallPaywall placement="campaign_trigger" loading={<Spinner />}>
+ *   <ProContent />
+ * </SuperwallPaywall>
+ * ```
+ */
+export declare function SuperwallPaywall({ placement, params, children, loading, inline, onPresent, onDismiss, onSkip, onError, }: SuperwallPaywallProps): import("react/jsx-runtime").JSX.Element;

package/dist/SuperwallPaywall.js

@@ -0,0 +1,50 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { createBrowserPresenter } from "@superwall/paywalls-js/browser";
+import { useSuperwall } from "./hooks.js";
+/**
+ * Declarative feature gate. Calls `register()` on mount and renders
+ * `children` when the user is entitled (already subscribed, purchased
+ * through the paywall, or the placement has no audience match).
+ *
+ * ```tsx
+ * <SuperwallPaywall placement="campaign_trigger" loading={<Spinner />}>
+ *   <ProContent />
+ * </SuperwallPaywall>
+ * ```
+ */
+export function SuperwallPaywall({ placement, params, children, loading = null, inline = false, onPresent, onDismiss, onSkip, onError, }) {
+    const sw = useSuperwall();
+    const [unlocked, setUnlocked] = useState(false);
+    const [presenting, setPresenting] = useState(false);
+    const containerRef = useRef(null);
+    const handlersRef = useRef({ onPresent, onDismiss, onSkip, onError });
+    handlersRef.current = { onPresent, onDismiss, onSkip, onError };
+    const presenter = useMemo(() => inline
+        ? createBrowserPresenter({ container: () => containerRef.current ?? document.body, inline: true })
+        : undefined, [inline]);
+    useEffect(() => {
+        let cancelled = false;
+        sw.register({
+            placement,
+            ...(params && { params }),
+            feature: () => { if (!cancelled)
+                setUnlocked(true); },
+            ...(presenter && { presenter }),
+            handler: {
+                onPresent: (info) => { if (!cancelled)
+                    setPresenting(true); handlersRef.current.onPresent?.(info); },
+                onDismiss: (info, result) => { handlersRef.current.onDismiss?.(info, result); },
+                onSkip: (reason) => { handlersRef.current.onSkip?.(reason); },
+                onError: (error) => { handlersRef.current.onError?.(error); },
+            },
+        }).catch(() => { });
+        return () => { cancelled = true; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [placement, params, presenter]);
+    if (unlocked)
+        return _jsx(_Fragment, { children: children });
+    // Container always stays in the DOM so the presenter can append the iframe
+    // before onPresent fires. We swap loading ↔ iframe via display:none.
+    return (_jsxs("div", { style: { position: "relative", width: "100%", height: "100%" }, children: [_jsx("div", { ref: containerRef, style: { display: presenting ? "block" : "none", width: "100%", height: "100%" } }), !presenting && (_jsx("div", { style: { position: "absolute", inset: 0 }, children: loading }))] }));
+}

package/dist/hooks.d.ts

@@ -0,0 +1,108 @@
+import type { AllSuperwallEvents, CustomerInfo, CustomPaywallController, CustomPaywallState, Entitlement, IdentityOptions, IntegrationAttribute, PaywallInfo, PaywallResult, PaywallSkippedReason, PlacementParams, Readable, RegisterPlacementArgs, RegisterPlacementResult, Superwall, SuperwallCustomEvent, SuperwallDelegate, SubscriptionStatus, UserAttributes } from "@superwall/paywalls-js";
+export declare const useSuperwall: () => Superwall;
+/**
+ * Subscribe to a `Readable<T>` and re-render on change. Stores the signal
+ * in a ref so an unstable `signal` identity per render doesn't cause
+ * `useSyncExternalStore` to re-subscribe on every render (which would
+ * spin into an infinite re-render loop). The ref always points at the
+ * latest signal; subscribe + getSnapshot read through it.
+ */
+export declare const useSignal: <T>(signal: Readable<T>) => T;
+export interface UseUserResult {
+    id: string;
+    aliasId: string;
+    effectiveId: string;
+    isLoggedIn: boolean;
+    attributes: UserAttributes;
+    integrationAttributes: Partial<Record<IntegrationAttribute, string>>;
+    subscriptionStatus: SubscriptionStatus;
+    customerInfo: CustomerInfo | null;
+    /** Active entitlements convenience — derived from subscriptionStatus. */
+    entitlements: Entitlement[];
+    identify: (userId: string, opts?: IdentityOptions) => Promise<void>;
+    signOut: () => Promise<void>;
+    setAttributes: (attrs: Partial<UserAttributes>) => void;
+    setIntegrationAttribute: (attr: IntegrationAttribute, value: string | null) => void;
+    setIntegrationAttributes: (attrs: Partial<Record<IntegrationAttribute, string | null>>) => void;
+}
+export declare const useUser: () => UseUserResult;
+export interface PaywallPresentationHandlerHooks {
+    onPresent?(info: PaywallInfo): void;
+    onDismiss?(info: PaywallInfo, result: PaywallResult): void;
+    onError?(error: Error): void;
+    onSkip?(reason: PaywallSkippedReason): void;
+}
+export type PaywallState = {
+    type: "idle";
+} | {
+    type: "presented";
+    info: PaywallInfo;
+} | {
+    type: "dismissed";
+    info: PaywallInfo;
+    result: PaywallResult;
+} | {
+    type: "skipped";
+    reason: PaywallSkippedReason;
+} | {
+    type: "error";
+    error: Error;
+};
+export interface UsePlacementResult {
+    register: (args: RegisterPlacementArgs) => Promise<RegisterPlacementResult>;
+    state: PaywallState;
+}
+/**
+ * Returns a `register` function bound to the active Superwall + a `state`
+ * reflecting the latest placement outcome from THIS hook's calls. Handler
+ * callbacks fire alongside the global delegate. State is local to the
+ * hook (one component's state, not the SDK's).
+ */
+export declare const usePlacement: (handler?: PaywallPresentationHandlerHooks) => UsePlacementResult;
+export interface UseCustomPaywallOptions extends PaywallPresentationHandlerHooks {
+    placement: string;
+    params?: PlacementParams;
+    /** Runs when the user is entitled OR a non-gated paywall is dismissed
+     *  without purchase. Same semantics as `register({ feature })`. */
+    feature?: () => void | Promise<void>;
+}
+export interface CustomPaywallMountSnapshot {
+    readonly state: CustomPaywallState;
+    readonly controller: CustomPaywallController;
+}
+export interface UseCustomPaywallResult {
+    /** Trigger the placement. Runs the full SDK pipeline (rules / holdout /
+     *  assignment / gating / analytics); if it decides to present, `paywall`
+     *  flips non-null and your UI should render. Resolves with the placement
+     *  outcome. */
+    register: () => Promise<RegisterPlacementResult>;
+    /** Active mount (state snapshot + controller) while presenting, else null.
+     *  Re-renders the calling component whenever the transaction / restoration
+     *  phase changes. */
+    paywall: CustomPaywallMountSnapshot | null;
+}
+/**
+ * React primitive for custom (developer-rendered) paywalls — the web analogue
+ * of Android's `SuperwallCustomPaywall`. You own the UI; the SDK runs the
+ * trigger pipeline, resolves products, fires identical lifecycle events, and
+ * hands you a controller. Render `paywall` when it's non-null; drive
+ * `paywall.controller.buy / restore / close` from your buttons.
+ *
+ *   const { register, paywall } = useCustomPaywall({ placement: "home" });
+ *   return (
+ *     <>
+ *       <button onClick={register}>Go Pro</button>
+ *       {paywall && (
+ *         <MyPaywall
+ *           products={paywall.state.products}
+ *           busy={paywall.state.transaction.phase === "purchasing"}
+ *           onBuy={paywall.controller.buy}
+ *           onClose={paywall.controller.close}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ */
+export declare const useCustomPaywall: (opts: UseCustomPaywallOptions) => UseCustomPaywallResult;
+export declare const useSuperwallEvent: <K extends keyof AllSuperwallEvents>(type: K, listener: (event: SuperwallCustomEvent<K>) => void) => void;
+export declare const useDelegate: (delegate: SuperwallDelegate | null) => void;

package/dist/hooks.js

@@ -0,0 +1,231 @@
+// React hooks — sugar over the public `Superwall` instance + `Readable<T>`.
+// Per API.md §9.3.
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useSuperwallContext } from "./provider.js";
+// ---------------------------------------------------------------------------
+// useSuperwall — raw instance access
+// ---------------------------------------------------------------------------
+export const useSuperwall = () => useSuperwallContext();
+// ---------------------------------------------------------------------------
+// useSignal — bridge `Readable<T>` to React via useSyncExternalStore
+// ---------------------------------------------------------------------------
+/**
+ * Subscribe to a `Readable<T>` and re-render on change. Stores the signal
+ * in a ref so an unstable `signal` identity per render doesn't cause
+ * `useSyncExternalStore` to re-subscribe on every render (which would
+ * spin into an infinite re-render loop). The ref always points at the
+ * latest signal; subscribe + getSnapshot read through it.
+ */
+export const useSignal = (signal) => {
+    const ref = useRef(signal);
+    ref.current = signal;
+    const subscribe = useCallback((onChange) => ref.current.subscribe(() => onChange()), []);
+    const getSnapshot = useCallback(() => ref.current.value, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+export const useUser = () => {
+    const sw = useSuperwall();
+    return {
+        id: useSignal(sw.user.id),
+        aliasId: useSignal(sw.user.aliasId),
+        effectiveId: useSignal(sw.user.effectiveId),
+        isLoggedIn: useSignal(sw.user.isLoggedIn),
+        attributes: useSignal(sw.user.attributes),
+        integrationAttributes: useSignal(sw.user.integrationAttributes),
+        subscriptionStatus: useSignal(sw.subscriptionStatus),
+        customerInfo: useSignal(sw.customerInfo),
+        entitlements: useSignal(sw.entitlements.active),
+        identify: sw.user.identify,
+        signOut: sw.user.signOut,
+        setAttributes: sw.user.setAttributes,
+        setIntegrationAttribute: sw.user.setIntegrationAttribute,
+        setIntegrationAttributes: sw.user.setIntegrationAttributes,
+    };
+};
+/**
+ * Returns a `register` function bound to the active Superwall + a `state`
+ * reflecting the latest placement outcome from THIS hook's calls. Handler
+ * callbacks fire alongside the global delegate. State is local to the
+ * hook (one component's state, not the SDK's).
+ */
+export const usePlacement = (handler) => {
+    const sw = useSuperwall();
+    const [state, setState] = useState({ type: "idle" });
+    // Latest-handler ref so the user can rely on closure-captured values
+    // without re-binding `register` on every render.
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const register = useCallback(async (args) => {
+        const r = await sw.register({
+            ...args,
+            handler: {
+                onPresent: (info) => {
+                    setState({ type: "presented", info });
+                    try {
+                        handlerRef.current?.onPresent?.(info);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                },
+                onDismiss: (info, result) => {
+                    setState({ type: "dismissed", info, result });
+                    try {
+                        handlerRef.current?.onDismiss?.(info, result);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                },
+                onError: (error) => {
+                    setState({ type: "error", error });
+                    try {
+                        handlerRef.current?.onError?.(error);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                },
+                onSkip: (reason) => {
+                    setState({ type: "skipped", reason });
+                    try {
+                        handlerRef.current?.onSkip?.(reason);
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                },
+            },
+        });
+        return r;
+    }, [sw]);
+    return { register, state };
+};
+/**
+ * React primitive for custom (developer-rendered) paywalls — the web analogue
+ * of Android's `SuperwallCustomPaywall`. You own the UI; the SDK runs the
+ * trigger pipeline, resolves products, fires identical lifecycle events, and
+ * hands you a controller. Render `paywall` when it's non-null; drive
+ * `paywall.controller.buy / restore / close` from your buttons.
+ *
+ *   const { register, paywall } = useCustomPaywall({ placement: "home" });
+ *   return (
+ *     <>
+ *       <button onClick={register}>Go Pro</button>
+ *       {paywall && (
+ *         <MyPaywall
+ *           products={paywall.state.products}
+ *           busy={paywall.state.transaction.phase === "purchasing"}
+ *           onBuy={paywall.controller.buy}
+ *           onClose={paywall.controller.close}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ */
+export const useCustomPaywall = (opts) => {
+    const sw = useSuperwall();
+    const [paywall, setPaywall] = useState(null);
+    // Latest-opts ref so `register` stays stable but reads fresh callbacks.
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const register = useCallback(() => {
+        const o = optsRef.current;
+        return sw.register({
+            placement: o.placement,
+            ...(o.params !== undefined && { params: o.params }),
+            ...(o.feature !== undefined && { feature: o.feature }),
+            handler: {
+                onPresent: (info) => {
+                    try {
+                        optsRef.current.onPresent?.(info);
+                    }
+                    catch { /* swallow */ }
+                },
+                onDismiss: (info, result) => {
+                    try {
+                        optsRef.current.onDismiss?.(info, result);
+                    }
+                    catch { /* swallow */ }
+                },
+                onError: (error) => {
+                    try {
+                        optsRef.current.onError?.(error);
+                    }
+                    catch { /* swallow */ }
+                },
+                onSkip: (reason) => {
+                    try {
+                        optsRef.current.onSkip?.(reason);
+                    }
+                    catch { /* swallow */ }
+                },
+            },
+            // The renderer bridges core's reactive state into React state. Core
+            // calls it once on present; we subscribe (fires sync) and mirror each
+            // update into component state. Teardown clears the mount on dismiss.
+            paywall: ({ state, controller }) => {
+                const unsubscribe = state.subscribe((s) => {
+                    setPaywall({ state: s, controller });
+                });
+                return () => {
+                    unsubscribe();
+                    setPaywall(null);
+                };
+            },
+        });
+    }, [sw]);
+    return { register, paywall };
+};
+// ---------------------------------------------------------------------------
+// useSuperwallEvent — typed addEventListener with auto-cleanup
+// ---------------------------------------------------------------------------
+export const useSuperwallEvent = (type, listener) => {
+    const sw = useSuperwall();
+    // Latest-listener ref so the user can capture fresh closures without
+    // re-attaching the listener every render.
+    const listenerRef = useRef(listener);
+    listenerRef.current = listener;
+    useEffect(() => {
+        const ac = new AbortController();
+        sw.events.addEventListener(type, (e) => listenerRef.current(e), { signal: ac.signal });
+        return () => ac.abort();
+    }, [sw, type]);
+};
+const delegateStacks = new WeakMap();
+const applyTop = (sw) => {
+    const stack = delegateStacks.get(sw) ?? [];
+    const top = stack.length === 0 ? null : (stack[stack.length - 1].delegate);
+    sw.setDelegate(top);
+};
+export const useDelegate = (delegate) => {
+    const sw = useSuperwall();
+    const ref = useRef(delegate);
+    ref.current = delegate;
+    useEffect(() => {
+        const id = Symbol("useDelegate");
+        // Always read latest delegate from the ref so callbacks see the current
+        // closure values without re-mounting.
+        const wrapped = ref.current === null
+            ? null
+            : new Proxy({}, {
+                get(_t, prop) {
+                    const d = ref.current;
+                    return d ? d[prop] : undefined;
+                },
+            });
+        const stack = delegateStacks.get(sw) ?? [];
+        stack.push({ id, delegate: wrapped });
+        delegateStacks.set(sw, stack);
+        applyTop(sw);
+        return () => {
+            const current = delegateStacks.get(sw) ?? [];
+            const next = current.filter((e) => e.id !== id);
+            if (next.length === 0)
+                delegateStacks.delete(sw);
+            else
+                delegateStacks.set(sw, next);
+            applyTop(sw);
+        };
+    }, [sw]);
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { SDK_VERSION } from "@superwall/paywalls-js";
+export { SuperwallProvider, type SuperwallProviderProps, useSuperwallContext, } from "./provider.js";
+export { useSuperwall, useSignal, useUser, usePlacement, useCustomPaywall, useSuperwallEvent, useDelegate, type UseUserResult, type UsePlacementResult, type UseCustomPaywallOptions, type UseCustomPaywallResult, type CustomPaywallMountSnapshot, type PaywallState, type PaywallPresentationHandlerHooks, } from "./hooks.js";
+export { SuperwallPaywall, type SuperwallPaywallProps, } from "./SuperwallPaywall.js";
+export * from "@superwall/paywalls-js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// @superwall/paywalls-react — React 19 bindings for the Superwall Web SDK.
+// See /Users/ianrumac/Workspace/Superwall/Superwall-Web/API.md §9.
+export { SDK_VERSION } from "@superwall/paywalls-js";
+export { SuperwallProvider, useSuperwallContext, } from "./provider.js";
+export { useSuperwall, useSignal, useUser, usePlacement, useCustomPaywall, useSuperwallEvent, useDelegate, } from "./hooks.js";
+export { SuperwallPaywall, } from "./SuperwallPaywall.js";
+// Re-export everything public from paywalls-js so React consumers don't
+// need to depend on both packages directly. Tree-shakeable per ESM rules.
+export * from "@superwall/paywalls-js";

package/dist/provider.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import { type CreateSuperwallOptions, type Superwall } from "@superwall/paywalls-js";
+/** Test-only — dispose every registered instance and clear the registry. */
+export declare const _resetProviderRegistry: () => void;
+export interface SuperwallProviderProps extends CreateSuperwallOptions {
+    children: ReactNode;
+}
+export declare const SuperwallProvider: ({ children, ...opts }: SuperwallProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const useSuperwallContext: () => Superwall;

package/dist/provider.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// `<SuperwallProvider>` — constructs a `Superwall` instance on mount and
+// exposes it via React Context. Per API.md §9.1.
+//
+// HMR / Fast Refresh resilient (normative §9.1): the Provider holds the
+// instance in a module-level registry keyed by `apiKey`. On unmount it
+// disposes; on re-mount with the same `apiKey` (e.g. dev-server hot
+// reload) it reuses the existing instance instead of building a new one,
+// so iframes don't leak and event listeners don't stack.
+//
+// SSR-safe: on the server, `createSuperwall` is called with whatever
+// identity seed the consumer passes; rendered children are eager (don't
+// gate with `use(sw.ready)` server-side per API.md §9.2).
+import { createContext, useContext, useMemo, } from "react";
+import { createSuperwall, } from "@superwall/paywalls-js";
+const SuperwallContext = createContext(null);
+// ---------------------------------------------------------------------------
+// HMR-resilient registry — instances live for the page's lifetime.
+//
+// Production: a host app has one Provider per apiKey, mounted once, never
+// unmounted until page navigation. Disposing on unmount is unnecessary
+// and fights HMR (Fast Refresh tears down + re-mounts; the iframe and
+// listeners would leak if we re-created the instance each time). Memory
+// "leak" of one Superwall instance per apiKey for the page's lifetime is
+// the intended trade-off.
+//
+// Tests use `_resetProviderRegistry()` between cases to avoid leakage.
+// ---------------------------------------------------------------------------
+const registry = new Map();
+const acquire = (apiKey, opts) => {
+    const existing = registry.get(apiKey);
+    if (existing)
+        return existing;
+    const sw = createSuperwall(opts);
+    registry.set(apiKey, sw);
+    return sw;
+};
+/** Test-only — dispose every registered instance and clear the registry. */
+export const _resetProviderRegistry = () => {
+    for (const sw of registry.values()) {
+        void sw.dispose();
+    }
+    registry.clear();
+};
+export const SuperwallProvider = ({ children, ...opts }) => {
+    // Acquire the registry-cached instance for this apiKey (first call
+    // creates; subsequent calls reuse — see registry comment above).
+    // `useMemo` keyed by apiKey is sufficient: changing `apiKey` swaps the
+    // context value to the next instance; other config props are ignored
+    // post-mount (config changes don't reconfigure the SDK in v0).
+    const sw = useMemo(() => acquire(opts.apiKey, opts), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [opts.apiKey]);
+    return (_jsx(SuperwallContext.Provider, { value: sw, children: children }));
+};
+// ---------------------------------------------------------------------------
+// Context consumer
+// ---------------------------------------------------------------------------
+export const useSuperwallContext = () => {
+    const sw = useContext(SuperwallContext);
+    if (sw === null) {
+        throw new Error("useSuperwall (or its callers) must be used inside <SuperwallProvider>");
+    }
+    return sw;
+};

package/package.json

@@ -1,29 +1,43 @@
 {
   "name": "@superwall/paywalls-react",
-  "version": "0.2.0",
+  "version": "0.2.5",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/superwall/Superwall-Web.git",
+    "directory": "packages/paywalls-react"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "@superwall/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "scripts": {
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "build": "echo 'no-op for v0; consumers import .ts directly via Bun/Vite/Next ESM'",
-    "clean": "rm -rf node_modules .turbo *.tsbuildinfo"
+    "build": "bun run ../../scripts/build-package.ts",
+    "clean": "rm -rf dist node_modules .turbo *.tsbuildinfo"
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "@superwall/paywalls-js": "^0.2.0"
+    "@superwall/paywalls-js": "^0.2.5"
   },
   "dependencies": {
-    "@superwall/paywalls-js": "^0.2.0"
+    "@superwall/paywalls-js": "^0.2.5"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",

package/.turbo/turbo-build.log

@@ -1,3 +0,0 @@
-
-$ echo 'no-op for v0; consumers import .ts directly via Bun/Vite/Next ESM'
-no-op for v0; consumers import .ts directly via Bun/Vite/Next ESM