@superwall/paywalls-react 0.1.5 → 0.2.0

package/.turbo/turbo-typecheck.log

@@ -1,46 +1,11 @@
 $ tsc --noEmit
-../paywalls-js/src/internal/audience.ts(32,3): error TS2322: Type 'Promise<typeof import("/Users/ianrumac/Workspace/Superwall/Superwall-Web/node_modules/.bun/@superwall+superscript@0.2.5/node_modules/@superwall/superscript/dist/types/browser")>' is not assignable to type 'Promise<{ evaluateWithContext: (input: ExecutionContext, host: SuperscriptHostContext) => string | boolean; }>'.
-  Type 'typeof import("/Users/ianrumac/Workspace/Superwall/Superwall-Web/node_modules/.bun/@superwall+superscript@0.2.5/node_modules/@superwall/superscript/dist/types/browser")' is not assignable to type '{ evaluateWithContext: (input: ExecutionContext, host: SuperscriptHostContext) => string | boolean; }'.
-    The types returned by 'evaluateWithContext(...)' are incompatible between these types.
-      Type 'Promise<string>' is not assignable to type 'string | boolean'.
-../paywalls-js/src/internal/audience.ts(232,18): error TS18047: 'mod' is possibly 'null'.
-../paywalls-js/src/internal/redemption.ts(133,21): error TS2379: Argument of type '{ deviceId: string; appUserId: string | undefined; aliasId: string; codes: { code: string; firstRedemption?: boolean; }[]; }' is not assignable to parameter of type 'RedeemRequest' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Types of property 'appUserId' are incompatible.
-    Type 'string | undefined' is not assignable to type 'string'.
-      Type 'undefined' is not assignable to type 'string'.
-../paywalls-js/src/superwall.ts(947,7): error TS2379: Argument of type 'Effect<void, StorageSetError, StorageService>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'StorageService' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1046,38): error TS2551: Property 'activeSubscriptions' does not exist on type 'CustomerInfo'. Did you mean 'subscriptions'?
-../paywalls-js/src/superwall.ts(1050,11): error TS2375: Type '{ publicApiKey: string; aliasId: string; appUserId: string; vendorId: string; deviceId: string; bundleId: string | undefined; appVersion: string | undefined; isSandbox: boolean; isFirstAppOpen: boolean; ... 6 more ...; activeProducts: any; }' is not assignable to type 'DeviceAttributesInput' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Types of property 'bundleId' are incompatible.
-    Type 'string | undefined' is not assignable to type 'string'.
-      Type 'undefined' is not assignable to type 'string'.
-../paywalls-js/src/superwall.ts(1208,9): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1608,15): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1722,17): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1737,17): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1949,11): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(1969,13): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(2050,11): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(2112,9): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(2303,9): error TS2379: Argument of type 'Effect<void, never, Logger>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'Logger' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(2317,9): error TS2379: Argument of type 'Effect<void, never, EventBus>' is not assignable to parameter of type 'Effect<unknown, unknown, never>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
-  Type 'EventBus' is not assignable to type 'never'.
-../paywalls-js/src/superwall.ts(2392,9): error TS2352: Conversion of type 'Effect<void, never, NetworkService | ConfigService | AssignmentService>' to type 'Effect<void, unknown, never>' may be a mistake because neither type sufficiently overlaps with the other. If this was intentional, convert the expression to 'unknown' first.
-  Type 'NetworkService | ConfigService | AssignmentService' is not comparable to type 'never'.
-    Type 'AssignmentService' is not comparable to type 'never'.
 src/hooks.test.tsx(417,26): error TS2345: Argument of type '{ readonly value: string; subscribe: (run: () => void) => () => void; }' is not assignable to parameter of type 'Readable<string>'.
   Types of property 'subscribe' are incompatible.
     Type '(run: () => void) => () => void' is not assignable to type '(run: (value: string) => void) => () => void'.
       Types of parameters 'run' and 'run' are incompatible.
         Target signature provides too few arguments. Expected 1 or more, but got 0.
 src/hooks.ts(185,11): error TS2367: This comparison appears to be unintentional because the types '"error" | "presented" | "skipped"' and '"entitled"' have no overlap.
+src/SuperwallPaywall.tsx(42,17): error TS2379: Argument of type '{ placement: string; params: PlacementParams | undefined; feature: () => void; handler: { onPresent: (info: PaywallInfo) => void | undefined; onDismiss: (info: PaywallInfo, result: PaywallResult) => void | undefined; onSkip: (reason: PaywallSkippedReason) => void | undefined; onError: (error: Error) => void | undefi...' is not assignable to parameter of type 'RegisterPlacementArgs' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
+  Types of property 'params' are incompatible.
+    Type 'PlacementParams | undefined' is not assignable to type 'PlacementParams'.
+      Type 'undefined' is not assignable to type 'PlacementParams'.

package/README.md

@@ -23,9 +23,29 @@ export function Root() {
 }
 ```
 
-`SuperwallProvider` takes the same config as `createSuperwall`
-(`apiKey`, `storage`, `delegate`, `identity`, `options`).
+`SuperwallProvider` accepts the following props:
 
+| Prop      | Type                | Description                                                                                          | Example                                     |
+|-----------|---------------------|------------------------------------------------------------------------------------------------------|---------------------------------------------|
+| `apiKey`  | `string`            | **Required.** Your Superwall public key.                                                             | `"pk_your_public_key"`                      |
+| `storage` | `StorageAdapter?`   | Optional. Provide a storage layer to customize persistence behavior (defaults to localStorage).       | `myCustomStorage`                           |
+| `delegate`| `SuperwallDelegate?`| Optional. Receives paywall and subscription events (like callbacks for onPresent, onDismiss, etc).   | `myDelegate`                                |
+| `identity`| `{ appUserId?, aliasId?, vendorId? }?` | Optional. Seed identity on configure, e.g. from cookies on SSR hydration. | `{ appUserId: 'abc123' }` |
+| `options` | `object?`           | Optional. Additional options for advanced configuration (see the paywalls-js docs for details).       | `{ networkEnvironment: "release" }`         |
+
+Most apps will only need to provide `apiKey`, but you can pass the optional extras as needed.
+
+```tsx
+<SuperwallProvider
+  apiKey="pk_your_public_key"
+  storage={myCustomStorage}
+  delegate={myDelegate}
+  identity={{ appUserId: "123" }}
+  options={{ networkEnvironment: "release" }}
+>
+  <App />
+</SuperwallProvider>
+```
 ## Placements
 
 ```tsx
@@ -76,6 +96,25 @@ function GoPro() {
 - The placement has no audience match / holdout — feature runs without showing a paywall
 - The user completes a purchase or restore through the paywall
 
+## SuperwallPaywall component
+
+Declarative alternative to `usePlacement`. Calls `register()` on mount and
+renders `children` when the user is entitled — i.e. the feature block fires.
+
+```tsx
+import { SuperwallPaywall } from "@superwall/paywalls-react";
+
+function App() {
+  return (
+    <SuperwallPaywall placement="campaign_trigger" loading={<LoadingSpinner />}>
+      <ProContent />
+    </SuperwallPaywall>
+  );
+}
+```
+
+`loading` renders while the paywall is loading and is swapped out the moment it presents. `children` render once the user is entitled. Pass `inline` to mount the paywall iframe inside the component instead of as a full-viewport overlay. Optional handler props (`onPresent`, `onDismiss`, `onSkip`, `onError`) work the same as in `usePlacement`.
+
 ## Subscription status & user
 
 ```tsx

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@superwall/paywalls-react",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "types": "./src/index.ts",
@@ -17,10 +20,10 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "@superwall/paywalls-js": "^0.1.3"
+    "@superwall/paywalls-js": "^0.2.0"
   },
   "dependencies": {
-    "@superwall/paywalls-js": "^0.1.3"
+    "@superwall/paywalls-js": "^0.2.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.0.0",

package/src/SuperwallPaywall.tsx

@@ -0,0 +1,94 @@
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
+import type { PlacementParams } from "@superwall/paywalls-js";
+import { createBrowserPresenter } from "@superwall/paywalls-js/browser";
+import type { PaywallPresentationHandlerHooks } from "./hooks.ts";
+import { useSuperwall } from "./hooks.ts";
+
+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 function SuperwallPaywall({
+  placement,
+  params,
+  children,
+  loading = null,
+  inline = false,
+  onPresent,
+  onDismiss,
+  onSkip,
+  onError,
+}: SuperwallPaywallProps) {
+  const sw = useSuperwall();
+  const [unlocked, setUnlocked] = useState(false);
+  const [presenting, setPresenting] = useState(false);
+  const containerRef = useRef<HTMLDivElement>(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,
+      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 <>{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 (
+    <div style={{ position: "relative", width: "100%", height: "100%" }}>
+      <div
+        ref={containerRef}
+        style={{ display: presenting ? "block" : "none", width: "100%", height: "100%" }}
+      />
+      {!presenting && (
+        <div style={{ position: "absolute", inset: 0 }}>
+          {loading}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -26,6 +26,11 @@ export {
   type PaywallPresentationHandlerHooks,
 } from "./hooks.ts";
 
+export {
+  SuperwallPaywall,
+  type SuperwallPaywallProps,
+} from "./SuperwallPaywall.tsx";
+
 // 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";