@crediball/react 0.3.7 → 0.5.0

package/dist/CrediballProvider.d.ts

@@ -1,16 +1,54 @@
 import { type ReactNode } from "react";
+import { type PackageOption, type SubscriptionPlanOption } from "./PaywallModal";
+import { type UsagePeriod } from "@crediball/core";
 export interface CrediballProviderProps {
     children: ReactNode;
+    /**
+     * Browser-safe key (cb_pub_...) from the Crediball dashboard. When set
+     * together with `userId`, the provider fetches and live-updates balance,
+     * usage, event costs, and packages — powering useCrediball()'s data fields,
+     * the Tier-2 variable components, and PaywallModal's package list. Omit both
+     * to use the provider in its original, data-less mode (host supplies
+     * everything via props/callbacks).
+     */
+    publishableKey?: string;
+    /** The end user's id, exactly as passed to track() server-side. Required alongside publishableKey. */
+    userId?: string;
+    /** Base URL of the Crediball API. Defaults to the hosted instance. */
+    apiUrl?: string;
+    /** Poll interval while the tab is visible. Default 30s. */
+    pollIntervalMs?: number;
+    /** Override the default "low credits" threshold (defaults to the highest-cost active event). */
+    lowCreditThreshold?: number;
     /**
      * Top-up amounts to offer in the paywall (host decides the meaning, e.g. euros).
      * Match these to the packages you configured in the Crediball dashboard.
+     * Ignored once real packages are available (with publishableKey/userId set).
      */
     amounts?: number[];
     /**
-     * Called when the user picks an amount to top up. Wire this to your checkout or
-     * server-side top-up route. If omitted, picking an amount just closes the modal.
+     * Optional override for the custom-amount top-up. If omitted, the paywall
+     * starts a Crediball-hosted Stripe Checkout itself (using publishableKey +
+     * userId) and redirects — no backend wiring needed, just connect payouts in the
+     * dashboard. Provide this only to run your own top-up/checkout flow instead.
      */
     onTopup?: (amount: number) => void | Promise<void>;
+    /**
+     * Optional override for one-time packages. If omitted, the paywall starts a
+     * Crediball-hosted Stripe Checkout itself and redirects (connect payouts in the
+     * dashboard). Provide this only to run your own flow (e.g. `meter.topup({ userId,
+     * packageId })` server-side).
+     */
+    onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    /**
+     * Called when the user picks a subscription plan. Unlike one-time top-ups,
+     * subscriptions have NO built-in checkout (they need recurring billing your
+     * backend sets up), so the paywall only shows subscription plans when this is
+     * provided — wire it to `meter.subscribe({ userId, planId })` server-side.
+     */
+    onSelectPlan?: (plan: SubscriptionPlanOption) => void | Promise<void>;
+    /** Called when the user cancels their subscription. Call `meter.cancelSubscription({ userId, subscriptionId })` server-side. */
+    onCancelSubscription?: (subscriptionId: string) => void | Promise<void>;
     /**
      * Auto-detect insufficient-credit responses from any fetch() call and open the
      * paywall automatically — no per-call wiring. Defaults to true. Set false to only
@@ -20,9 +58,15 @@ export interface CrediballProviderProps {
      * ndjson (streaming/SSE routes where the error arrives as a stream chunk).
      */
     watchFetch?: boolean;
-    /** Allow a free-form amount entry in the paywall. */
+    /**
+     * Show a free-form amount field in the paywall. Defaults to your dashboard's
+     * custom-topup setting (with its min/max) when packages are loaded — set this
+     * explicitly only to override (e.g. `false` to force-hide it).
+     */
     allowCustom?: boolean;
+    /** Override the custom-amount minimum (defaults to the dashboard's configured minimum). */
     customMin?: number;
+    /** Override the custom-amount maximum (defaults to the dashboard's configured maximum). */
     customMax?: number;
     /** Currency symbol shown in the paywall (default "€"). Match your app's billing currency. */
     currencySymbol?: string;
@@ -42,28 +86,60 @@ interface CrediballContextValue {
     hidePaywall: () => void;
     /** Whether the paywall is currently open. */
     open: boolean;
+    /** Alias of showPaywall — reads better from Tier-2 variable components. */
+    openPaywall: () => void;
+    /** The user's current credit balance. null until loaded, or always null without publishableKey/userId. */
+    balance: number | null;
+    /** Credits consumed in the user's current period (subscription cycle, or calendar month). */
+    usage: UsagePeriod | null;
+    /** Alias of balance — the credits left to spend. */
+    remaining: number | null;
+    /** True once balance drops below the low-credit threshold. */
+    isLow: boolean;
+    /** True while the initial fetch is in flight. */
+    loading: boolean;
+    /** Set when the last fetch failed. */
+    error: Error | null;
+    /** Credit cost of a tracked event, from the live cost catalog. undefined if unknown. */
+    costOf: (event: string) => number | undefined;
+    /** Trigger a top-up (delegates to the `onTopup` prop) and refresh balance/usage on completion. */
+    topUp: (amount: number) => Promise<void>;
+    /** Refetch balance, usage, costs, and packages immediately. No-op without publishableKey/userId. */
+    refresh: () => Promise<void>;
 }
 /**
  * Pattern B, automated. Wrap your app once:
  *
- *   <CrediballProvider amounts={[5, 15, 40]} onTopup={(eur) => checkout(eur)}>
+ *   <CrediballProvider
+ *     publishableKey="cb_pub_..."
+ *     userId={user.id}
+ *     onTopup={(eur) => checkout(eur)}
+ *   >
  *     <App />
  *   </CrediballProvider>
  *
- * Whenever any request returns 402 `insufficient_credits` (your server forwarding
- * Crediball's error), the paywall appears automatically — no extra code per call.
- * You can also open it yourself with useCrediball().showPaywall().
+ * With `publishableKey` + `userId` set, every useCrediball() consumer and every
+ * Tier-2 variable component (<CrediballBalance/>, <CrediballUsage/>, ...) gets
+ * live balance/usage/cost data automatically. Whenever any request returns 402
+ * `insufficient_credits`, the paywall appears automatically — no extra code per
+ * call. You can also open it yourself with useCrediball().showPaywall().
  *
  * 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, amounts, onTopup, watchFetch, allowCustom, customMin, customMax, currencySymbol, 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, title, description, accentColor, }: CrediballProviderProps): import("react").JSX.Element;
 /**
- * Access the paywall controls from anywhere inside <CrediballProvider>.
+ * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *
  * Important: showPaywall() is always safe to call — never add a "paywallAlreadyShown"
  * guard around it. Dismissing the modal ("Not now") does not prevent future calls
  * from reopening it. Call showPaywall() unconditionally on every InsufficientCreditsError.
  */
 export declare function useCrediball(): CrediballContextValue;
+/**
+ * Same as useCrediball(), but returns null instead of throwing outside a
+ * <CrediballProvider>. For components (like CreditsBadge) that work either
+ * standalone via props or auto-wired via a provider.
+ */
+export declare function useCrediballOptional(): CrediballContextValue | null;
 export {};

package/dist/CrediballProvider.js

@@ -1,25 +1,44 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+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";
 const CrediballContext = createContext(null);
+const EMPTY_SNAPSHOT = {
+    balance: null,
+    usage: null,
+    remaining: null,
+    costs: {},
+    packages: null,
+    isLow: false,
+    loading: false,
+    error: null,
+};
+const noopSubscribe = () => () => { };
+const getEmptySnapshot = () => EMPTY_SNAPSHOT;
 /**
  * Pattern B, automated. Wrap your app once:
  *
- *   <CrediballProvider amounts={[5, 15, 40]} onTopup={(eur) => checkout(eur)}>
+ *   <CrediballProvider
+ *     publishableKey="cb_pub_..."
+ *     userId={user.id}
+ *     onTopup={(eur) => checkout(eur)}
+ *   >
  *     <App />
  *   </CrediballProvider>
  *
- * Whenever any request returns 402 `insufficient_credits` (your server forwarding
- * Crediball's error), the paywall appears automatically — no extra code per call.
- * You can also open it yourself with useCrediball().showPaywall().
+ * With `publishableKey` + `userId` set, every useCrediball() consumer and every
+ * Tier-2 variable component (<CrediballBalance/>, <CrediballUsage/>, ...) gets
+ * live balance/usage/cost data automatically. Whenever any request returns 402
+ * `insufficient_credits`, the paywall appears automatically — no extra code per
+ * call. You can also open it yourself with useCrediball().showPaywall().
  *
  * 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, amounts = [5, 10, 20], onTopup, watchFetch = true, allowCustom = false, customMin, customMax, currencySymbol = "€", 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 = "€", title, description, accentColor, }) {
     const [open, setOpen] = useState(false);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
@@ -35,19 +54,139 @@ export function CrediballProvider({ children, amounts = [5, 10, 20], onTopup, wa
             return;
         return subscribeFetchWatcher(() => showPaywallRef.current());
     }, [watchFetch]);
-    const ctx = useMemo(() => ({ showPaywall, hidePaywall, open }), [showPaywall, hidePaywall, open]);
+    // Shared data client — one poller/stream per (publishableKey, userId, apiUrl),
+    // reused by every component reading useCrediball() or a Tier-2 variable.
+    const client = useMemo(() => {
+        if (!publishableKey || !userId)
+            return null;
+        return getCrediballClient({ publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold });
+    }, [publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold]);
+    useEffect(() => {
+        if (!client)
+            return;
+        client.start();
+        return () => client.stop();
+    }, [client]);
+    const snapshot = useSyncExternalStore(client ? client.subscribe : noopSubscribe, client ? client.getSnapshot : getEmptySnapshot, client ? client.getSnapshot : getEmptySnapshot);
+    const costOf = useCallback((event) => client?.costOf(event), [client]);
+    const refresh = useCallback(async () => {
+        await client?.refresh();
+    }, [client]);
+    const topUp = useCallback(async (amount) => {
+        await onTopup?.(amount);
+        notifyBalanceChanged();
+        await client?.refresh();
+    }, [onTopup, client]);
+    const ctx = useMemo(() => ({
+        showPaywall,
+        hidePaywall,
+        open,
+        openPaywall: showPaywall,
+        balance: snapshot.balance,
+        usage: snapshot.usage,
+        remaining: snapshot.remaining,
+        isLow: snapshot.isLow,
+        loading: snapshot.loading,
+        error: snapshot.error,
+        costOf,
+        topUp,
+        refresh,
+    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh]);
+    // The page to return to after Stripe checkout — the one the user is on now.
+    function currentReturnPath() {
+        if (typeof window === "undefined")
+            return undefined;
+        return window.location.pathname + window.location.search;
+    }
+    // Drive a Crediball-hosted Stripe Checkout with just the publishable key — used
+    // when the host didn't wire its own onSelectPackage/onTopup handler, so the
+    // paywall's buttons work out of the box (the developer only has to connect
+    // payouts in the dashboard). Redirects the browser to Stripe on success.
+    async function startBuiltInCheckout(input) {
+        if (!client)
+            return;
+        const { url } = await client.createCheckout({ ...input, returnPath: currentReturnPath() });
+        if (typeof window !== "undefined")
+            window.location.assign(url);
+    }
     async function handleAdd(amount) {
+        // A host-supplied top-up flow always wins.
+        if (onTopup) {
+            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);
+                notifyBalanceChanged();
+                await client?.refresh();
+            }
+            finally {
+                setOpen(false);
+            }
+            return;
+        }
+        if (client) {
+            try {
+                await startBuiltInCheckout({ packageId: pkg.id });
+            }
+            catch (err) {
+                console.error("[crediball] checkout failed:", err);
+            }
+            return;
+        }
+        setOpen(false);
+    }
+    async function handleSelectPlan(plan) {
         try {
-            await onTopup?.(amount);
+            await onSelectPlan?.(plan);
+            notifyBalanceChanged();
+            await client?.refresh();
         }
         finally {
             setOpen(false);
         }
     }
-    return (_jsxs(CrediballContext.Provider, { value: ctx, children: [children, _jsx(PaywallModal, { open: open, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: allowCustom, customMin: customMin, customMax: customMax, currencySymbol: currencySymbol, title: title, description: description, accentColor: accentColor })] }));
+    async function handleCancelSubscription(subscriptionId) {
+        await onCancelSubscription?.(subscriptionId);
+        await client?.refresh();
+    }
+    const pkgs = snapshot.packages;
+    // 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).
+    const customCfg = pkgs?.customTopup;
+    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, 
+                // Subscriptions can't be fulfilled by the built-in checkout (that path is
+                // one-time top-ups only), so only OFFER them when the host wired an
+                // onSelectPlan to fulfill them — otherwise they'd be dead buttons.
+                subscriptionPlans: onSelectPlan ? pkgs?.subscriptionPlans : undefined, 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 })] }));
 }
 /**
- * Access the paywall controls from anywhere inside <CrediballProvider>.
+ * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *
  * Important: showPaywall() is always safe to call — never add a "paywallAlreadyShown"
  * guard around it. Dismissing the modal ("Not now") does not prevent future calls
@@ -60,3 +199,11 @@ export function useCrediball() {
     }
     return ctx;
 }
+/**
+ * Same as useCrediball(), but returns null instead of throwing outside a
+ * <CrediballProvider>. For components (like CreditsBadge) that work either
+ * standalone via props or auto-wired via a provider.
+ */
+export function useCrediballOptional() {
+    return useContext(CrediballContext);
+}

package/dist/CreditIndicator.d.ts

@@ -1,9 +1,14 @@
 import type { CSSProperties } from "react";
-export interface CreditIndicatorProps {
-    /** Pre-formatted balance (e.g. "6.20"). */
-    balanceLabel: string;
+import { type CrediballThemeOverrides } from "./theme";
+export interface CreditIndicatorProps extends CrediballThemeOverrides {
+    /**
+     * Pre-formatted balance (e.g. "6.20"). Omit to read + format it automatically
+     * from an ancestor <CrediballProvider publishableKey userId>.
+     */
+    balanceLabel?: string;
     /** Text before the balance (default "Credits:"). */
     label?: string;
+    /** Defaults to opening the provider's paywall when a <CrediballProvider> is present. */
     onClick?: () => void;
     style?: CSSProperties;
 }
@@ -11,4 +16,4 @@ export interface CreditIndicatorProps {
  * 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 declare function CreditIndicator({ balanceLabel, label, onClick, style, }: CreditIndicatorProps): import("react").JSX.Element;
+export declare function CreditIndicator({ balanceLabel, label, onClick, accentColor, style, }: CreditIndicatorProps): import("react").JSX.Element;

package/dist/CreditIndicator.js

@@ -1,24 +1,30 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { tokens } from "./theme";
+import { theme, accentStyle } from "./theme";
+import { formatCredits } from "./format";
+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, style, }) {
-    return (_jsxs("button", { onClick: onClick, style: {
+export function CreditIndicator({ balanceLabel, label = "Credits:", onClick, accentColor, style, }) {
+    const ctx = useCrediballOptional();
+    const resolvedLabel = balanceLabel ?? (ctx?.balance != null ? formatCredits(ctx.balance) : "—");
+    const resolvedOnClick = onClick ?? ctx?.openPaywall;
+    return (_jsxs("button", { onClick: resolvedOnClick, style: {
             display: "inline-flex",
             alignItems: "center",
             gap: 4,
             appearance: "none",
-            cursor: onClick ? "pointer" : "default",
-            background: tokens.canvas,
-            border: `1px solid ${tokens.hairline}`,
-            borderRadius: tokens.radiusPill,
-            color: tokens.ink,
-            fontFamily: tokens.fontStack,
+            cursor: resolvedOnClick ? "pointer" : "default",
+            background: theme.canvas,
+            border: `1px solid ${theme.hairline}`,
+            borderRadius: theme.radiusPill,
+            color: theme.ink,
+            fontFamily: theme.font,
             fontSize: 14,
             padding: "4px 12px",
+            ...accentStyle(accentColor),
             ...style,
-        }, children: [_jsx("span", { style: { color: tokens.inkMuted }, children: label }), _jsx("span", { style: { fontWeight: 600 }, children: balanceLabel })] }));
+        }, children: [_jsx("span", { style: { color: theme.inkMuted }, children: label }), _jsx("span", { style: { fontWeight: 600 }, children: resolvedLabel })] }));
 }

package/dist/CreditsBadge.d.ts

@@ -1,8 +1,11 @@
 import type { CSSProperties } from "react";
 import { type CrediballThemeOverrides } from "./theme";
 export interface CreditsBadgeProps extends CrediballThemeOverrides {
-    /** The user's raw credit balance (the big number). */
-    credits: number;
+    /**
+     * The user's raw credit balance (the big number). Omit to read it
+     * automatically from an ancestor <CrediballProvider publishableKey userId>.
+     */
+    credits?: number;
     /**
      * Credits per one unit of currency. When set, a derived money value is shown
      * underneath (e.g. credits=840, rate=100 → "≈ €8.40"). Omit to hide it.
@@ -12,7 +15,7 @@ export interface CreditsBadgeProps extends CrediballThemeOverrides {
     currency?: string;
     /** Label shown above the balance. */
     label?: string;
-    /** Called when the user clicks "Add credits". */
+    /** Called when the user clicks "Add credits". Defaults to opening the provider's paywall. */
     onAddCredits?: () => void;
     /** Override the button text. */
     addLabel?: string;

package/dist/CreditsBadge.js

@@ -1,19 +1,17 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { tokens } from "./theme";
-function formatCredits(credits) {
-    return new Intl.NumberFormat(undefined).format(Math.round(credits));
-}
-function formatMoney(amount, currency) {
-    return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(amount);
-}
+import { theme, accentStyle } from "./theme";
+import { formatCredits, formatMoney } from "./format";
+import { useCrediballOptional } from "./CrediballProvider";
 /**
  * Pattern A — Embedded (recommended). Drop into a profile/settings section to
  * show the user's balance with an "Add credits" action. Shows the credit balance
  * 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 = tokens.primary, style, }) {
+export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit balance", onAddCredits, addLabel = "Add credits", accentColor, style, }) {
+    const ctx = useCrediballOptional();
+    const resolvedCredits = credits ?? ctx?.balance ?? 0;
     const showMoney = typeof rate === "number" && rate > 0;
     return (_jsxs("div", { style: {
             display: "flex",
@@ -21,20 +19,21 @@ export function CreditsBadge({ credits, rate, currency = "EUR", label = "Credit
             justifyContent: "space-between",
             gap: 16,
             padding: 24,
-            border: `1px solid ${tokens.hairline}`,
-            borderRadius: tokens.radiusCard,
-            background: tokens.canvas,
-            fontFamily: tokens.fontStack,
+            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: 14, color: tokens.inkMuted }, children: label }), _jsxs("div", { style: { fontSize: 28, fontWeight: 600, color: tokens.ink, letterSpacing: "-0.01em" }, children: [formatCredits(credits), _jsx("span", { style: { fontSize: 16, fontWeight: 400, color: tokens.inkMuted, marginLeft: 6 }, children: "credits" })] }), showMoney ? (_jsxs("div", { style: { fontSize: 13, color: tokens.inkMuted, marginTop: 2 }, children: ["\u2248 ", formatMoney(credits / rate, currency)] })) : null] }), _jsx("button", { onClick: onAddCredits, 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: {
                     appearance: "none",
                     border: "none",
                     cursor: "pointer",
-                    background: accentColor,
-                    color: tokens.onPrimary,
-                    fontFamily: tokens.fontStack,
+                    background: theme.accent,
+                    color: theme.onAccent,
+                    fontFamily: theme.font,
                     fontSize: 14,
-                    padding: "8px 18px",
-                    borderRadius: tokens.radiusPill,
+                    padding: "8px 16px",
+                    borderRadius: theme.radiusPill,
                 }, children: addLabel })] }));
 }

package/dist/PaywallModal.d.ts

@@ -72,6 +72,8 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     onClose?: () => void;
     /** When true, show a free-form amount field in addition to the preset buttons. */
     allowCustom?: boolean;
+    /** Button label for the free-form amount field (default "Add"). */
+    addButtonText?: string;
     /** Minimum custom amount (default 1). */
     customMin?: number;
     /** Optional maximum custom amount. */
@@ -79,14 +81,26 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     /** Currency symbol shown beside the custom field (default "€"). */
     currencySymbol?: string;
     /**
-     * When provided, a "Your balance" row is shown at the top of the modal.
-     * Useful for the paywall context so the user can see why the modal appeared.
+     * When provided, a compact "Balance" column is shown at the top of the
+     * modal (beside "Usage" if that's provided too) so the user can see why
+     * the modal appeared.
      */
     balance?: number;
     /** Credits per one currency unit — used to derive the ≈ money value beside the balance. */
     balanceRate?: number;
     /** ISO 4217 currency for the derived balance money value (default "EUR"). */
     currency?: string;
+    /** Credits used this period — shown as a second column beside balance, when provided. */
+    usage?: number;
+    /** Label above the usage column (default "Usage"). */
+    usageLabel?: string;
+    /** Hide the "Powered by Crediball" footer line (default false). */
+    hideBranding?: boolean;
     style?: CSSProperties;
 }
-export declare function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, customMin, customMax, currencySymbol, balance, balanceRate, currency, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;
+/**
+ * Pattern B — Paywall moment. Render when a user has insufficient credits to
+ * 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;

package/dist/PaywallModal.js

@@ -1,37 +1,46 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { tokens } from "./theme";
+import { useEffect, useRef, useState } from "react";
+import { theme, accentStyle } from "./theme";
+import { formatCredits, formatMoney } from "./format";
+/** Shared uppercase eyebrow-label style used above the subscribe/buy-credits sections. */
+function sectionLabelStyle(marginBottom) {
+    return {
+        fontSize: 11,
+        fontWeight: 600,
+        letterSpacing: "0.06em",
+        textTransform: "uppercase",
+        color: theme.inkMuted,
+        marginBottom,
+    };
+}
 /**
  * Pattern B — Paywall moment. Render when a user has insufficient credits to
- * continue. The host controls when it appears; no Crediball branding.
+ * continue. The host controls when it appears; shows a small "Powered by
+ * Crediball" line by default (set `hideBranding` to remove it).
  */
-function fmtCredits(n) {
-    return new Intl.NumberFormat().format(Math.round(n));
-}
-function fmtMoney(n, currency) {
-    try {
-        return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(n);
-    }
-    catch {
-        return `${n.toFixed(2)} ${currency}`;
-    }
-}
-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, customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", accentColor = tokens.primary, style, }) {
-    // Stack the top-up buttons one-per-line on narrow (mobile) screens.
+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, }) {
+    // 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
+    // the layout correctly respond when the dialog is rendered inside a
+    // narrower container (e.g. a device-mockup preview) on a wide screen.
     const [narrow, setNarrow] = useState(false);
+    const overlayRef = useRef(null);
     const [customValue, setCustomValue] = useState("");
     const [customError, setCustomError] = useState(null);
     const [cancelPending, setCancelPending] = useState(false);
     const [cancelDone, setCancelDone] = useState(false);
     useEffect(() => {
-        if (typeof window === "undefined" || !window.matchMedia)
+        const el = overlayRef.current;
+        if (!el || typeof ResizeObserver === "undefined")
             return;
-        const mq = window.matchMedia("(max-width: 480px)");
-        const update = () => setNarrow(mq.matches);
-        update();
-        mq.addEventListener("change", update);
-        return () => mq.removeEventListener("change", update);
+        const observer = new ResizeObserver((entries) => {
+            const width = entries[0]?.contentRect.width ?? el.clientWidth;
+            setNarrow(width <= 480);
+        });
+        observer.observe(el);
+        return () => observer.disconnect();
     }, []);
     if (!open)
         return null;
@@ -69,14 +78,16 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         appearance: "none",
         border: "none",
         cursor: "pointer",
-        background: accentColor,
-        color: tokens.onPrimary,
-        fontFamily: tokens.fontStack,
-        fontSize: 17,
-        padding: "11px 22px",
-        borderRadius: tokens.radiusPill,
+        background: theme.accent,
+        color: theme.onAccent,
+        fontFamily: theme.font,
+        fontWeight: 500,
+        fontSize: 14,
+        lineHeight: "24px",
+        padding: "8px 16px",
+        borderRadius: theme.radiusPill,
     };
-    return (_jsx("div", { role: "dialog", "aria-modal": "true", style: {
+    return (_jsx("div", { ref: overlayRef, role: "dialog", "aria-modal": "true", style: {
             position: "fixed",
             inset: 0,
             zIndex: 2147483647,
@@ -84,37 +95,42 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
             alignItems: "center",
             justifyContent: "center",
             padding: 24,
-            background: tokens.overlay,
-            fontFamily: tokens.fontStack,
+            background: theme.overlay,
+            fontFamily: theme.font,
+            // Mobile Safari/Chrome auto-inflate font sizes in narrow columns for
+            // readability, which throws off this dialog's fixed layout (extra
+            // text wrapping eats the padding around it). Opt out — sizes here
+            // are already chosen deliberately.
+            WebkitTextSizeAdjust: "100%",
+            textSizeAdjust: "100%",
+            ...accentStyle(accentColor),
         }, onClick: onClose, children: _jsxs("div", { onClick: (e) => e.stopPropagation(), style: {
                 width: "100%",
                 maxWidth: 420,
                 padding: 32,
-                borderRadius: tokens.radiusCard,
-                background: tokens.canvas,
+                borderRadius: theme.radiusCard,
+                background: theme.canvas,
+                boxShadow: "0px 4px 6px 0px rgba(0, 0, 0, 0.09)",
                 ...style,
             }, children: [balance != null && (_jsxs("div", { style: {
-                        marginBottom: 24,
-                        paddingBottom: 20,
-                        borderBottom: `1px solid ${tokens.hairline}`,
-                    }, children: [_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: 4,
-                            }, children: "Your balance" }), _jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8, flexWrap: "wrap" }, children: [_jsxs("span", { style: { fontSize: 22, fontWeight: 600, color: tokens.ink }, children: [fmtCredits(balance), " credits"] }), balanceRate && balanceRate > 0 ? (_jsxs("span", { style: { fontSize: 13, color: tokens.inkMuted }, children: ["\u2248 ", fmtMoney(balance / balanceRate, currency)] })) : null] })] })), _jsx("h3", { style: { margin: 0, fontSize: 24, fontWeight: 600, color: tokens.ink, letterSpacing: "-0.01em" }, children: activeSubscription
+                        display: "flex",
+                        gap: 16,
+                        marginBottom: 16,
+                        paddingBottom: 16,
+                        borderBottom: `1px solid ${theme.hairline}`,
+                    }, children: [_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2 }, children: [_jsx("span", { style: { fontSize: 11, color: theme.inkMuted }, children: "Balance" }), _jsxs("span", { style: { fontSize: 12, fontWeight: 500, color: theme.ink }, children: [formatCredits(balance), balanceRate && balanceRate > 0
+                                            ? ` (≈${formatMoney(balance / balanceRate, currency)})`
+                                            : ""] })] }), usage != null ? (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 2 }, children: [_jsx("span", { style: { fontSize: 11, color: theme.inkMuted }, children: usageLabel }), _jsxs("span", { style: { fontSize: 12, fontWeight: 500, color: theme.ink }, children: [formatCredits(usage), " credits"] })] })) : null] })), _jsx("h3", { style: { margin: 0, fontSize: 18, fontWeight: 600, lineHeight: "28px", color: theme.ink }, children: activeSubscription
                         ? "You've used all your credits for this period."
-                        : title }), _jsx("p", { style: { marginTop: 8, marginBottom: 0, fontSize: 14, color: tokens.inkMuted }, children: activeSubscription
+                        : title }), _jsx("p", { style: { marginTop: 8, marginBottom: 0, fontSize: 13, color: theme.inkMuted }, children: activeSubscription
                         ? `Your ${activeSubscription.planName} credits renew on ${new Date(activeSubscription.currentPeriodEnd).toLocaleDateString()}.`
                         : description }), activeSubscription && (_jsxs("div", { style: {
                         marginTop: 16,
                         padding: "12px 16px",
-                        borderRadius: tokens.radiusCard,
+                        borderRadius: theme.radiusCard,
                         background: "#f5f5f7",
-                        border: `1px solid ${tokens.hairline}`,
-                    }, children: [_jsx("div", { style: { fontSize: 13, fontWeight: 600, color: tokens.ink }, children: cancelDone ? "Subscription canceled" : `${activeSubscription.planName} · ${activeSubscription.planPeriod}` }), !cancelDone && (_jsx("button", { onClick: handleCancelSubscription, disabled: cancelPending, style: {
+                        border: `1px solid ${theme.hairline}`,
+                    }, children: [_jsx("div", { style: { fontSize: 13, fontWeight: 600, color: theme.ink }, children: cancelDone ? "Subscription canceled" : `${activeSubscription.planName} · ${activeSubscription.planPeriod}` }), !cancelDone && (_jsx("button", { onClick: handleCancelSubscription, disabled: cancelPending, style: {
                                 marginTop: 8,
                                 appearance: "none",
                                 border: "none",
@@ -122,61 +138,41 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                 cursor: cancelPending ? "default" : "pointer",
                                 padding: 0,
                                 fontSize: 13,
-                                color: tokens.inkMuted,
-                                fontFamily: tokens.fontStack,
+                                color: theme.inkMuted,
+                                fontFamily: theme.font,
                                 textDecoration: "underline",
-                            }, children: cancelPending ? "Canceling…" : "Cancel subscription" }))] })), !activeSubscription && subscriptionPlans && subscriptionPlans.length > 0 && (_jsxs("div", { style: { marginTop: 24 }, children: [_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: 8,
-                            }, children: "Subscribe" }), _jsx("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: subscriptionPlans.map((plan) => (_jsxs("button", { onClick: () => onSelectPlan?.(plan), style: {
+                            }, children: cancelPending ? "Canceling…" : "Cancel subscription" }))] })), !activeSubscription && subscriptionPlans && subscriptionPlans.length > 0 && (_jsxs("div", { style: { marginTop: 24 }, children: [_jsx("div", { style: sectionLabelStyle(8), children: "Subscribe" }), _jsx("div", { style: { display: "flex", flexDirection: "column", gap: 8 }, children: subscriptionPlans.map((plan) => (_jsxs("button", { onClick: () => onSelectPlan?.(plan), style: {
                                     ...buttonStyle,
                                     flex: "none",
                                     display: "flex",
                                     justifyContent: "space-between",
                                     alignItems: "center",
-                                }, children: [_jsx("span", { children: plan.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [fmtMoney(plan.price, currency), "/", plan.period === "monthly" ? "mo" : "yr", " \u00B7 ", fmtCredits(plan.credits), " cr"] })] }, plan.id))) })] })), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10, marginTop: 24 }, children: [(!activeSubscription && subscriptionPlans && subscriptionPlans.length > 0) && (_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: -2,
-                            }, children: activeSubscription ? "Add extra credits" : "Or buy credits" })), activeSubscription && packages && packages.length > 0 && (_jsx("div", { style: {
-                                fontSize: 11,
-                                fontWeight: 600,
-                                letterSpacing: "0.06em",
-                                textTransform: "uppercase",
-                                color: tokens.inkMuted,
-                                marginBottom: -2,
-                            }, children: "Add extra credits" })), packages && packages.length > 0
-                            ? packages.map((pkg) => (_jsxs("button", { onClick: () => onSelectPackage?.(pkg), style: { ...buttonStyle, flex: "none", display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [_jsx("span", { children: pkg.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [fmtMoney(pkg.price, currency), " \u00B7 ", fmtCredits(pkg.credits), " cr"] })] }, pkg.id)))
-                            : (!activeSubscription && (_jsx("div", { style: { display: "flex", flexDirection: narrow ? "column" : "row", gap: 12 }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) })))] }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 17, color: tokens.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
+                                }, children: [_jsx("span", { children: plan.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [formatMoney(plan.price, currency), "/", plan.period === "monthly" ? "mo" : "yr", " \u00B7 ", formatCredits(plan.credits), " cr"] })] }, plan.id))) })] })), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10, marginTop: 24 }, children: [(!activeSubscription && subscriptionPlans && subscriptionPlans.length > 0) && (_jsx("div", { style: sectionLabelStyle(-2), children: "Or buy credits" })), activeSubscription && packages && packages.length > 0 && (_jsx("div", { style: sectionLabelStyle(-2), children: "Add extra credits" })), packages && packages.length > 0
+                            ? packages.map((pkg) => (_jsxs("button", { onClick: () => onSelectPackage?.(pkg), style: { ...buttonStyle, flex: "none", display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [_jsx("span", { children: pkg.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [formatMoney(pkg.price, currency), " \u00B7 ", formatCredits(pkg.credits), " cr"] })] }, pkg.id)))
+                            : (!activeSubscription && (_jsx("div", { style: { display: "flex", flexDirection: narrow ? "column" : "row", gap: 12 }, children: amounts.map((amount) => (_jsxs("button", { onClick: () => onAdd?.(amount), style: buttonStyle, children: [amountPrefix, amount] }, amount))) })))] }), allowCustom ? (_jsxs("div", { style: { marginTop: 12 }, children: [_jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx("span", { style: { fontSize: 14, color: theme.inkMuted }, children: currencySymbol }), _jsx("input", { value: customValue, onChange: (e) => setCustomValue(e.target.value), inputMode: "decimal", placeholder: String(customMin), style: {
                                         flex: 1,
                                         minWidth: 0,
                                         appearance: "none",
-                                        fontFamily: tokens.fontStack,
-                                        fontSize: 17,
-                                        padding: "11px 14px",
-                                        borderRadius: tokens.radiusPill,
-                                        border: `1px solid ${tokens.hairline}`,
-                                        color: tokens.ink,
-                                        background: tokens.canvas,
+                                        fontFamily: theme.font,
+                                        fontSize: 14,
+                                        lineHeight: "20px",
+                                        padding: "8px 12px",
+                                        borderRadius: theme.radiusPill,
+                                        border: `1px solid ${theme.hairline}`,
+                                        color: theme.ink,
+                                        background: theme.canvas,
                                         outline: "none",
-                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: "Add" })] }), customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: accentColor }, 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, onClose ? (_jsx("button", { onClick: onClose, style: {
                         width: "100%",
                         marginTop: 12,
                         appearance: "none",
                         border: "none",
                         cursor: "pointer",
                         background: "transparent",
-                        color: tokens.inkMuted,
-                        fontFamily: tokens.fontStack,
-                        fontSize: 14,
-                        padding: "11px 22px",
-                        borderRadius: tokens.radiusPill,
-                    }, children: "Not now" })) : null] }) }));
+                        color: theme.inkMuted,
+                        fontFamily: theme.font,
+                        fontSize: 12,
+                        padding: "8px 16px",
+                        borderRadius: theme.radiusPill,
+                    }, children: "Not now" })) : null, !hideBranding && (_jsx("div", { style: { display: "flex", justifyContent: "flex-end", marginTop: 10 }, children: _jsx("span", { style: { fontSize: 10, color: theme.inkMuted }, children: "Powered by Crediball." }) }))] }) }));
 }

package/dist/creditEvent.d.ts

@@ -1,21 +1,8 @@
 /**
- * Global custom-event bus for insufficient-credits signals.
- *
- * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
- * server action catch block — can call notifyInsufficientCredits() and every
- * mounted CrediballProvider / usePaywall instance will open the paywall.
- *
- * This decouples the signal source from the UI, so the paywall works regardless
- * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ * Re-exported from @crediball/core so the event bus is shared between
+ * @crediball/react, @crediball/elements, and any core-based data client —
+ * a signal fired from one surface (e.g. the web-components layer) is seen by
+ * every other. Kept as a distinct module path for backwards compatibility
+ * with existing imports inside this package.
  */
-/**
- * Fire the global insufficient-credits signal. Safe to call from anywhere in
- * the app — server components excluded (DOM only). Every mounted paywall
- * component will react to it automatically.
- */
-export declare function notifyInsufficientCredits(): void;
-/**
- * Subscribe to the global insufficient-credits signal.
- * Returns an unsubscribe function for use in useEffect cleanup.
- */
-export declare function subscribeInsufficientCredits(listener: () => void): () => void;
+export { notifyInsufficientCredits, subscribeInsufficientCredits } from "@crediball/core";

package/dist/creditEvent.js

@@ -1,31 +1,8 @@
 /**
- * Global custom-event bus for insufficient-credits signals.
- *
- * Any code — a useChat onError, an XHR error handler, a Redux middleware, a
- * server action catch block — can call notifyInsufficientCredits() and every
- * mounted CrediballProvider / usePaywall instance will open the paywall.
- *
- * This decouples the signal source from the UI, so the paywall works regardless
- * of how the HTTP request was made (fetch, XHR, EventSource, AI SDK internals…).
+ * Re-exported from @crediball/core so the event bus is shared between
+ * @crediball/react, @crediball/elements, and any core-based data client —
+ * a signal fired from one surface (e.g. the web-components layer) is seen by
+ * every other. Kept as a distinct module path for backwards compatibility
+ * with existing imports inside this package.
  */
-const EVENT = "crediball:insufficient-credits";
-/**
- * Fire the global insufficient-credits signal. Safe to call from anywhere in
- * the app — server components excluded (DOM only). Every mounted paywall
- * component will react to it automatically.
- */
-export function notifyInsufficientCredits() {
-    if (typeof window === "undefined")
-        return;
-    window.dispatchEvent(new CustomEvent(EVENT));
-}
-/**
- * Subscribe to the global insufficient-credits signal.
- * Returns an unsubscribe function for use in useEffect cleanup.
- */
-export function subscribeInsufficientCredits(listener) {
-    if (typeof window === "undefined")
-        return () => { };
-    window.addEventListener(EVENT, listener);
-    return () => window.removeEventListener(EVENT, listener);
-}
+export { notifyInsufficientCredits, subscribeInsufficientCredits } from "@crediball/core";

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+/** 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;

package/dist/format.js

@@ -0,0 +1,13 @@
+/** 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}`;
+    }
+}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
 export { CreditsBadge, type CreditsBadgeProps } from "./CreditsBadge";
 export { PaywallModal, type PaywallModalProps, type PackageOption, type SubscriptionPlanOption, type ActiveSubscriptionInfo, } from "./PaywallModal";
 export { CreditIndicator, type CreditIndicatorProps } from "./CreditIndicator";
-export { CrediballProvider, useCrediball, type CrediballProviderProps, } from "./CrediballProvider";
+export { CrediballProvider, useCrediball, useCrediballOptional, type CrediballProviderProps, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, type UsePaywallProps, type UsePaywallResult, } from "./usePaywall";
-export { tokens, type CrediballThemeOverrides } from "./theme";
+export { tokens, theme, cssVars, accentStyle, type CrediballThemeOverrides } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
+export { CrediballBalance, type CrediballBalanceProps } from "./variables/CrediballBalance";
+export { CrediballUsage, type CrediballUsageProps } from "./variables/CrediballUsage";
+export { CrediballTopUpButton, type CrediballTopUpButtonProps } from "./variables/CrediballTopUpButton";
+export { CrediballLowCreditWarning, type CrediballLowCreditWarningProps, } from "./variables/CrediballLowCreditWarning";

package/dist/index.js

@@ -3,7 +3,12 @@
 export { CreditsBadge } from "./CreditsBadge";
 export { PaywallModal, } from "./PaywallModal";
 export { CreditIndicator } from "./CreditIndicator";
-export { CrediballProvider, useCrediball, } from "./CrediballProvider";
+export { CrediballProvider, useCrediball, useCrediballOptional, } from "./CrediballProvider";
 export { usePaywall, isInsufficientCreditsError, } from "./usePaywall";
-export { tokens } from "./theme";
+export { tokens, theme, cssVars, accentStyle } from "./theme";
 export { notifyInsufficientCredits } from "./creditEvent";
+// Tier 2 — "variables" you place anywhere inside <CrediballProvider>.
+export { CrediballBalance } from "./variables/CrediballBalance";
+export { CrediballUsage } from "./variables/CrediballUsage";
+export { CrediballTopUpButton } from "./variables/CrediballTopUpButton";
+export { CrediballLowCreditWarning, } from "./variables/CrediballLowCreditWarning";

package/dist/theme.d.ts

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 /**
  * Self-contained design tokens (no Tailwind / external CSS) so these components
  * look right when dropped into any host app. Mirrors the Crediball design
@@ -19,3 +20,41 @@ export type CrediballThemeOverrides = {
     /** Override the accent color (defaults to Action Blue #0066cc). */
     accentColor?: string;
 };
+/**
+ * `--crediball-*` CSS custom property names. A host app can set these once
+ * (on `:root` or any ancestor) to theme every embedded component — including
+ * ones rendered later, or across `@crediball/elements` web components — without
+ * passing props. Components read these via `theme` below, which wraps each
+ * token in `var(--crediball-x, <tokens fallback>)`.
+ */
+export declare const cssVars: {
+    readonly accent: "--crediball-accent";
+    readonly ink: "--crediball-ink";
+    readonly inkMuted: "--crediball-ink-muted";
+    readonly canvas: "--crediball-canvas";
+    readonly hairline: "--crediball-hairline";
+    readonly onAccent: "--crediball-on-accent";
+    readonly overlay: "--crediball-overlay";
+    readonly radiusPill: "--crediball-radius";
+    readonly radiusCard: "--crediball-radius-card";
+    readonly font: "--crediball-font";
+};
+/** CSS-var-wrapped values for use in component styles — prefer these over raw `tokens`. */
+export declare const theme: {
+    accent: string;
+    ink: string;
+    inkMuted: string;
+    canvas: string;
+    hairline: string;
+    onAccent: string;
+    overlay: string;
+    radiusPill: string;
+    radiusCard: string;
+    font: string;
+};
+/**
+ * Sets `--crediball-accent` on a component's root element when `accentColor`
+ * is passed, so the prop keeps working exactly as before while everything
+ * underneath consistently reads `theme.accent`. Spread onto the root `style`.
+ */
+export declare function accentStyle(accentColor?: string): CSSProperties;

package/dist/theme.js

@@ -15,3 +15,46 @@ export const tokens = {
     radiusPill: 9999,
     radiusCard: 18,
 };
+/**
+ * `--crediball-*` CSS custom property names. A host app can set these once
+ * (on `:root` or any ancestor) to theme every embedded component — including
+ * ones rendered later, or across `@crediball/elements` web components — without
+ * passing props. Components read these via `theme` below, which wraps each
+ * token in `var(--crediball-x, <tokens fallback>)`.
+ */
+export const cssVars = {
+    accent: "--crediball-accent",
+    ink: "--crediball-ink",
+    inkMuted: "--crediball-ink-muted",
+    canvas: "--crediball-canvas",
+    hairline: "--crediball-hairline",
+    onAccent: "--crediball-on-accent",
+    overlay: "--crediball-overlay",
+    radiusPill: "--crediball-radius",
+    radiusCard: "--crediball-radius-card",
+    font: "--crediball-font",
+};
+function v(name, fallback) {
+    return `var(${name}, ${fallback})`;
+}
+/** CSS-var-wrapped values for use in component styles — prefer these over raw `tokens`. */
+export const theme = {
+    accent: v(cssVars.accent, tokens.primary),
+    ink: v(cssVars.ink, tokens.ink),
+    inkMuted: v(cssVars.inkMuted, tokens.inkMuted),
+    canvas: v(cssVars.canvas, tokens.canvas),
+    hairline: v(cssVars.hairline, tokens.hairline),
+    onAccent: v(cssVars.onAccent, tokens.onPrimary),
+    overlay: v(cssVars.overlay, tokens.overlay),
+    radiusPill: v(cssVars.radiusPill, `${tokens.radiusPill}px`),
+    radiusCard: v(cssVars.radiusCard, `${tokens.radiusCard}px`),
+    font: v(cssVars.font, tokens.fontStack),
+};
+/**
+ * Sets `--crediball-accent` on a component's root element when `accentColor`
+ * is passed, so the prop keeps working exactly as before while everything
+ * underneath consistently reads `theme.accent`. Spread onto the root `style`.
+ */
+export function accentStyle(accentColor) {
+    return accentColor ? { [cssVars.accent]: accentColor } : {};
+}

package/dist/variables/CrediballBalance.d.ts

@@ -0,0 +1,26 @@
+import type { CSSProperties, ReactNode } from "react";
+export interface CrediballBalanceRenderProps {
+    balance: number | null;
+    loading: boolean;
+}
+export interface CrediballBalanceProps {
+    className?: string;
+    style?: CSSProperties;
+    /** Format the raw number. Defaults to a locale-formatted whole number. */
+    format?: (balance: number) => string;
+    /**
+     * Static content overrides the balance entirely. Pass a function to render
+     * fully custom markup from the live value (the escape hatch for anything
+     * this component's default <span> doesn't cover).
+     */
+    children?: ReactNode | ((props: CrediballBalanceRenderProps) => ReactNode);
+}
+/**
+ * Tier 2 — a "variable" you drop anywhere inside <CrediballProvider>. Renders
+ * as an inline <span> that inherits the surrounding font, size, and color
+ * (`font: inherit; color: currentColor`) so it looks native wherever it's
+ * placed — a navbar, a sentence, a settings row.
+ *
+ *   <p>You have <CrediballBalance /> credits left.</p>
+ */
+export declare function CrediballBalance({ className, style, format, children }: CrediballBalanceProps): import("react").JSX.Element;

package/dist/variables/CrediballBalance.js

@@ -0,0 +1,19 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCrediball } from "../CrediballProvider";
+import { formatCredits } from "../format";
+/**
+ * Tier 2 — a "variable" you drop anywhere inside <CrediballProvider>. Renders
+ * as an inline <span> that inherits the surrounding font, size, and color
+ * (`font: inherit; color: currentColor`) so it looks native wherever it's
+ * placed — a navbar, a sentence, a settings row.
+ *
+ *   <p>You have <CrediballBalance /> credits left.</p>
+ */
+export function CrediballBalance({ className, style, format = formatCredits, children }) {
+    const { balance, loading } = useCrediball();
+    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)) }));
+}

package/dist/variables/CrediballLowCreditWarning.d.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties, ReactNode } from "react";
+export interface CrediballLowCreditWarningRenderProps {
+    balance: number | null;
+    isLow: boolean;
+}
+export interface CrediballLowCreditWarningProps {
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Override the provider's default threshold (highest-cost active event) for
+     * just this instance — e.g. warn earlier next to an expensive action.
+     */
+    threshold?: number;
+    /** Message shown when low. Defaults to a generic nudge. */
+    message?: string;
+    children?: ReactNode | ((props: CrediballLowCreditWarningRenderProps) => ReactNode);
+}
+/**
+ * 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")
+ * or globally near the top of the app.
+ *
+ *   <CrediballLowCreditWarning threshold={20} message="Not enough for one more image." />
+ */
+export declare function CrediballLowCreditWarning({ className, style, threshold, message, children, }: CrediballLowCreditWarningProps): import("react").JSX.Element | null;

package/dist/variables/CrediballLowCreditWarning.js

@@ -0,0 +1,20 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCrediball } from "../CrediballProvider";
+/**
+ * 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")
+ * or globally near the top of the app.
+ *
+ *   <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;
+    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 }));
+}

package/dist/variables/CrediballTopUpButton.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type CrediballThemeOverrides } from "../theme";
+export interface CrediballTopUpButtonProps extends CrediballThemeOverrides {
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    /** Defaults to opening the provider's paywall. */
+    onClick?: () => void;
+}
+/**
+ * Tier 2 — a themeable call-to-action that opens the paywall. Inherits the
+ * surrounding font; background/text color come from the same `--crediball-*`
+ * variables as every other component, so it matches PaywallModal and
+ * CreditsBadge without extra styling.
+ *
+ *   <CrediballTopUpButton>Get more credits</CrediballTopUpButton>
+ */
+export declare function CrediballTopUpButton({ className, style, children, onClick, accentColor }: CrediballTopUpButtonProps): import("react").JSX.Element;

package/dist/variables/CrediballTopUpButton.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCrediball } from "../CrediballProvider";
+import { theme, accentStyle } from "../theme";
+/**
+ * Tier 2 — a themeable call-to-action that opens the paywall. Inherits the
+ * surrounding font; background/text color come from the same `--crediball-*`
+ * variables as every other component, so it matches PaywallModal and
+ * CreditsBadge without extra styling.
+ *
+ *   <CrediballTopUpButton>Get more credits</CrediballTopUpButton>
+ */
+export function CrediballTopUpButton({ className, style, children, onClick, accentColor }) {
+    const { openPaywall } = useCrediball();
+    return (_jsx("button", { type: "button", className: className, onClick: onClick ?? openPaywall, style: {
+            font: "inherit",
+            appearance: "none",
+            border: "none",
+            cursor: "pointer",
+            color: theme.onAccent,
+            background: theme.accent,
+            borderRadius: theme.radiusPill,
+            padding: "0.5em 1.1em",
+            ...accentStyle(accentColor),
+            ...style,
+        }, children: children ?? "Add credits" }));
+}

package/dist/variables/CrediballUsage.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { UsagePeriod } from "@crediball/core";
+export interface CrediballUsageRenderProps {
+    usage: UsagePeriod | null;
+    value: number | null;
+    loading: boolean;
+}
+export interface CrediballUsageProps {
+    className?: string;
+    style?: CSSProperties;
+    /** Show credits consumed this period, or credits remaining. Default "used". */
+    show?: "used" | "remaining";
+    /** Format the raw number. Defaults to a locale-formatted whole number. */
+    format?: (value: number) => string;
+    children?: ReactNode | ((props: CrediballUsageRenderProps) => ReactNode);
+}
+/**
+ * Tier 2 — credits consumed in the user's current period (their subscription's
+ * billing cycle, or the calendar month for non-subscribers). Inline, inherits
+ * host styling. Pass `show="remaining"` to render the balance instead.
+ *
+ *   <p><CrediballUsage /> credits used this month.</p>
+ */
+export declare function CrediballUsage({ className, style, show, format, children, }: CrediballUsageProps): import("react").JSX.Element;

package/dist/variables/CrediballUsage.js

@@ -0,0 +1,19 @@
+"use client";
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCrediball } from "../CrediballProvider";
+import { formatCredits } from "../format";
+/**
+ * Tier 2 — credits consumed in the user's current period (their subscription's
+ * billing cycle, or the calendar month for non-subscribers). Inline, inherits
+ * host styling. Pass `show="remaining"` to render the balance instead.
+ *
+ *   <p><CrediballUsage /> credits used this month.</p>
+ */
+export function CrediballUsage({ className, style, show = "used", format = formatCredits, children, }) {
+    const { usage, remaining, loading } = useCrediball();
+    const value = show === "remaining" ? remaining : (usage?.usedCredits ?? null);
+    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)) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.3.7",
+  "version": "0.5.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",
@@ -50,6 +50,9 @@
   "peerDependencies": {
     "react": ">=18"
   },
+  "dependencies": {
+    "@crediball/core": "^0.1.1"
+  },
   "devDependencies": {
     "@types/react": "^18.3.11",
     "typescript": "^5.6.3"