@crediball/react 0.7.0 → 0.9.0

package/dist/CrediballProvider.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import { type PackageOption, type SubscriptionPlanOption } from "./PaywallModal";
-import { type UsagePeriod } from "@crediball/core";
+import { type UsagePeriod, type PackagesPayload, type CrediballUiContent } from "@crediball/core";
 export interface CrediballProviderProps {
     children: ReactNode;
     /**
@@ -84,7 +84,36 @@ export interface CrediballProviderProps {
     description?: string;
     /** Override the accent color (defaults to Action Blue). */
     accentColor?: string;
+    /**
+     * Apply the theme (colors, radii, font) the developer published on the
+     * Crediball dashboard's UI-patterns page — served alongside packages — as
+     * `--crediball-*` CSS variables, so preview edits reflect here with no code
+     * change. On by default; the published theme takes precedence over any
+     * `--crediball-*` vars you set in your own CSS. Set false to opt out and
+     * 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"
@@ -116,6 +145,12 @@ interface CrediballContextValue {
     topUp: (amount: number) => Promise<void>;
     /** Refetch balance, usage, costs, and packages immediately. No-op without publishableKey/userId. */
     refresh: () => Promise<void>;
+    /** The live packages payload (top-up options, plans, custom-topup, currency, ui). null until loaded. */
+    packages: PackagesPayload | null;
+    /** Currency symbol derived from the dashboard's configured currency (e.g. "€", "$"). */
+    currencySymbol: string;
+    /** Developer-published default copy from the dashboard, used as a label fallback. null when unconfigured. */
+    content: CrediballUiContent | null;
 }
 /**
  * Pattern B, automated. Wrap your app once:
@@ -137,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, }: 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

@@ -1,10 +1,19 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore, } from "react";
 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, } 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,
@@ -54,8 +63,25 @@ 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, }) {
+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]);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
     // Keep a ref so the fetch-watcher closure always calls the latest version.
@@ -84,6 +110,20 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         return () => client.stop();
     }, [client]);
     const snapshot = useSyncExternalStore(client ? client.subscribe : noopSubscribe, client ? client.getSnapshot : getEmptySnapshot, client ? client.getSnapshot : getEmptySnapshot);
+    const pkgs = snapshot.packages;
+    const uiTheme = pkgs?.ui?.theme ?? null;
+    const uiContent = pkgs?.ui?.content ?? null;
+    // Follow the dashboard's configured currency once packages load, unless the
+    // host pins an explicit symbol. Falls back to "€" only until the first fetch
+    // resolves, so switching currencies on the Packages page never requires a
+    // matching code change/redeploy here.
+    const currencySymbol = currencySymbolProp ?? (pkgs?.currency ? symbolForCurrency(pkgs.currency) : "€");
+    // Load the published theme's webfont, if any, so --crediball-font renders.
+    useEffect(() => {
+        if (!applyRemoteTheme || !uiTheme?.fontUrl)
+            return;
+        loadRemoteFont(uiTheme.fontUrl);
+    }, [applyRemoteTheme, uiTheme?.fontUrl]);
     const costOf = useCallback((event) => client?.costOf(event), [client]);
     const refresh = useCallback(async () => {
         await client?.refresh();
@@ -107,7 +147,10 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         costOf,
         topUp,
         refresh,
-    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh]);
+        packages: pkgs,
+        currencySymbol,
+        content: uiContent,
+    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh, pkgs, currencySymbol, uiContent]);
     // The page to return to after Stripe checkout — the one the user is on now.
     function currentReturnPath() {
         if (typeof window === "undefined")
@@ -125,35 +168,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();
             }
@@ -164,56 +186,38 @@ 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);
         await client?.refresh();
     }
-    const pkgs = snapshot.packages;
-    // Follow the dashboard's configured currency once packages load, unless the
-    // host pins an explicit symbol. Falls back to "€" only until the first fetch
-    // resolves, so switching currencies on the Packages page never requires a
-    // matching code change/redeploy here.
-    const currencySymbol = currencySymbolProp ?? (pkgs?.currency ? symbolForCurrency(pkgs.currency) : "€");
     // 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).
@@ -221,7 +225,14 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     const effectiveAllowCustom = allowCustom ?? customCfg?.enabled ?? false;
     const effectiveCustomMin = customMin ?? customCfg?.minEur;
     const effectiveCustomMax = customMax ?? customCfg?.maxEur ?? undefined;
-    return (_jsxs(CrediballContext.Provider, { value: ctx, children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: handleCancelSubscription, 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, description: description, accentColor: accentColor })] }));
+    // Published theme → --crediball-* CSS vars, applied on a display:contents
+    // wrapper so it themes every descendant (and the paywall) without adding a
+    // 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 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/CreditIndicator.js

@@ -7,9 +7,11 @@ import { useCrediballOptional } from "./CrediballProvider";
  * Pattern C — Subtle indicator. A quiet balance chip for a host app's top bar;
  * clickable to open a top-up flow. Minimal and non-intrusive.
  */
-export function CreditIndicator({ balanceLabel, label = "Credits:", onClick, accentColor, style, }) {
+export function CreditIndicator({ balanceLabel, label, onClick, accentColor, style, }) {
     const ctx = useCrediballOptional();
     const resolvedLabel = balanceLabel ?? (ctx?.balance != null ? formatCredits(ctx.balance) : "—");
+    // Prefer the host prop, then the dashboard-published default, then the built-in.
+    const resolvedText = label ?? ctx?.content?.indicatorLabel ?? "Credits:";
     const resolvedOnClick = onClick ?? ctx?.openPaywall;
     return (_jsxs("button", { onClick: resolvedOnClick, style: {
             display: "inline-flex",
@@ -26,5 +28,5 @@ export function CreditIndicator({ balanceLabel, label = "Credits:", onClick, acc
             padding: "4px 12px",
             ...accentStyle(accentColor),
             ...style,
-        }, children: [_jsx("span", { style: { color: theme.inkMuted }, children: label }), _jsx("span", { style: { fontWeight: 600 }, children: resolvedLabel })] }));
+        }, children: [_jsx("span", { style: { color: theme.inkMuted }, children: resolvedText }), _jsx("span", { style: { fontWeight: 600 }, children: resolvedLabel })] }));
 }

package/dist/CreditsBadge.js

@@ -9,9 +9,12 @@ import { useCrediballOptional } from "./CrediballProvider";
  * as the primary figure and an approximate money value beneath it. No Crediball
  * branding.
  */
-export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit balance", onAddCredits, addLabel = "Add credits", accentColor, style, }) {
+export function CreditsBadge({ credits, rate, currency = "EUR", label, onAddCredits, addLabel, accentColor, style, }) {
     const ctx = useCrediballOptional();
     const resolvedCredits = credits ?? ctx?.balance ?? 0;
+    // Prefer the host prop, then the dashboard-published default, then the built-in.
+    const resolvedLabel = label ?? ctx?.content?.badgeLabel ?? "Credit balance";
+    const resolvedAddLabel = addLabel ?? ctx?.content?.badgeAddLabel ?? "Add credits";
     const showMoney = typeof rate === "number" && rate > 0;
     return (_jsxs("div", { style: {
             display: "flex",
@@ -25,7 +28,7 @@ export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit
             fontFamily: theme.font,
             ...accentStyle(accentColor),
             ...style,
-        }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, color: theme.inkMuted }, children: label }), _jsxs("div", { style: { fontSize: 28, fontWeight: 600, color: theme.ink, letterSpacing: "-0.01em" }, children: [formatCredits(resolvedCredits), _jsx("span", { style: { fontSize: 16, fontWeight: 400, color: theme.inkMuted, marginLeft: 6 }, children: "credits" })] }), showMoney ? (_jsxs("div", { style: { fontSize: 13, color: theme.inkMuted, marginTop: 2 }, children: ["\u2248 ", formatMoney(resolvedCredits / rate, currency)] })) : null] }), _jsx("button", { onClick: onAddCredits ?? ctx?.openPaywall, style: {
+        }, children: [_jsxs("div", { children: [_jsx("div", { style: { fontSize: 14, color: theme.inkMuted }, children: resolvedLabel }), _jsxs("div", { style: { fontSize: 28, fontWeight: 600, color: theme.ink, letterSpacing: "-0.01em" }, children: [formatCredits(resolvedCredits), _jsx("span", { style: { fontSize: 16, fontWeight: 400, color: theme.inkMuted, marginLeft: 6 }, children: "credits" })] }), showMoney ? (_jsxs("div", { style: { fontSize: 13, color: theme.inkMuted, marginTop: 2 }, children: ["\u2248 ", formatMoney(resolvedCredits / rate, currency)] })) : null] }), _jsx("button", { onClick: onAddCredits ?? ctx?.openPaywall, style: {
                     appearance: "none",
                     border: "none",
                     cursor: "pointer",
@@ -35,5 +38,5 @@ export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit
                     fontSize: 14,
                     padding: "8px 16px",
                     borderRadius: theme.radiusPill,
-                }, children: addLabel })] }));
+                }, children: resolvedAddLabel })] }));
 }

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/ReferralCard.d.ts

@@ -0,0 +1,30 @@
+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;
+}
+/**
+ * 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, }: ReferralCardProps): import("react").JSX.Element | null;

package/dist/ReferralCard.js

@@ -0,0 +1,70 @@
+"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, }) {
+    const { enabled, link, code, clicks, rewards, rewardCredits, referredRewardCredits, loading, copy, copied, share, } = useReferral();
+    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")
@@ -8,13 +10,16 @@ import { useCrediball } from "../CrediballProvider";
  *
  *   <CrediballLowCreditWarning threshold={20} message="Not enough for one more image." />
  */
-export function CrediballLowCreditWarning({ className, style, threshold, message = "Low credit balance — top up to keep going.", children, }) {
-    const { balance, isLow: contextIsLow } = useCrediball();
-    const isLow = threshold != null && balance != null ? balance < threshold : contextIsLow;
+export function CrediballLowCreditWarning({ className, style, threshold, message, children, }) {
+    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 = isBalanceLow(balance, effectiveThreshold, contextIsLow);
     if (!isLow)
         return null;
     if (typeof children === "function") {
         return _jsx(_Fragment, { children: children({ balance, isLow }) });
     }
-    return (_jsx("span", { className: className, style: { font: "inherit", color: "currentColor", ...style }, children: children ?? message }));
+    const resolvedMessage = message ?? content?.lowCreditMessage ?? "Low credit balance — top up to keep going.";
+    return (_jsx(InlineValue, { className: className, style: style, children: children ?? resolvedMessage }));
 }

package/dist/variables/CrediballTopUpButton.js

@@ -11,7 +11,7 @@ import { theme, accentStyle } from "../theme";
  *   <CrediballTopUpButton>Get more credits</CrediballTopUpButton>
  */
 export function CrediballTopUpButton({ className, style, children, onClick, accentColor }) {
-    const { openPaywall } = useCrediball();
+    const { openPaywall, content } = useCrediball();
     return (_jsx("button", { type: "button", className: className, onClick: onClick ?? openPaywall, style: {
             font: "inherit",
             appearance: "none",
@@ -23,5 +23,5 @@ export function CrediballTopUpButton({ className, style, children, onClick, acce
             padding: "0.5em 1.1em",
             ...accentStyle(accentColor),
             ...style,
-        }, children: children ?? "Add credits" }));
+        }, children: children ?? content?.topUpButtonText ?? "Add credits" }));
 }

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.7.0",
+  "version": "0.9.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.2.0"
+    "@crediball/core": "^0.4.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",