@crediball/react 0.1.0 → 0.3.0

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,8 +1,11 @@
 "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";
 const CrediballContext = createContext(null);
+// Symbol used to mark a patched fetch so double-mount in React Strict Mode (dev)
+// or a second <CrediballProvider> doesn't stack intercepts.
+const CREDIBALL_FETCH_PATCHED = Symbol.for("crediball.fetch.patched");
 /**
  * Pattern B, automated. Wrap your app once:
  *
@@ -13,35 +16,51 @@ 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);
+    // Stable callback refs so the fetch interceptor closure doesn't go stale.
     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.
+    const showPaywallRef = useRef(showPaywall);
+    showPaywallRef.current = showPaywall;
     useEffect(() => {
         if (!watchFetch || typeof window === "undefined")
             return;
+        // If another provider (or a double-invoke from React Strict Mode) already
+        // patched this window.fetch in the same tick, skip — the cleanup will restore.
+        const win = window;
+        if (win[CREDIBALL_FETCH_PATCHED])
+            return;
         const original = window.fetch;
+        win[CREDIBALL_FETCH_PATCHED] = true;
         window.fetch = async (...args) => {
             const res = await original(...args);
             if (res.status === 402) {
+                // Clone so the original response body is still readable by the caller.
                 res
                     .clone()
                     .json()
                     .then((body) => {
-                    if (body && body.code === "insufficient_credits")
-                        setOpen(true);
+                    if (body && body.code === "insufficient_credits") {
+                        showPaywallRef.current();
+                    }
                 })
                     .catch(() => {
-                    /* non-JSON 402: ignore */
+                    // Non-JSON 402 (e.g. Stripe webhook): open paywall anyway since any
+                    // 402 from the app's own API routes is very likely a credit shortage.
+                    // If the app has other 402 uses, set watchFetch=false and call
+                    // showPaywall() manually.
                 });
             }
             return res;
         };
         return () => {
             window.fetch = original;
+            delete win[CREDIBALL_FETCH_PATCHED];
         };
     }, [watchFetch]);
     const ctx = useMemo(() => ({ showPaywall, hidePaywall, open }), [showPaywall, hidePaywall, open]);
@@ -55,7 +74,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.d.ts

@@ -1,13 +1,36 @@
 import { type CSSProperties } from "react";
 import { type CrediballThemeOverrides } from "./theme";
+/** A purchasable credit bundle from the Crediball dashboard (returned by listPackages()). */
+export interface PackageOption {
+    id: string;
+    name: string;
+    price: number;
+    credits: number;
+}
 export interface PaywallModalProps extends CrediballThemeOverrides {
     open: boolean;
-    /** Top-up amounts to offer (host decides the meaning, e.g. euros). */
+    /**
+     * Preferred: pass the packages from `meter.listPackages()` so Crediball can
+     * resolve credits and record revenue automatically when the user checks out.
+     * The modal renders one button per package (e.g. "Starter — €5 / 10 cr").
+     */
+    packages?: PackageOption[];
+    /**
+     * Called when the user selects a package. Use this with `packages` — call
+     * `meter.topup({ userId, packageId: pkg.id })` in your backend. No `amount`
+     * calculation needed; Crediball derives it from the package.
+     */
+    onSelectPackage?: (pkg: PackageOption) => void;
+    /**
+     * Legacy: flat list of euro amounts. Prefer `packages` + `onSelectPackage`.
+     * When both are provided, `packages` takes precedence.
+     */
     amounts?: number[];
-    /** Prefix shown on each button before the amount (default "Add €"). */
+    /** Prefix shown on each legacy amount button (default "Add €"). */
     amountPrefix?: string;
     title?: string;
     description?: string;
+    /** Called when the user clicks a legacy amount button. */
     onAdd?: (amount: number) => void;
     onClose?: () => void;
     /** When true, show a free-form amount field in addition to the preset buttons. */
@@ -29,4 +52,4 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     currency?: string;
     style?: CSSProperties;
 }
-export declare function PaywallModal({ open, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, customMin, customMax, currencySymbol, balance, balanceRate, currency, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;
+export declare function PaywallModal({ open, packages, onSelectPackage, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, customMin, customMax, currencySymbol, balance, balanceRate, currency, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;

package/dist/PaywallModal.js

@@ -17,7 +17,7 @@ function fmtMoney(n, currency) {
         return `${n.toFixed(2)} ${currency}`;
     }
 }
-export function PaywallModal({ open, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", accentColor = tokens.primary, style, }) {
+export function PaywallModal({ open, packages, onSelectPackage, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", accentColor = tokens.primary, style, }) {
     // Stack the top-up buttons one-per-line on narrow (mobile) screens.
     const [narrow, setNarrow] = useState(false);
     const [customValue, setCustomValue] = useState("");
@@ -92,10 +92,12 @@ export function PaywallModal({ open, amounts = [5, 10], amountPrefix = "Add €"
                                 marginBottom: 4,
                             }, children: "Your balance" }), _jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8, flexWrap: "wrap" }, children: [_jsxs("span", { style: { fontSize: 22, fontWeight: 600, color: tokens.ink }, children: [fmtCredits(balance), " credits"] }), balanceRate && balanceRate > 0 ? (_jsxs("span", { style: { fontSize: 13, color: tokens.inkMuted }, children: ["\u2248 ", fmtMoney(balance / balanceRate, currency)] })) : null] })] })), _jsx("h3", { style: { margin: 0, fontSize: 24, fontWeight: 600, color: tokens.ink, letterSpacing: "-0.01em" }, children: title }), _jsx("p", { style: { marginTop: 8, marginBottom: 0, fontSize: 14, color: tokens.inkMuted }, children: description }), _jsx("div", { style: {
                         display: "flex",
-                        flexDirection: narrow ? "column" : "row",
-                        gap: 12,
+                        flexDirection: "column",
+                        gap: 10,
                         marginTop: 24,
-                    }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 17, color: tokens.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
+                    }, children: packages && packages.length > 0
+                        ? packages.map((pkg) => (_jsxs("button", { onClick: () => onSelectPackage?.(pkg), style: { ...buttonStyle, flex: "none", display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [_jsx("span", { children: pkg.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [fmtMoney(pkg.price, currency), " \u00B7 ", fmtCredits(pkg.credits), " cr"] })] }, pkg.id)))
+                        : (_jsx("div", { style: { display: "flex", flexDirection: narrow ? "column" : "row", gap: 12 }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) })) }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 17, color: tokens.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
                                         flex: 1,
                                         minWidth: 0,
                                         appearance: "none",

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,60 @@
+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>;
+};
+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, }?: UsePaywallProps): UsePaywallResult;

package/dist/usePaywall.js

@@ -0,0 +1,44 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { PaywallModal } from "./PaywallModal";
+/**
+ * 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, } = {}) {
+    const [isOpen, setIsOpen] = useState(false);
+    const trigger = useCallback(() => setIsOpen(true), []);
+    const dismiss = useCallback(() => setIsOpen(false), []);
+    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.1.0",
+  "version": "0.3.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",