@crediball/react 0.9.0 → 0.10.0

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() {
@@ -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.
@@ -230,7 +252,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, 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 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

@@ -96,6 +96,15 @@ 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;
     style?: CSSProperties;
 }
 /**
@@ -103,4 +112,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, 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;

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, 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, }) {
     // 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,7 @@ 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);
     useEffect(() => {
         const el = overlayRef.current;
         if (!el || typeof ResizeObserver === "undefined")
@@ -56,6 +57,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) {
@@ -162,7 +170,37 @@ 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, referralLink ? (_jsxs("div", { style: {
+                        marginTop: 20,
+                        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: {
+                                        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, onClose ? (_jsx("button", { onClick: onClose, style: {
                         width: "100%",
                         marginTop: 12,
                         appearance: "none",

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.10.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",