@superwall/paywalls-react 0.1.5 → 0.2.1

package/src/hooks.ts

@@ -1,368 +0,0 @@
-// React hooks — sugar over the public `Superwall` instance + `Readable<T>`.
-// Per API.md §9.3.
-
-import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
-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";
-import { useSuperwallContext } from "./provider.tsx";
-
-// ---------------------------------------------------------------------------
-// useSuperwall — raw instance access
-// ---------------------------------------------------------------------------
-
-export const useSuperwall = (): Superwall => 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 = <T,>(signal: Readable<T>): T => {
-  const ref = useRef(signal);
-  ref.current = signal;
-  const subscribe = useCallback(
-    (onChange: () => void) => ref.current.subscribe(() => onChange()),
-    [],
-  );
-  const getSnapshot = useCallback(() => ref.current.value, []);
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-};
-
-// ---------------------------------------------------------------------------
-// useUser — flat view of the user namespace + bound methods
-// ---------------------------------------------------------------------------
-
-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 const useUser = (): UseUserResult => {
-  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,
-  };
-};
-
-// ---------------------------------------------------------------------------
-// usePlacement — per-component register + lifecycle state
-// ---------------------------------------------------------------------------
-
-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 const usePlacement = (
-  handler?: PaywallPresentationHandlerHooks,
-): UsePlacementResult => {
-  const sw = useSuperwall();
-  const [state, setState] = useState<PaywallState>({ 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: RegisterPlacementArgs): Promise<RegisterPlacementResult> => {
-      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 */
-            }
-          },
-        },
-      });
-      // For cases where the SDK returned a non-presented result without
-      // firing handler callbacks (e.g. `entitled`), reflect that in state.
-      if (r.type === "entitled") {
-        setState({ type: "idle" });
-      }
-      return r;
-    },
-    [sw],
-  );
-
-  return { register, state };
-};
-
-// ---------------------------------------------------------------------------
-// useCustomPaywall — render your own paywall UI through register()
-// ---------------------------------------------------------------------------
-
-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 const useCustomPaywall = (
-  opts: UseCustomPaywallOptions,
-): UseCustomPaywallResult => {
-  const sw = useSuperwall();
-  const [paywall, setPaywall] = useState<CustomPaywallMountSnapshot | null>(null);
-
-  // Latest-opts ref so `register` stays stable but reads fresh callbacks.
-  const optsRef = useRef(opts);
-  optsRef.current = opts;
-
-  const register = useCallback((): Promise<RegisterPlacementResult> => {
-    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 = <K extends keyof AllSuperwallEvents>(
-  type: K,
-  listener: (event: SuperwallCustomEvent<K>) => void,
-): void => {
-  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]);
-};
-
-// ---------------------------------------------------------------------------
-// useDelegate — install a global SuperwallDelegate for the lifetime of the
-// component. Multiple hooks can mount concurrently: each pushes onto a
-// per-instance stack. The active delegate is always the top; unmount pops
-// only the owner that pushed and re-installs whatever was below.
-// ---------------------------------------------------------------------------
-
-interface DelegateEntry {
-  readonly id: symbol;
-  readonly delegate: SuperwallDelegate | null;
-}
-
-const delegateStacks = new WeakMap<Superwall, DelegateEntry[]>();
-
-const applyTop = (sw: Superwall): void => {
-  const stack = delegateStacks.get(sw) ?? [];
-  const top = stack.length === 0 ? null : (stack[stack.length - 1]!.delegate);
-  sw.setDelegate(top);
-};
-
-export const useDelegate = (delegate: SuperwallDelegate | null): void => {
-  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: SuperwallDelegate | null =
-      ref.current === null
-        ? null
-        : new Proxy({} as SuperwallDelegate, {
-            get(_t, prop: string) {
-              const d = ref.current;
-              return d ? (d as Record<string, unknown>)[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/src/index.test.ts

@@ -1,7 +0,0 @@
-import { test, expect } from "bun:test";
-import { SDK_VERSION } from "./index.ts";
-
-test("re-exports SDK_VERSION from @superwall/paywalls-js", () => {
-  expect(typeof SDK_VERSION).toBe("string");
-  expect(SDK_VERSION).toMatch(/^\d+\.\d+\.\d+/);
-});

package/src/index.ts

@@ -1,31 +0,0 @@
-// @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,
-  type SuperwallProviderProps,
-  useSuperwallContext,
-} from "./provider.tsx";
-
-export {
-  useSuperwall,
-  useSignal,
-  useUser,
-  usePlacement,
-  useCustomPaywall,
-  useSuperwallEvent,
-  useDelegate,
-  type UseUserResult,
-  type UsePlacementResult,
-  type UseCustomPaywallOptions,
-  type UseCustomPaywallResult,
-  type CustomPaywallMountSnapshot,
-  type PaywallState,
-  type PaywallPresentationHandlerHooks,
-} from "./hooks.ts";
-
-// 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/src/provider.test.tsx

@@ -1,102 +0,0 @@
-import { test, expect, beforeEach } from "bun:test";
-import { act, render } from "@testing-library/react";
-import { useSuperwall } from "./hooks.ts";
-import {
-  _resetProviderRegistry,
-  SuperwallProvider,
-} from "./provider.tsx";
-
-const noopFetch = (() =>
-  Promise.resolve(new Response("", { status: 204 }))) as unknown as typeof fetch;
-
-beforeEach(() => {
-  _resetProviderRegistry();
-});
-
-test("SuperwallProvider provides a Superwall instance via context", async () => {
-  let captured: ReturnType<typeof useSuperwall> | null = null;
-  const Probe = () => {
-    captured = useSuperwall();
-    return null;
-  };
-
-  await act(async () => {
-    render(
-      <SuperwallProvider apiKey="pk_test" fetch={noopFetch}>
-        <Probe />
-      </SuperwallProvider>,
-    );
-  });
-
-  expect(captured).not.toBeNull();
-  expect(captured!.apiKey).toBe("pk_test");
-});
-
-test("useSuperwall outside <SuperwallProvider> throws a clear error", () => {
-  const Probe = () => {
-    useSuperwall();
-    return null;
-  };
-  expect(() => render(<Probe />)).toThrow(/SuperwallProvider/);
-});
-
-test("registry reuses the instance across re-mounts with the same apiKey (HMR)", async () => {
-  let first: ReturnType<typeof useSuperwall> | null = null;
-  let second: ReturnType<typeof useSuperwall> | null = null;
-
-  const Probe = ({ slot }: { slot: 1 | 2 }) => {
-    const sw = useSuperwall();
-    if (slot === 1) first = sw;
-    else second = sw;
-    return null;
-  };
-
-  let view: ReturnType<typeof render>;
-  await act(async () => {
-    view = render(
-      <SuperwallProvider apiKey="pk_hmr" fetch={noopFetch}>
-        <Probe slot={1} />
-      </SuperwallProvider>,
-    );
-  });
-  // Unmount, re-mount with same key — registry should hand back the same instance.
-  await act(async () => {
-    view!.unmount();
-    render(
-      <SuperwallProvider apiKey="pk_hmr" fetch={noopFetch}>
-        <Probe slot={2} />
-      </SuperwallProvider>,
-    );
-  });
-
-  expect(first).not.toBeNull();
-  expect(second).toBe(first); // same instance
-});
-
-test("different apiKeys produce different instances", async () => {
-  let a: ReturnType<typeof useSuperwall> | null = null;
-  let b: ReturnType<typeof useSuperwall> | null = null;
-  const Probe = ({ tag }: { tag: "a" | "b" }) => {
-    const sw = useSuperwall();
-    if (tag === "a") a = sw;
-    else b = sw;
-    return null;
-  };
-
-  await act(async () => {
-    render(
-      <>
-        <SuperwallProvider apiKey="pk_a" fetch={noopFetch}>
-          <Probe tag="a" />
-        </SuperwallProvider>
-        <SuperwallProvider apiKey="pk_b" fetch={noopFetch}>
-          <Probe tag="b" />
-        </SuperwallProvider>
-      </>,
-    );
-  });
-
-  expect(a).not.toBeNull();
-  expect(b).not.toBeNull();
-  expect(a).not.toBe(b);
-});

package/src/provider.tsx

@@ -1,99 +0,0 @@
-// `<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,
-  type ReactNode,
-} from "react";
-import {
-  createSuperwall,
-  type CreateSuperwallOptions,
-  type Superwall,
-} from "@superwall/paywalls-js";
-
-const SuperwallContext = createContext<Superwall | null>(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<string, Superwall>();
-
-const acquire = (apiKey: string, opts: CreateSuperwallOptions): Superwall => {
-  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 = (): void => {
-  for (const sw of registry.values()) {
-    void sw.dispose();
-  }
-  registry.clear();
-};
-
-// ---------------------------------------------------------------------------
-// Provider
-// ---------------------------------------------------------------------------
-
-export interface SuperwallProviderProps extends CreateSuperwallOptions {
-  children: ReactNode;
-}
-
-export const SuperwallProvider = ({
-  children,
-  ...opts
-}: SuperwallProviderProps) => {
-  // 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 (
-    <SuperwallContext.Provider value={sw}>{children}</SuperwallContext.Provider>
-  );
-};
-
-// ---------------------------------------------------------------------------
-// Context consumer
-// ---------------------------------------------------------------------------
-
-export const useSuperwallContext = (): Superwall => {
-  const sw = useContext(SuperwallContext);
-  if (sw === null) {
-    throw new Error(
-      "useSuperwall (or its callers) must be used inside <SuperwallProvider>",
-    );
-  }
-  return sw;
-};

package/test-setup-dom.ts

@@ -1,11 +0,0 @@
-// Bun preload — registers happy-dom so React 19 + @testing-library/react
-// run in a browser-shaped environment.
-
-import { GlobalRegistrator } from "@happy-dom/global-registrator";
-
-GlobalRegistrator.register({ url: "https://app.example.test" });
-
-// `IS_REACT_ACT_ENVIRONMENT` is the React 19 marker that quiets "act"
-// warnings during state updates from outside `act(...)`. Setting it
-// globally is the recommended pattern for non-React-Native test runners.
-(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "jsx": "react-jsx",
-    "lib": ["ESNext", "DOM"]
-  },
-  "include": ["src/**/*"]
-}