@crediball/react 0.3.6 → 0.4.0

package/dist/CrediballProvider.d.ts

@@ -1,16 +1,43 @@
 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.
+     * Called when the user picks an amount to top up (legacy flat-amount flow).
+     * Wire this to your checkout or server-side top-up route. If omitted,
+     * picking an amount just closes the modal.
      */
     onTopup?: (amount: number) => void | Promise<void>;
+    /** Called when the user picks a one-time package. Call `meter.topup({ userId, packageId })` server-side. */
+    onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    /** Called when the user picks a subscription plan. Call `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
@@ -42,28 +69,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 = false, customMin, customMax, currencySymbol = "€", title, description, accentColor, }) {
     const [open, setOpen] = useState(false);
     const showPaywall = useCallback(() => setOpen(true), []);
     const hidePaywall = useCallback(() => setOpen(false), []);
@@ -35,19 +54,81 @@ 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]);
     async function handleAdd(amount) {
         try {
-            await onTopup?.(amount);
+            await topUp(amount);
+        }
+        finally {
+            setOpen(false);
+        }
+    }
+    async function handleSelectPackage(pkg) {
+        try {
+            await onSelectPackage?.(pkg);
+            notifyBalanceChanged();
+            await client?.refresh();
+        }
+        finally {
+            setOpen(false);
+        }
+    }
+    async function handleSelectPlan(plan) {
+        try {
+            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;
+    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: allowCustom, customMin: customMin, customMax: customMax, 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 +141,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;