@crediball/react 0.2.0 → 0.3.1

package/dist/CrediballProvider.d.ts

@@ -16,6 +16,10 @@ export interface CrediballProviderProps {
      * `{ code: "insufficient_credits" }`) from any fetch() call and open the paywall
      * automatically — no per-call wiring. Defaults to true. Set false to only open
      * the paywall manually via useCrediball().showPaywall().
+     *
+     * Note: this only intercepts responses with HTTP 402. Streaming (SSE) routes that
+     * surface credit errors as stream events will not be caught automatically — call
+     * showPaywall() manually from your SSE error handler in those cases.
      */
     watchFetch?: boolean;
     /** Allow a free-form amount entry in the paywall. */
@@ -30,7 +34,11 @@ export interface CrediballProviderProps {
     accentColor?: string;
 }
 interface CrediballContextValue {
-    /** Open the paywall modal. */
+    /**
+     * Open the paywall modal. Always safe to call — never guard with "already shown"
+     * state. Calling while already open is a no-op; dismissing via "Not now" does not
+     * prevent the next showPaywall() call from reopening it.
+     */
     showPaywall: () => void;
     /** Close the paywall modal. */
     hidePaywall: () => void;
@@ -47,8 +55,17 @@ interface CrediballContextValue {
  * Whenever any request returns 402 `insufficient_credits` (your server forwarding
  * Crediball's error), the paywall appears automatically — no extra code per call.
  * You can also open it yourself with useCrediball().showPaywall().
+ *
+ * For SSE/streaming routes: the 402 is surfaced as a stream event, not an HTTP status,
+ * so watchFetch won't catch it. Call showPaywall() manually from your SSE error handler.
  */
 export declare function CrediballProvider({ children, amounts, onTopup, watchFetch, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, }: CrediballProviderProps): import("react").JSX.Element;
-/** Access the paywall controls from anywhere inside <CrediballProvider>. */
+/**
+ * Access the paywall controls from anywhere inside <CrediballProvider>.
+ *
+ * Important: showPaywall() is always safe to call — never add a "paywallAlreadyShown"
+ * guard around it. Dismissing the modal ("Not now") does not prevent future calls
+ * from reopening it. Call showPaywall() unconditionally on every InsufficientCreditsError.
+ */
 export declare function useCrediball(): CrediballContextValue;
 export {};

package/dist/CrediballProvider.js

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
 import { PaywallModal } from "./PaywallModal";
+import { subscribeFetchWatcher } from "./fetchWatcher";
 const CrediballContext = createContext(null);
 /**
  * Pattern B, automated. Wrap your app once:
@@ -13,36 +14,21 @@ const CrediballContext = createContext(null);
  * Whenever any request returns 402 `insufficient_credits` (your server forwarding
  * Crediball's error), the paywall appears automatically — no extra code per call.
  * You can also open it yourself with useCrediball().showPaywall().
+ *
+ * For SSE/streaming routes: the 402 is surfaced as a stream event, not an HTTP status,
+ * so watchFetch won't catch it. Call showPaywall() manually from your SSE error handler.
  */
 export function CrediballProvider({ children, amounts = [5, 10, 20], onTopup, watchFetch = true, allowCustom = false, customMin, customMax, currencySymbol = "€", title, description, accentColor, }) {
     const [open, setOpen] = useState(false);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
-    // Auto-open on any 402 insufficient_credits response, app-wide. We patch
-    // window.fetch and inspect a *clone* so the original response is untouched.
+    // Keep a ref so the fetch-watcher closure always calls the latest version.
+    const showPaywallRef = useRef(showPaywall);
+    showPaywallRef.current = showPaywall;
     useEffect(() => {
-        if (!watchFetch || typeof window === "undefined")
+        if (!watchFetch)
             return;
-        const original = window.fetch;
-        window.fetch = async (...args) => {
-            const res = await original(...args);
-            if (res.status === 402) {
-                res
-                    .clone()
-                    .json()
-                    .then((body) => {
-                    if (body && body.code === "insufficient_credits")
-                        setOpen(true);
-                })
-                    .catch(() => {
-                    /* non-JSON 402: ignore */
-                });
-            }
-            return res;
-        };
-        return () => {
-            window.fetch = original;
-        };
+        return subscribeFetchWatcher(() => showPaywallRef.current());
     }, [watchFetch]);
     const ctx = useMemo(() => ({ showPaywall, hidePaywall, open }), [showPaywall, hidePaywall, open]);
     async function handleAdd(amount) {
@@ -55,7 +41,13 @@ export function CrediballProvider({ children, amounts = [5, 10, 20], onTopup, wa
     }
     return (_jsxs(CrediballContext.Provider, { value: ctx, children: [children, _jsx(PaywallModal, { open: open, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: allowCustom, customMin: customMin, customMax: customMax, currencySymbol: currencySymbol, title: title, description: description, accentColor: accentColor })] }));
 }
-/** Access the paywall controls from anywhere inside <CrediballProvider>. */
+/**
+ * Access the paywall controls from anywhere inside <CrediballProvider>.
+ *
+ * Important: showPaywall() is always safe to call — never add a "paywallAlreadyShown"
+ * guard around it. Dismissing the modal ("Not now") does not prevent future calls
+ * from reopening it. Call showPaywall() unconditionally on every InsufficientCreditsError.
+ */
 export function useCrediball() {
     const ctx = useContext(CrediballContext);
     if (!ctx) {

package/dist/PaywallModal.js

@@ -65,7 +65,7 @@ export function PaywallModal({ open, packages, onSelectPackage, amounts = [5, 10
     return (_jsx("div", { role: "dialog", "aria-modal": "true", style: {
             position: "fixed",
             inset: 0,
-            zIndex: 1000,
+            zIndex: 2147483647,
             display: "flex",
             alignItems: "center",
             justifyContent: "center",

package/dist/fetchWatcher.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Module-level singleton that patches window.fetch once and fans out to all
+ * registered listeners (from CrediballProvider and/or usePaywall). Only one
+ * fetch patch exists at a time regardless of how many components subscribe.
+ * Reference-counted: the patch is removed when the last listener unsubscribes.
+ */
+type Listener = () => void;
+/**
+ * Subscribe to insufficient-credits 402 events detected in window.fetch.
+ * Returns an unsubscribe function — call it in your useEffect cleanup.
+ */
+export declare function subscribeFetchWatcher(listener: Listener): () => void;
+export {};

package/dist/fetchWatcher.js

@@ -0,0 +1,57 @@
+/**
+ * Module-level singleton that patches window.fetch once and fans out to all
+ * registered listeners (from CrediballProvider and/or usePaywall). Only one
+ * fetch patch exists at a time regardless of how many components subscribe.
+ * Reference-counted: the patch is removed when the last listener unsubscribes.
+ */
+let _original = null;
+const _listeners = new Set();
+function install() {
+    if (typeof window === "undefined" || _original !== null)
+        return;
+    _original = window.fetch;
+    window.fetch = async (...args) => {
+        const res = await _original(...args);
+        if (res.status === 402) {
+            res
+                .clone()
+                .json()
+                .then((body) => {
+                if (body != null &&
+                    typeof body === "object" &&
+                    body.code === "insufficient_credits") {
+                    _listeners.forEach((fn) => fn());
+                }
+            })
+                .catch(() => {
+                // Non-JSON 402. Fire listeners anyway — a 402 from the app's own API
+                // route is almost certainly a credit shortage. Set watchFetch=false
+                // and call trigger() manually if your app uses 402 for other purposes.
+                _listeners.forEach((fn) => fn());
+            });
+        }
+        return res;
+    };
+}
+function uninstall() {
+    if (typeof window === "undefined" || _original === null)
+        return;
+    window.fetch = _original;
+    _original = null;
+}
+/**
+ * Subscribe to insufficient-credits 402 events detected in window.fetch.
+ * Returns an unsubscribe function — call it in your useEffect cleanup.
+ */
+export function subscribeFetchWatcher(listener) {
+    if (typeof window === "undefined")
+        return () => { };
+    if (_listeners.size === 0)
+        install();
+    _listeners.add(listener);
+    return () => {
+        _listeners.delete(listener);
+        if (_listeners.size === 0)
+            uninstall();
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { CreditsBadge, type CreditsBadgeProps } from "./CreditsBadge";
-export { PaywallModal, type PaywallModalProps } from "./PaywallModal";
+export { PaywallModal, type PaywallModalProps, type PackageOption } from "./PaywallModal";
 export { CreditIndicator, type CreditIndicatorProps } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, type CrediballProviderProps, } from "./CrediballProvider";
+export { usePaywall, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
 export { tokens, type CrediballThemeOverrides } from "./theme";

package/dist/index.js

@@ -4,4 +4,5 @@ export { CreditsBadge } from "./CreditsBadge";
 export { PaywallModal } from "./PaywallModal";
 export { CreditIndicator } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, } from "./CrediballProvider";
+export { usePaywall, } from "./usePaywall";
 export { tokens } from "./theme";

package/dist/usePaywall.d.ts

@@ -0,0 +1,71 @@
+import { type ReactElement } from "react";
+import { type PaywallModalProps, type PackageOption } from "./PaywallModal";
+export type UsePaywallProps = Pick<PaywallModalProps, "amounts" | "amountPrefix" | "packages" | "allowCustom" | "customMin" | "customMax" | "currencySymbol" | "title" | "description" | "accentColor" | "balance" | "balanceRate" | "currency"> & {
+    /** Called when the user picks a preset or custom top-up amount. */
+    onTopup?: (amount: number) => void | Promise<void>;
+    /** Called when the user picks a package from `packages`. */
+    onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    /**
+     * Auto-detect HTTP 402 `insufficient_credits` responses from any fetch() call
+     * and open the paywall automatically. Defaults to true.
+     *
+     * Set to false if your app uses <CrediballProvider> (it already watches fetch)
+     * or if you want to trigger the paywall exclusively via trigger().
+     *
+     * Note: SSE/streaming routes surface credit errors as stream events (HTTP 200),
+     * not HTTP 402 — call trigger() manually from your stream error handler.
+     */
+    watchFetch?: boolean;
+};
+export interface UsePaywallResult {
+    /**
+     * Open the paywall modal. Calling this is ALWAYS safe — it opens the modal
+     * whether or not it was previously dismissed. Never add a "paywallAlreadyShown"
+     * guard around this: it is idempotent (calling while already open is a no-op)
+     * and every InsufficientCreditsError should call it unconditionally.
+     */
+    trigger: () => void;
+    /** Close the paywall without a purchase. The next trigger() call will re-open it. */
+    dismiss: () => void;
+    /** Whether the paywall is currently open. */
+    isOpen: boolean;
+    /**
+     * Drop this into your JSX tree — it renders the modal when open.
+     * It must be rendered for the paywall to appear; place it near the root of
+     * the component where you call `trigger()`.
+     *
+     *   return (
+     *     <div>
+     *       <button onClick={generate}>Generate</button>
+     *       {paywall}
+     *     </div>
+     *   );
+     */
+    paywall: ReactElement;
+}
+/**
+ * Manages a Crediball paywall modal with a simple, misuse-proof API.
+ *
+ * The key rule: call `trigger()` unconditionally whenever you catch an
+ * InsufficientCreditsError — never guard it with "already shown" state.
+ * Dismissing the modal ("Not now") does NOT prevent the next trigger() from
+ * reopening it. This is what makes the paywall reliably reappear on retry.
+ *
+ *   const { trigger, paywall } = usePaywall({
+ *     amounts: [5, 10, 20],
+ *     onTopup: async (eur) => checkout(eur),
+ *   });
+ *
+ *   try {
+ *     const page = await meter.wrapMeteredAction(userId, "generate_page", async () => {
+ *       const res = await streamAI(prompt);
+ *       return { result: res, tokens: res.usage.totalTokens };
+ *     });
+ *   } catch (e) {
+ *     if (e instanceof InsufficientCreditsError) trigger(); // always call — no guard
+ *     else throw e;
+ *   }
+ *
+ *   return <div>...<button onClick={generate}>Generate</button>...{paywall}</div>;
+ */
+export declare function usePaywall({ amounts, amountPrefix, packages, onTopup, onSelectPackage, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, balance, balanceRate, currency, watchFetch, }?: UsePaywallProps): UsePaywallResult;

package/dist/usePaywall.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { PaywallModal } from "./PaywallModal";
+import { subscribeFetchWatcher } from "./fetchWatcher";
+/**
+ * Manages a Crediball paywall modal with a simple, misuse-proof API.
+ *
+ * The key rule: call `trigger()` unconditionally whenever you catch an
+ * InsufficientCreditsError — never guard it with "already shown" state.
+ * Dismissing the modal ("Not now") does NOT prevent the next trigger() from
+ * reopening it. This is what makes the paywall reliably reappear on retry.
+ *
+ *   const { trigger, paywall } = usePaywall({
+ *     amounts: [5, 10, 20],
+ *     onTopup: async (eur) => checkout(eur),
+ *   });
+ *
+ *   try {
+ *     const page = await meter.wrapMeteredAction(userId, "generate_page", async () => {
+ *       const res = await streamAI(prompt);
+ *       return { result: res, tokens: res.usage.totalTokens };
+ *     });
+ *   } catch (e) {
+ *     if (e instanceof InsufficientCreditsError) trigger(); // always call — no guard
+ *     else throw e;
+ *   }
+ *
+ *   return <div>...<button onClick={generate}>Generate</button>...{paywall}</div>;
+ */
+export function usePaywall({ amounts, amountPrefix, packages, onTopup, onSelectPackage, allowCustom, customMin, customMax, currencySymbol, title, description, accentColor, balance, balanceRate, currency, watchFetch = true, } = {}) {
+    const [isOpen, setIsOpen] = useState(false);
+    const trigger = useCallback(() => setIsOpen(true), []);
+    const dismiss = useCallback(() => setIsOpen(false), []);
+    // Keep a ref so the fetch-watcher closure always calls the latest trigger.
+    const triggerRef = useRef(trigger);
+    triggerRef.current = trigger;
+    useEffect(() => {
+        if (!watchFetch)
+            return;
+        return subscribeFetchWatcher(() => triggerRef.current());
+    }, [watchFetch]);
+    const handleTopup = useCallback(async (amount) => {
+        setIsOpen(false);
+        await onTopup?.(amount);
+    }, [onTopup]);
+    const handleSelectPackage = useCallback(async (pkg) => {
+        setIsOpen(false);
+        await onSelectPackage?.(pkg);
+    }, [onSelectPackage]);
+    const paywall = (_jsx(PaywallModal, { open: isOpen, amounts: amounts, amountPrefix: amountPrefix, packages: packages, onAdd: handleTopup, onSelectPackage: handleSelectPackage, onClose: dismiss, allowCustom: allowCustom, customMin: customMin, customMax: customMax, currencySymbol: currencySymbol, title: title, description: description, accentColor: accentColor, balance: balance, balanceRate: balanceRate, currency: currency }));
+    return { trigger, dismiss, isOpen, paywall };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",