@crediball/react 0.8.0 → 0.10.0

package/dist/CrediballProvider.d.ts

@@ -93,7 +93,27 @@ export interface CrediballProviderProps {
      * theme entirely from your own stylesheet.
      */
     applyRemoteTheme?: boolean;
+    /**
+     * Automatic referral handling. On by default: any visit with `?ref=CODE` in
+     * the URL is captured (stored locally + click counted), and once a `userId`
+     * is present the stored code is attached to that user as a pending referral —
+     * so with referrals enabled in the dashboard there is zero extra wiring.
+     * Rewards are only ever granted server-side when the conversion condition is
+     * met. Set false to manage capture/completion yourself via @crediball/core.
+     */
+    captureReferrals?: boolean;
+}
+/**
+ * Internal: the provider's raw connection config, for hooks (useReferral) that
+ * talk to the API directly instead of reading the polled snapshot.
+ */
+interface CrediballConfigValue {
+    publishableKey?: string;
+    userId?: string;
+    apiUrl?: string;
 }
+/** Internal hook: the provider's publishableKey/userId/apiUrl. Throws outside a provider. */
+export declare function useCrediballConfig(): CrediballConfigValue;
 interface CrediballContextValue {
     /**
      * Open the paywall modal. Always safe to call — never guard with "already shown"
@@ -152,7 +172,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, }: CrediballProviderProps): import("react").JSX.Element;
+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;
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *

package/dist/CrediballProvider.js

@@ -4,7 +4,16 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, use
 import { PaywallModal } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
 import { subscribeInsufficientCredits } from "./creditEvent";
-import { getCrediballClient, notifyBalanceChanged, } 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() {
+    const ctx = useContext(CrediballConfigContext);
+    if (!ctx) {
+        throw new Error("This hook must be used inside <CrediballProvider>.");
+    }
+    return ctx;
+}
 const CrediballContext = createContext(null);
 const EMPTY_SNAPSHOT = {
     balance: null,
@@ -34,50 +43,6 @@ function symbolForCurrency(iso) {
         return iso;
     }
 }
-/**
- * Turn a published theme into the `--crediball-*` inline style the provider
- * spreads onto a wrapping element. Only set fields are emitted, so an empty or
- * partial theme leaves the built-in defaults (and any host CSS vars) in place.
- */
-function themeToCssVars(theme) {
-    if (!theme)
-        return {};
-    const vars = {};
-    if (theme.accent)
-        vars["--crediball-accent"] = theme.accent;
-    if (theme.onAccent)
-        vars["--crediball-on-accent"] = theme.onAccent;
-    if (theme.ink)
-        vars["--crediball-ink"] = theme.ink;
-    if (theme.canvas)
-        vars["--crediball-canvas"] = theme.canvas;
-    if (theme.hairline)
-        vars["--crediball-hairline"] = theme.hairline;
-    if (theme.radius != null)
-        vars["--crediball-radius"] = `${theme.radius}px`;
-    if (theme.radiusCard != null)
-        vars["--crediball-radius-card"] = `${theme.radiusCard}px`;
-    if (theme.fontStack)
-        vars["--crediball-font"] = theme.fontStack;
-    return vars;
-}
-/** Inject a webfont stylesheet <link> once (idempotent by href), for a published theme's fontUrl. */
-function loadRemoteFont(url) {
-    if (typeof document === "undefined")
-        return;
-    const existing = document.querySelector(`link[data-crediball-font]`);
-    if (existing?.href === url)
-        return;
-    if (existing)
-        existing.href = url;
-    else {
-        const link = document.createElement("link");
-        link.rel = "stylesheet";
-        link.href = url;
-        link.setAttribute("data-crediball-font", "");
-        document.head.appendChild(link);
-    }
-}
 /**
  * Pattern B, automated. Wrap your app once:
  *
@@ -98,8 +63,47 @@ function loadRemoteFont(url) {
  * 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, }) {
+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, }) {
     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
+    // no account yet at this point.
+    useEffect(() => {
+        if (!captureReferrals || !publishableKey)
+            return;
+        captureReferral({ publishableKey, apiUrl });
+    }, [captureReferrals, publishableKey, apiUrl]);
+    // Referral auto-complete: the moment a userId is known (signup finished, or
+    // a signed-in user returns), attach any stored code to them as a pending
+    // referral. Best-effort — a failure leaves the code stored for a retry on
+    // the next mount.
+    useEffect(() => {
+        if (!captureReferrals || !publishableKey || !userId)
+            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.
@@ -186,35 +190,14 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         if (typeof window !== "undefined")
             window.location.assign(url);
     }
-    async function handleAdd(amount) {
-        // A host-supplied top-up flow always wins.
-        if (onTopup) {
+    // Shared shape for handleAdd/handleSelectPackage/handleSelectPlan: a host-supplied
+    // handler always wins (and refreshes balance/usage on completion); otherwise fall
+    // back to the built-in Stripe checkout when a data client is available, leaving the
+    // modal open on failure so the error stays visible; otherwise just close the modal.
+    async function runPaywallAction(hostHandler, arg, builtIn, errorLabel) {
+        if (hostHandler) {
             try {
-                await topUp(amount);
-            }
-            finally {
-                setOpen(false);
-            }
-            return;
-        }
-        // Otherwise start Stripe ourselves (custom amount). Leave the modal open on
-        // failure so the error is visible instead of the modal silently closing.
-        if (client) {
-            try {
-                await startBuiltInCheckout({ eurAmount: amount });
-            }
-            catch (err) {
-                console.error("[crediball] checkout failed:", err);
-            }
-            return;
-        }
-        // Data-less mode with no handler: nothing to charge against.
-        setOpen(false);
-    }
-    async function handleSelectPackage(pkg) {
-        if (onSelectPackage) {
-            try {
-                await onSelectPackage(pkg);
+                await hostHandler(arg);
                 notifyBalanceChanged();
                 await client?.refresh();
             }
@@ -225,45 +208,33 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         }
         if (client) {
             try {
-                await startBuiltInCheckout({ packageId: pkg.id });
+                await builtIn();
             }
             catch (err) {
-                console.error("[crediball] checkout failed:", err);
+                console.error(`[crediball] ${errorLabel} failed:`, err);
             }
             return;
         }
+        // Data-less mode with no handler: nothing to charge against.
         setOpen(false);
     }
-    async function handleSelectPlan(plan) {
-        // Host-supplied subscription flow wins.
-        if (onSelectPlan) {
-            try {
-                await onSelectPlan(plan);
-                notifyBalanceChanged();
-                await client?.refresh();
-            }
-            finally {
-                setOpen(false);
-            }
-            return;
-        }
-        // Otherwise start the recurring Stripe Checkout ourselves. Leave the modal
-        // open on failure so the error is visible.
-        if (client) {
-            try {
-                const { url } = await client.createSubscriptionCheckout({
-                    planId: plan.id,
-                    returnPath: currentReturnPath(),
-                });
-                if (typeof window !== "undefined")
-                    window.location.assign(url);
-            }
-            catch (err) {
-                console.error("[crediball] subscription checkout failed:", err);
-            }
-            return;
-        }
-        setOpen(false);
+    function handleAdd(amount) {
+        return runPaywallAction(onTopup, amount, () => startBuiltInCheckout({ eurAmount: amount }), "checkout");
+    }
+    function handleSelectPackage(pkg) {
+        return runPaywallAction(onSelectPackage, pkg, () => startBuiltInCheckout({ packageId: pkg.id }), "checkout");
+    }
+    function handleSelectPlan(plan) {
+        return runPaywallAction(onSelectPlan, plan, async () => {
+            if (!client)
+                return;
+            const { url } = await client.createSubscriptionCheckout({
+                planId: plan.id,
+                returnPath: currentReturnPath(),
+            });
+            if (typeof window !== "undefined")
+                window.location.assign(url);
+        }, "subscription checkout");
     }
     async function handleCancelSubscription(subscriptionId) {
         await onCancelSubscription?.(subscriptionId);
@@ -281,8 +252,9 @@ 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 })] }));
-    return (_jsx(CrediballContext.Provider, { value: ctx, children: hasThemeVars ? _jsx("div", { style: { display: "contents", ...themeVars }, children: inner }) : inner }));
+    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) }) }));
 }
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.

package/dist/InlineValue.d.ts

@@ -0,0 +1,11 @@
+import type { CSSProperties, ReactNode } from "react";
+/**
+ * Shared rendering shell for the Tier-2 "variable" components (CrediballBalance,
+ * CrediballUsage, CrediballLowCreditWarning): an inline <span> that inherits the
+ * surrounding font/color so it reads naturally wherever it's placed.
+ */
+export declare function InlineValue({ className, style, children, }: {
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/InlineValue.js

@@ -0,0 +1,10 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Shared rendering shell for the Tier-2 "variable" components (CrediballBalance,
+ * CrediballUsage, CrediballLowCreditWarning): an inline <span> that inherits the
+ * surrounding font/color so it reads naturally wherever it's placed.
+ */
+export function InlineValue({ className, style, children, }) {
+    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children }));
+}

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

@@ -0,0 +1,49 @@
+import type { CSSProperties } from "react";
+import { type CrediballThemeOverrides } from "./theme";
+export interface ReferralCardProps extends CrediballThemeOverrides {
+    /** Heading. Default "Invite friends". */
+    title?: string;
+    /**
+     * Subtitle. Defaults to a reward blurb built from the dashboard config
+     * (e.g. "Earn 100 credits for every friend who joins.").
+     */
+    description?: string;
+    /** Copy-button label. Default "Copy". */
+    copyLabel?: string;
+    /** Share-button label. Default "Share". */
+    shareLabel?: string;
+    /** 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
+ * <CrediballProvider publishableKey userId>:
+ *
+ *   <ReferralCard />
+ *
+ * Shows the user's invite link with Copy/Share actions and their referral
+ * stats. Lazily creates the code on first render, renders nothing while
+ * 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, demo, }: ReferralCardProps): import("react").JSX.Element | null;

package/dist/ReferralCard.js

@@ -0,0 +1,83 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { theme, accentStyle } from "./theme";
+import { formatCredits } from "./format";
+import { useReferral } from "./useReferral";
+/**
+ * Drop-in invite card built on useReferral(). Place anywhere inside
+ * <CrediballProvider publishableKey userId>:
+ *
+ *   <ReferralCard />
+ *
+ * Shows the user's invite link with Copy/Share actions and their referral
+ * stats. Lazily creates the code on first render, renders nothing while
+ * 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, 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 ??
+        (rewardCredits > 0
+            ? referredRewardCredits > 0
+                ? `Earn ${formatCredits(rewardCredits)} credits for every friend who joins — they get ${formatCredits(referredRewardCredits)} credits too.`
+                : `Earn ${formatCredits(rewardCredits)} credits for every friend who joins.`
+            : undefined);
+    const canShare = typeof navigator !== "undefined" && typeof navigator.share === "function";
+    const buttonBase = {
+        appearance: "none",
+        cursor: "pointer",
+        fontFamily: theme.font,
+        fontSize: 14,
+        padding: "8px 16px",
+        borderRadius: theme.radiusPill,
+        whiteSpace: "nowrap",
+    };
+    return (_jsxs("div", { style: {
+            display: "flex",
+            flexDirection: "column",
+            gap: 14,
+            padding: 24,
+            border: `1px solid ${theme.hairline}`,
+            borderRadius: theme.radiusCard,
+            background: theme.canvas,
+            fontFamily: theme.font,
+            ...accentStyle(accentColor),
+            ...style,
+        }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 16, fontWeight: 600, color: theme.ink }, children: title }), resolvedDescription ? (_jsx("div", { style: { fontSize: 13, color: theme.inkMuted, marginTop: 2 }, children: resolvedDescription })) : null] }), _jsxs("div", { style: { display: "flex", alignItems: "center", gap: 8, flexWrap: "wrap" }, children: [_jsx("div", { style: {
+                            flex: "1 1 180px",
+                            minWidth: 0,
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
+                            whiteSpace: "nowrap",
+                            fontSize: 14,
+                            color: theme.ink,
+                            border: `1px solid ${theme.hairline}`,
+                            borderRadius: theme.radiusPill,
+                            padding: "8px 14px",
+                        }, title: link ?? code, children: link ?? code }), _jsx("button", { onClick: () => void copy(), style: {
+                            ...buttonBase,
+                            border: `1px solid ${theme.hairline}`,
+                            background: "transparent",
+                            color: theme.ink,
+                        }, children: copied ? "Copied!" : copyLabel }), canShare ? (_jsx("button", { onClick: () => void share(), style: {
+                            ...buttonBase,
+                            border: "none",
+                            background: theme.accent,
+                            color: theme.onAccent,
+                        }, children: shareLabel })) : null] }), hideStats ? null : (_jsxs("div", { style: { display: "flex", gap: 16, fontSize: 13, color: theme.inkMuted }, children: [_jsxs("span", { children: [_jsx("strong", { style: { color: theme.ink, fontWeight: 600 }, children: clicks }), " clicks"] }), _jsxs("span", { children: [_jsx("strong", { style: { color: theme.ink, fontWeight: 600 }, children: rewards.converted }), " ", "joined"] }), rewards.creditsEarned > 0 ? (_jsxs("span", { children: [_jsx("strong", { style: { color: theme.ink, fontWeight: 600 }, children: formatCredits(rewards.creditsEarned) }), " ", "credits earned"] })) : null] }))] }));
+}

package/dist/format.d.ts

@@ -1,4 +1 @@
-/** Formats a raw credit balance as a locale-formatted whole number (e.g. 840 → "840"). */
-export declare function formatCredits(credits: number): string;
-/** Formats a monetary amount in the given ISO 4217 currency, falling back to a plain number + code for unknown currencies. */
-export declare function formatMoney(amount: number, currency: string): string;
+export { formatCredits, formatMoney } from "@crediball/core";

package/dist/format.js

@@ -1,13 +1 @@
-/** Formats a raw credit balance as a locale-formatted whole number (e.g. 840 → "840"). */
-export function formatCredits(credits) {
-    return new Intl.NumberFormat(undefined).format(Math.round(credits));
-}
-/** Formats a monetary amount in the given ISO 4217 currency, falling back to a plain number + code for unknown currencies. */
-export function formatMoney(amount, currency) {
-    try {
-        return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(amount);
-    }
-    catch {
-        return `${amount.toFixed(2)} ${currency}`;
-    }
-}
+export { formatCredits, formatMoney } from "@crediball/core";

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { PaywallModal, type PaywallModalProps, type PackageOption, type Subscrip
 export { CreditIndicator, type CreditIndicatorProps } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, useCrediballOptional, type CrediballProviderProps, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
+export { useReferral, type UseReferralResult } from "./useReferral";
+export { ReferralCard, type ReferralCardProps } from "./ReferralCard";
 export { tokens, theme, cssVars, accentStyle, type CrediballThemeOverrides } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
 export { CrediballBalance, type CrediballBalanceProps } from "./variables/CrediballBalance";

package/dist/index.js

@@ -5,6 +5,8 @@ export { PaywallModal, } from "./PaywallModal";
 export { CreditIndicator } from "./CreditIndicator";
 export { CrediballProvider, useCrediball, useCrediballOptional, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, } from "./usePaywall";
+export { useReferral } from "./useReferral";
+export { ReferralCard } from "./ReferralCard";
 export { tokens, theme, cssVars, accentStyle } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
 // Tier 2 — "variables" you place anywhere inside <CrediballProvider>.

package/dist/useReferral.d.ts

@@ -0,0 +1,42 @@
+export interface UseReferralResult {
+    /** False while loading, or when the referral program is off in the dashboard. */
+    enabled: boolean;
+    /** The user's referral code (lazily created server-side on first read). */
+    code: string | null;
+    /** Full invite link: the dashboard's link template, or `origin/?ref=CODE` when unset. */
+    link: string | null;
+    /** How many times the invite link was opened. */
+    clicks: number;
+    /** Referral outcomes: pending / converted counts and credits earned so far. */
+    rewards: {
+        pending: number;
+        converted: number;
+        creditsEarned: number;
+    };
+    /** Credits the referrer earns per converted referral (dashboard config). */
+    rewardCredits: number;
+    /** Credits the invited friend gets on conversion (dashboard config, 0 = off). */
+    referredRewardCredits: number;
+    loading: boolean;
+    error: Error | null;
+    /** Copy the invite link (falls back to the code) to the clipboard. */
+    copy: () => Promise<void>;
+    /** True for 2s after a successful copy — for "Copied!" feedback. */
+    copied: boolean;
+    /** Open the native share sheet with the invite link; falls back to copy. */
+    share: () => Promise<void>;
+    /** Refetch code/stats. */
+    refresh: () => Promise<void>;
+}
+/**
+ * Headless referral hook — render any invite UI on top of it:
+ *
+ *   const { link, copy, share, rewards, loading } = useReferral();
+ *
+ * Must be used inside <CrediballProvider publishableKey userId>. The referral
+ * code is created lazily by the server on the first call and stays stable.
+ * When the dashboard's referral program is disabled, `enabled` is false and
+ * everything else stays empty — render nothing in that case (as
+ * <ReferralCard/> does).
+ */
+export declare function useReferral(): UseReferralResult;

package/dist/useReferral.js

@@ -0,0 +1,92 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { fetchReferral } from "@crediball/core";
+import { useCrediballConfig } from "./CrediballProvider";
+const EMPTY_REWARDS = { pending: 0, converted: 0, creditsEarned: 0 };
+/**
+ * Headless referral hook — render any invite UI on top of it:
+ *
+ *   const { link, copy, share, rewards, loading } = useReferral();
+ *
+ * Must be used inside <CrediballProvider publishableKey userId>. The referral
+ * code is created lazily by the server on the first call and stays stable.
+ * When the dashboard's referral program is disabled, `enabled` is false and
+ * everything else stays empty — render nothing in that case (as
+ * <ReferralCard/> does).
+ */
+export function useReferral() {
+    const { publishableKey, userId, apiUrl } = useCrediballConfig();
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [copied, setCopied] = useState(false);
+    const copiedTimer = useRef(null);
+    const refresh = useCallback(async () => {
+        if (!publishableKey || !userId) {
+            setLoading(false);
+            return;
+        }
+        try {
+            const next = await fetchReferral({ publishableKey, userId, apiUrl });
+            setData(next);
+            setError(null);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [publishableKey, userId, apiUrl]);
+    useEffect(() => {
+        setLoading(true);
+        void refresh();
+    }, [refresh]);
+    useEffect(() => {
+        return () => {
+            if (copiedTimer.current)
+                clearTimeout(copiedTimer.current);
+        };
+    }, []);
+    const link = data?.link ?? null;
+    const code = data?.code ?? null;
+    const copy = useCallback(async () => {
+        const text = link ?? code;
+        if (!text || typeof navigator === "undefined" || !navigator.clipboard)
+            return;
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        if (copiedTimer.current)
+            clearTimeout(copiedTimer.current);
+        copiedTimer.current = setTimeout(() => setCopied(false), 2000);
+    }, [link, code]);
+    const share = useCallback(async () => {
+        const url = link ?? undefined;
+        const nav = typeof navigator === "undefined" ? undefined : navigator;
+        if (url && nav?.share) {
+            try {
+                await nav.share({ url });
+                return;
+            }
+            catch {
+                // dismissed or unsupported payload — fall through to copy
+            }
+        }
+        await copy();
+    }, [link, copy]);
+    return {
+        enabled: data?.enabled ?? false,
+        code,
+        link,
+        clicks: data?.clicks ?? 0,
+        rewards: data?.rewards ?? EMPTY_REWARDS,
+        rewardCredits: data?.rewardCredits ?? 0,
+        referredRewardCredits: data?.referredRewardCredits ?? 0,
+        loading,
+        error,
+        copy,
+        copied,
+        share,
+        refresh,
+    };
+}

package/dist/variables/CrediballBalance.js

@@ -2,6 +2,7 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useCrediball } from "../CrediballProvider";
 import { formatCredits } from "../format";
+import { InlineValue } from "../InlineValue";
 /**
  * Tier 2 — a "variable" you drop anywhere inside <CrediballProvider>. Renders
  * as an inline <span> that inherits the surrounding font, size, and color
@@ -15,5 +16,5 @@ export function CrediballBalance({ className, style, format = formatCredits, chi
     if (typeof children === "function") {
         return _jsx(_Fragment, { children: children({ balance, loading }) });
     }
-    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? (balance == null ? "—" : format(balance)) }));
+    return (_jsx(InlineValue, { className: className, style: style, children: children ?? (balance == null ? "—" : format(balance)) }));
 }

package/dist/variables/CrediballLowCreditWarning.js

@@ -1,6 +1,8 @@
 "use client";
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { isBalanceLow } from "@crediball/core";
 import { useCrediball } from "../CrediballProvider";
+import { InlineValue } from "../InlineValue";
 /**
  * Tier 2 — renders nothing until the user's balance is low, then shows a
  * message inline. Place it next to a specific action ("this costs 20 credits")
@@ -12,12 +14,12 @@ export function CrediballLowCreditWarning({ className, style, threshold, message
     const { balance, isLow: contextIsLow, content } = useCrediball();
     // Prefer the host prop, then the dashboard-published default, then the provider's.
     const effectiveThreshold = threshold ?? content?.lowCreditThreshold;
-    const isLow = effectiveThreshold != null && balance != null ? balance < effectiveThreshold : contextIsLow;
+    const isLow = isBalanceLow(balance, effectiveThreshold, contextIsLow);
     if (!isLow)
         return null;
     if (typeof children === "function") {
         return _jsx(_Fragment, { children: children({ balance, isLow }) });
     }
     const resolvedMessage = message ?? content?.lowCreditMessage ?? "Low credit balance — top up to keep going.";
-    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? resolvedMessage }));
+    return (_jsx(InlineValue, { className: className, style: style, children: children ?? resolvedMessage }));
 }

package/dist/variables/CrediballUsage.js

@@ -2,6 +2,7 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useCrediball } from "../CrediballProvider";
 import { formatCredits } from "../format";
+import { InlineValue } from "../InlineValue";
 /**
  * Tier 2 — credits consumed in the user's current period (their subscription's
  * billing cycle, or the calendar month for non-subscribers). Inline, inherits
@@ -15,5 +16,5 @@ export function CrediballUsage({ className, style, show = "used", format = forma
     if (typeof children === "function") {
         return _jsx(_Fragment, { children: children({ usage, value, loading }) });
     }
-    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? (value == null ? "—" : format(value)) }));
+    return (_jsx(InlineValue, { className: className, style: style, children: children ?? (value == null ? "—" : format(value)) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.8.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>",
@@ -51,7 +51,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@crediball/core": "^0.3.0"
+    "@crediball/core": "^0.4.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",