@crediball/react 0.9.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

@@ -4,7 +4,7 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, use
 import { PaywallModal } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
 import { subscribeInsufficientCredits } from "./creditEvent";
-import { getCrediballClient, notifyBalanceChanged, loadRemoteFont, themeToCssVars, captureReferral, completeStoredReferral, } from "@crediball/core";
+import { getCrediballClient, notifyBalanceChanged, loadRemoteFont, themeToCssVars, captureReferral, completeStoredReferral, fetchReferral, } from "@crediball/core";
 const CrediballConfigContext = createContext(null);
 /** Internal hook: the provider's publishableKey/userId/apiUrl. Throws outside a provider. */
 export function useCrediballConfig() {
@@ -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
@@ -82,6 +82,28 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
             return;
         void completeStoredReferral({ publishableKey, userId, apiUrl }).catch(() => { });
     }, [captureReferrals, publishableKey, userId, apiUrl]);
+    // The user's own referral invite link + reward, for the paywall's
+    // "Refer a friend" row. Null while loading or when referrals are disabled.
+    const [referral, setReferral] = useState(null);
+    useEffect(() => {
+        if (!publishableKey || !userId) {
+            setReferral(null);
+            return;
+        }
+        let cancelled = false;
+        fetchReferral({ publishableKey, userId, apiUrl })
+            .then((data) => {
+            if (!cancelled)
+                setReferral(data.enabled ? data : null);
+        })
+            .catch(() => {
+            if (!cancelled)
+                setReferral(null);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [publishableKey, userId, apiUrl]);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
     // Keep a ref so the fetch-watcher closure always calls the latest version.
@@ -218,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).
@@ -230,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, 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.
@@ -96,6 +121,21 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     usageLabel?: string;
     /** Hide the "Powered by Crediball" footer line (default false). */
     hideBranding?: boolean;
+    /**
+     * The user's referral invite link. When provided, a "Refer a friend" row with
+     * a copyable link is shown at the bottom of the modal — a way to earn credits
+     * without paying. Wired automatically by <CrediballProvider> when referrals are
+     * enabled in the dashboard; pass it yourself when using the modal standalone.
+     */
+    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;
 }
 /**
@@ -103,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, 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, 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
@@ -31,6 +31,10 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
     const [customError, setCustomError] = useState(null);
     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")
@@ -42,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() {
@@ -56,6 +69,13 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
             setCancelPending(false);
         }
     }
+    async function copyReferral() {
+        if (!referralLink || typeof navigator === "undefined" || !navigator.clipboard)
+            return;
+        await navigator.clipboard.writeText(referralLink);
+        setReferralCopied(true);
+        setTimeout(() => setReferralCopied(false), 2000);
+    }
     function submitCustom() {
         const amt = Number(customValue);
         if (!Number.isFinite(amt) || amt <= 0) {
@@ -73,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",
@@ -87,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,
@@ -162,7 +189,52 @@ 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, onClose ? (_jsx("button", { onClick: onClose, style: {
+                                    } }), _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",
@@ -174,5 +246,38 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                         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: "Not now" })) : null, referralLink ? (_jsxs("div", { style: {
+                        marginTop: 16,
+                        paddingTop: 16,
+                        borderTop: `1px solid ${theme.hairline}`,
+                    }, 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",
+                                        textOverflow: "ellipsis",
+                                        whiteSpace: "nowrap",
+                                        fontSize: 13,
+                                        color: theme.ink,
+                                        border: `1px solid ${theme.hairline}`,
+                                        borderRadius: theme.radiusPill,
+                                        padding: "8px 14px",
+                                    }, children: referralLink }), _jsx("button", { onClick: copyReferral, style: {
+                                        flex: "none",
+                                        appearance: "none",
+                                        cursor: "pointer",
+                                        background: "transparent",
+                                        color: theme.ink,
+                                        border: `1px solid ${theme.hairline}`,
+                                        fontFamily: theme.font,
+                                        fontWeight: 500,
+                                        fontSize: 14,
+                                        padding: "8px 16px",
+                                        borderRadius: theme.radiusPill,
+                                        whiteSpace: "nowrap",
+                                    }, 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/dist/ReferralCard.d.ts

@@ -15,6 +15,25 @@ export interface ReferralCardProps extends CrediballThemeOverrides {
     /** Hide the clicks / converted counters row. */
     hideStats?: boolean;
     style?: CSSProperties;
+    /**
+     * Preview/demo override. When set, the card renders from this sample data
+     * instead of the live `useReferral()` result — used by the dashboard's
+     * UI-patterns preview so the card is visible and themeable without a
+     * connected app, exactly like `PaywallModal`'s balance/packages preview
+     * props. In production you never pass this: the card fetches real data itself.
+     */
+    demo?: {
+        link?: string | null;
+        code?: string;
+        clicks?: number;
+        rewardCredits?: number;
+        referredRewardCredits?: number;
+        rewards?: {
+            pending: number;
+            converted: number;
+            creditsEarned: number;
+        };
+    };
 }
 /**
  * Drop-in invite card built on useReferral(). Place anywhere inside
@@ -27,4 +46,4 @@ export interface ReferralCardProps extends CrediballThemeOverrides {
  * loading or when the referral program is disabled in the dashboard, and is
  * themed by the same `--crediball-*` variables as every other component.
  */
-export declare function ReferralCard({ title, description, copyLabel, shareLabel, hideStats, accentColor, style, }: ReferralCardProps): import("react").JSX.Element | null;
+export declare function ReferralCard({ title, description, copyLabel, shareLabel, hideStats, accentColor, style, demo, }: ReferralCardProps): import("react").JSX.Element | null;

package/dist/ReferralCard.js

@@ -14,8 +14,21 @@ import { useReferral } from "./useReferral";
  * loading or when the referral program is disabled in the dashboard, and is
  * themed by the same `--crediball-*` variables as every other component.
  */
-export function ReferralCard({ title = "Invite friends", description, copyLabel = "Copy", shareLabel = "Share", hideStats = false, accentColor, style, }) {
-    const { enabled, link, code, clicks, rewards, rewardCredits, referredRewardCredits, loading, copy, copied, share, } = useReferral();
+export function ReferralCard({ title = "Invite friends", description, copyLabel = "Copy", shareLabel = "Share", hideStats = false, accentColor, style, demo, }) {
+    const live = useReferral();
+    // Demo/preview data (if any) overrides the live hook result and bypasses the
+    // loading/enabled gate, so the card renders in the UI-patterns preview.
+    const enabled = demo ? true : live.enabled;
+    const link = demo ? (demo.link ?? null) : live.link;
+    const code = demo ? (demo.code ?? null) : live.code;
+    const clicks = demo ? (demo.clicks ?? 0) : live.clicks;
+    const rewards = demo?.rewards ?? live.rewards;
+    const rewardCredits = demo ? (demo.rewardCredits ?? 0) : live.rewardCredits;
+    const referredRewardCredits = demo ? (demo.referredRewardCredits ?? 0) : live.referredRewardCredits;
+    const loading = demo ? false : live.loading;
+    const copied = demo ? false : live.copied;
+    const copy = live.copy;
+    const share = live.share;
     if (loading || !enabled || !code)
         return null;
     const resolvedDescription = description ??

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.9.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",