@crediball/react 0.10.0 → 0.11.0

package/dist/CrediballProvider.d.ts

@@ -54,6 +54,18 @@ export interface CrediballProviderProps {
      * `meter.cancelSubscription({ userId, subscriptionId })` on your backend.
      */
     onCancelSubscription?: (subscriptionId: string) => void | Promise<void>;
+    /**
+     * Optional override for the auto-topup opt-in. If omitted, the paywall starts a
+     * Crediball-hosted Stripe Checkout in setup mode itself (connect payouts in the
+     * dashboard) — no money changes hands there, it only saves a payment method.
+     * Provide this only to run your own flow (e.g.
+     * `meter.setupAutoTopupCheckout({ userId, packageId, thresholdCredits, ... })`
+     * server-side).
+     */
+    onEnableAutoTopup?: (input: {
+        packageId: string;
+        thresholdCredits: number;
+    }) => void | Promise<void>;
     /**
      * Auto-detect insufficient-credit responses from any fetch() call and open the
      * paywall automatically — no per-call wiring. Defaults to true. Set false to only
@@ -172,7 +184,7 @@ interface CrediballContextValue {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme, captureReferrals, }: CrediballProviderProps): import("react").JSX.Element;
+export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme, captureReferrals, }: CrediballProviderProps): import("react").JSX.Element;
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *

package/dist/CrediballProvider.js

@@ -63,7 +63,7 @@ function symbolForCurrency(iso) {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, watchFetch = true, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme = true, captureReferrals = true, }) {
+export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch = true, allowCustom, customMin, customMax, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme = true, captureReferrals = true, }) {
     const [open, setOpen] = useState(false);
     // Referral auto-capture: pick up a `?ref=CODE` visit into localStorage (and
     // count the click) as soon as the provider mounts — the visitor usually has
@@ -240,6 +240,18 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         await onCancelSubscription?.(subscriptionId);
         await client?.refresh();
     }
+    function handleEnableAutoTopup(input) {
+        return runPaywallAction(onEnableAutoTopup, input, async () => {
+            if (!client)
+                return;
+            const { url } = await client.createAutoTopupCheckout({
+                ...input,
+                returnPath: currentReturnPath(),
+            });
+            if (typeof window !== "undefined")
+                window.location.assign(url);
+        }, "auto-topup setup");
+    }
     // Auto-derive the custom-amount field from the dashboard's custom-topup config,
     // so a developer who enabled it doesn't also have to pass allowCustom/min/max.
     // Explicit props still win (allowCustom={false} force-hides it).
@@ -252,7 +264,7 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     // layout box. Host props/CSS are overridden by design (dashboard wins).
     const themeVars = applyRemoteTheme ? themeToCssVars(uiTheme) : {};
     const hasThemeVars = Object.keys(themeVars).length > 0;
-    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, referralLink: referral?.link ?? undefined, referralReward: referral?.rewardCredits, accentColor: accentColor })] }));
+    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, autoTopup: pkgs?.autoTopup, onEnableAutoTopup: handleEnableAutoTopup, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, referralLink: referral?.link ?? undefined, referralReward: referral?.rewardCredits, referralLabel: uiContent?.referralLabel, accentColor: accentColor })] }));
     const configCtx = useMemo(() => ({ publishableKey, userId, apiUrl }), [publishableKey, userId, apiUrl]);
     return (_jsx(CrediballContext.Provider, { value: ctx, children: _jsx(CrediballConfigContext.Provider, { value: configCtx, children: hasThemeVars ? (_jsx("div", { style: { display: "contents", ...themeVars }, children: inner })) : (inner) }) }));
 }

package/dist/PaywallModal.d.ts

@@ -22,6 +22,13 @@ export interface ActiveSubscriptionInfo {
     planPeriod: string;
     currentPeriodEnd: string;
 }
+/** The end user's current auto-topup rule (returned by listPackages() with userId). */
+export interface AutoTopupInfo {
+    enabled: boolean;
+    packageId: string;
+    thresholdCredits: number;
+    status: "pending" | "active" | "needs_auth" | "failed";
+}
 export interface PaywallModalProps extends CrediballThemeOverrides {
     open: boolean;
     /**
@@ -58,6 +65,24 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
      * Call `meter.cancelSubscription({ userId, subscriptionId })` in your backend.
      */
     onCancelSubscription?: (subscriptionId: string) => void | Promise<void>;
+    /**
+     * The end user's current auto-topup rule (from `meter.listPackages({ userId })`
+     * or `meter.getAutoTopupStatus(userId)`). When absent/null and `onEnableAutoTopup`
+     * is provided, an opt-in row is shown below the packages so the user can turn
+     * on "keep me topped up automatically".
+     */
+    autoTopup?: AutoTopupInfo | null;
+    /**
+     * Called when the user opts into auto top-up (only shown when `packages` is
+     * non-empty). Call `meter.setupAutoTopupCheckout({ userId, packageId,
+     * thresholdCredits, successUrl, cancelUrl })` in your backend — it saves a
+     * payment method, no money changes hands in this step — then redirect the
+     * browser to the returned `url`.
+     */
+    onEnableAutoTopup?: (input: {
+        packageId: string;
+        thresholdCredits: number;
+    }) => void;
     /**
      * Legacy: flat list of euro amounts. Prefer `packages` + `onSelectPackage`.
      * When both are provided, `packages` takes precedence.
@@ -105,6 +130,12 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     referralLink?: string | null;
     /** Credits earned per successful referral, shown in the refer-a-friend blurb. */
     referralReward?: number;
+    /**
+     * Label above the referral link. `{credits}` is replaced with `referralReward`.
+     * Default "Refer a friend · earn {credits} credits". Shown as written (not
+     * uppercased), so lowercase/sentence case is preserved.
+     */
+    referralLabel?: string;
     style?: CSSProperties;
 }
 /**
@@ -112,4 +143,4 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
  * continue. The host controls when it appears; shows a small "Powered by
  * Crediball" line by default (set `hideBranding` to remove it).
  */
-export declare function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, addButtonText, customMin, customMax, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;
+export declare function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, addButtonText, customMin, customMax, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, referralLabel, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;

package/dist/PaywallModal.js

@@ -19,7 +19,7 @@ function sectionLabelStyle(marginBottom) {
  * continue. The host controls when it appears; shows a small "Powered by
  * Crediball" line by default (set `hideBranding` to remove it).
  */
-export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, addButtonText = "Add", customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, referralLink, referralReward, accentColor, style, }) {
+export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, addButtonText = "Add", customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, referralLink, referralReward, referralLabel = "Refer a friend · earn {credits} credits", accentColor, style, }) {
     // Stack the top-up buttons one-per-line when the dialog itself is narrow.
     // Measured off the dialog's own box (via ResizeObserver) rather than the
     // window — in normal use the two are the same width, but this also makes
@@ -32,6 +32,9 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
     const [cancelPending, setCancelPending] = useState(false);
     const [cancelDone, setCancelDone] = useState(false);
     const [referralCopied, setReferralCopied] = useState(false);
+    const [autoTopupOpen, setAutoTopupOpen] = useState(false);
+    const [autoTopupPackageId, setAutoTopupPackageId] = useState("");
+    const [autoTopupThreshold, setAutoTopupThreshold] = useState("");
     useEffect(() => {
         const el = overlayRef.current;
         if (!el || typeof ResizeObserver === "undefined")
@@ -43,6 +46,15 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         observer.observe(el);
         return () => observer.disconnect();
     }, []);
+    // Default the auto-topup picker to the cheapest package + its own credit
+    // amount as the suggested threshold, once packages are available.
+    useEffect(() => {
+        if (!packages || packages.length === 0 || autoTopupPackageId)
+            return;
+        const cheapest = packages.reduce((min, p) => (p.price < min.price ? p : min), packages[0]);
+        setAutoTopupPackageId(cheapest.id);
+        setAutoTopupThreshold(String(cheapest.credits));
+    }, [packages, autoTopupPackageId]);
     if (!open)
         return null;
     async function handleCancelSubscription() {
@@ -81,6 +93,12 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         setCustomError(null);
         onAdd?.(amt);
     }
+    function submitAutoTopup() {
+        const threshold = Number(autoTopupThreshold);
+        if (!autoTopupPackageId || !Number.isFinite(threshold) || threshold < 0)
+            return;
+        onEnableAutoTopup?.({ packageId: autoTopupPackageId, thresholdCredits: threshold });
+    }
     const buttonStyle = {
         flex: 1,
         appearance: "none",
@@ -95,6 +113,7 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         padding: "8px 16px",
         borderRadius: theme.radiusPill,
     };
+    const resolvedReferralLabel = referralLabel.replace("{credits}", formatCredits(referralReward ?? 0));
     return (_jsx("div", { ref: overlayRef, role: "dialog", "aria-modal": "true", style: {
             position: "fixed",
             inset: 0,
@@ -170,13 +189,73 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                         color: theme.ink,
                                         background: theme.canvas,
                                         outline: "none",
-                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: addButtonText })] }), customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: theme.accent }, children: customError })) : null] })) : null, referralLink ? (_jsxs("div", { style: {
-                        marginTop: 20,
+                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: addButtonText })] }), customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: theme.accent }, children: customError })) : null] })) : null, onEnableAutoTopup && packages && packages.length > 0 && (_jsx("div", { style: { marginTop: 16 }, children: autoTopup?.enabled && autoTopup.status === "active" ? (_jsxs("p", { style: { margin: 0, fontSize: 12, color: theme.inkMuted }, children: ["Auto top-up is on \u2014 buying", " ", packages.find((p) => p.id === autoTopup.packageId)?.name ?? "your package", " whenever your balance drops below ", formatCredits(autoTopup.thresholdCredits), " credits."] })) : autoTopup?.enabled && (autoTopup.status === "needs_auth" || autoTopup.status === "failed") ? (_jsxs("div", { children: [_jsx("p", { style: { margin: 0, fontSize: 12, color: theme.accent }, children: autoTopup.status === "needs_auth"
+                                    ? "Auto top-up needs you to re-confirm your payment method."
+                                    : "Auto top-up's last charge failed." }), _jsx("button", { onClick: () => onEnableAutoTopup({
+                                    packageId: autoTopup.packageId,
+                                    thresholdCredits: autoTopup.thresholdCredits,
+                                }), style: {
+                                    marginTop: 6,
+                                    appearance: "none",
+                                    border: "none",
+                                    background: "transparent",
+                                    cursor: "pointer",
+                                    padding: 0,
+                                    fontSize: 12,
+                                    color: theme.ink,
+                                    fontFamily: theme.font,
+                                    textDecoration: "underline",
+                                }, children: "Fix auto top-up" })] })) : autoTopupOpen ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("select", { value: autoTopupPackageId, onChange: (e) => setAutoTopupPackageId(e.target.value), style: {
+                                            flex: 1,
+                                            minWidth: 0,
+                                            fontFamily: theme.font,
+                                            fontSize: 13,
+                                            padding: "6px 10px",
+                                            borderRadius: theme.radiusPill,
+                                            border: `1px solid ${theme.hairline}`,
+                                            color: theme.ink,
+                                            background: theme.canvas,
+                                        }, children: packages.map((pkg) => (_jsxs("option", { value: pkg.id, children: [pkg.name, " \u00B7 ", formatMoney(pkg.price, currency)] }, pkg.id))) }), _jsx("input", { value: autoTopupThreshold, onChange: (e) => setAutoTopupThreshold(e.target.value), inputMode: "numeric", "aria-label": "Threshold credits", style: {
+                                            width: 72,
+                                            fontFamily: theme.font,
+                                            fontSize: 13,
+                                            padding: "6px 10px",
+                                            borderRadius: theme.radiusPill,
+                                            border: `1px solid ${theme.hairline}`,
+                                            color: theme.ink,
+                                            background: theme.canvas,
+                                        } }), _jsx("button", { onClick: submitAutoTopup, style: { ...buttonStyle, flex: "none", padding: "6px 14px", fontSize: 13 }, children: "Turn on" })] }), _jsx("p", { style: { margin: 0, fontSize: 11, color: theme.inkMuted }, children: "Buy that package automatically whenever your balance drops below the credit amount above." })] })) : (_jsx("button", { onClick: () => setAutoTopupOpen(true), style: {
+                            appearance: "none",
+                            border: "none",
+                            background: "transparent",
+                            cursor: "pointer",
+                            padding: 0,
+                            fontSize: 12,
+                            color: theme.inkMuted,
+                            fontFamily: theme.font,
+                            textDecoration: "underline",
+                        }, children: "Keep me topped up automatically" })) })), onClose ? (_jsx("button", { onClick: onClose, style: {
+                        width: "100%",
+                        marginTop: 12,
+                        appearance: "none",
+                        border: "none",
+                        cursor: "pointer",
+                        background: "transparent",
+                        color: theme.inkMuted,
+                        fontFamily: theme.font,
+                        fontSize: 12,
+                        padding: "8px 16px",
+                        borderRadius: theme.radiusPill,
+                    }, children: "Not now" })) : null, referralLink ? (_jsxs("div", { style: {
+                        marginTop: 16,
                         paddingTop: 16,
                         borderTop: `1px solid ${theme.hairline}`,
-                    }, children: [_jsx("div", { style: sectionLabelStyle(8), children: referralReward && referralReward > 0
-                                ? `Refer a friend · earn ${formatCredits(referralReward)} credits`
-                                : "Refer a friend" }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("div", { title: referralLink, style: {
+                    }, children: [_jsx("div", { style: {
+                                fontSize: 12,
+                                fontWeight: 600,
+                                color: theme.inkMuted,
+                                marginBottom: 8,
+                            }, children: resolvedReferralLabel }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("div", { title: referralLink, style: {
                                         flex: 1,
                                         minWidth: 0,
                                         overflow: "hidden",
@@ -200,17 +279,5 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                         padding: "8px 16px",
                                         borderRadius: theme.radiusPill,
                                         whiteSpace: "nowrap",
-                                    }, children: referralCopied ? "Copied!" : "Copy" })] })] })) : null, onClose ? (_jsx("button", { onClick: onClose, style: {
-                        width: "100%",
-                        marginTop: 12,
-                        appearance: "none",
-                        border: "none",
-                        cursor: "pointer",
-                        background: "transparent",
-                        color: theme.inkMuted,
-                        fontFamily: theme.font,
-                        fontSize: 12,
-                        padding: "8px 16px",
-                        borderRadius: theme.radiusPill,
-                    }, children: "Not now" })) : null, !hideBranding && (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", marginTop: 10 }, children: _jsx("span", { style: { fontSize: 10, color: theme.inkMuted }, children: "Powered by Crediball." }) }))] }) }));
+                                    }, children: referralCopied ? "Copied!" : "Copy" })] })] })) : null, !hideBranding && (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", marginTop: 10 }, children: _jsx("span", { style: { fontSize: 10, color: theme.inkMuted }, children: "Powered by Crediball." }) }))] }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",
@@ -51,7 +51,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@crediball/core": "^0.4.0"
+    "@crediball/core": "^0.6.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",