@crediball/react 0.17.0 → 0.19.0

package/dist/CrediballProvider.d.ts

@@ -1,6 +1,6 @@
 import { type ReactNode } from "react";
 import { type PackageOption, type SubscriptionPlanOption } from "./PaywallModal";
-import { type UsagePeriod, type PackagesPayload, type CrediballUiContent } from "@crediball/core";
+import { type UsagePeriod, type PackagesPayload, type CrediballUiContent, type ColorScheme } from "@crediball/core";
 export interface CrediballProviderProps {
     children: ReactNode;
     /**
@@ -22,8 +22,12 @@ export interface CrediballProviderProps {
     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).
+     * Only used in data-less mode (no publishableKey/userId), where there's no
+     * dashboard catalog to fall back to and the host is fully responsible for
+     * `onTopup`. Ignored whenever publishableKey + userId are set — the paywall
+     * then shows your dashboard's real packages, or no top-up button at all if
+     * you haven't configured any yet, rather than a button that can't actually
+     * charge anything.
      */
     amounts?: number[];
     /**
@@ -88,7 +92,7 @@ export interface CrediballProviderProps {
     customMax?: number;
     /**
      * Show a "Have a promo code?" field in the paywall. Auto-derived from your
-     * dashboard's Growth → Promotions config: shown automatically once you have
+     * dashboard's Promos → Promotions config: shown automatically once you have
      * an active Checkout promotion, same as `allowCustom`/custom top-up. Pass
      * this only to override (e.g. `false` to force-hide it, or `true` to show it
      * before you've set one up). The code is passed through to
@@ -118,6 +122,16 @@ export interface CrediballProviderProps {
      * theme entirely from your own stylesheet.
      */
     applyRemoteTheme?: boolean;
+    /**
+     * Which color scheme to render the published theme's dark colors in (if
+     * the developer has configured a dark palette on the dashboard). Defaults
+     * to `"system"` — follows the OS/browser's `prefers-color-scheme` and
+     * updates live if it changes. Pass `"light"`/`"dark"` explicitly to follow
+     * your own app's in-app theme toggle instead (common when it can diverge
+     * from the OS setting). Read back via `useCrediball().colorScheme` for
+     * your own custom UI.
+     */
+    colorScheme?: "light" | "dark" | "system";
     /**
      * Automatic referral handling. On by default: any visit with `?ref=CODE` in
      * the URL is captured (stored locally + click counted), and once a `userId`
@@ -177,6 +191,8 @@ interface CrediballContextValue {
     currencySymbol: string;
     /** Developer-published default copy from the dashboard, used as a label fallback. null when unconfigured. */
     content: CrediballUiContent | null;
+    /** The resolved color scheme (`colorScheme` prop, or the live OS/browser preference when it's "system"). */
+    colorScheme: ColorScheme;
 }
 /**
  * Pattern B, automated. Wrap your app once:
@@ -198,7 +214,7 @@ interface CrediballContextValue {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch, allowCustom, customMin, customMax, allowPromoCode, promoCodeLabel, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme, captureReferrals, }: CrediballProviderProps): import("react").JSX.Element;
+export declare function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts, onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch, allowCustom, customMin, customMax, allowPromoCode, promoCodeLabel, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme, colorScheme, captureReferrals, }: CrediballProviderProps): import("react").JSX.Element;
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *

package/dist/CrediballProvider.js

@@ -4,7 +4,7 @@ import { createContext, useCallback, useContext, useEffect, useMemo, useRef, use
 import { PaywallModal } from "./PaywallModal";
 import { subscribeFetchWatcher } from "./fetchWatcher";
 import { subscribeInsufficientCredits } from "./creditEvent";
-import { getCrediballClient, notifyBalanceChanged, loadRemoteFont, themeToCssVars, captureReferral, completeStoredReferral, fetchReferral, } from "@crediball/core";
+import { getCrediballClient, notifyBalanceChanged, loadRemoteFont, themeToCssVars, getSystemColorScheme, watchSystemColorScheme, captureReferral, completeStoredReferral, fetchReferral, } from "@crediball/core";
 const CrediballConfigContext = createContext(null);
 /** Internal hook: the provider's publishableKey/userId/apiUrl. Throws outside a provider. */
 export function useCrediballConfig() {
@@ -63,13 +63,19 @@ function symbolForCurrency(iso) {
  * SSE/streaming routes (text/event-stream, ndjson) are also handled automatically —
  * the watcher scans each chunk for credit errors, so no manual wiring is needed.
  */
-export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch = true, allowCustom, customMin, customMax, allowPromoCode, promoCodeLabel, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme = true, captureReferrals = true, }) {
+export function CrediballProvider({ children, publishableKey, userId, apiUrl, pollIntervalMs, lowCreditThreshold, amounts = [5, 10, 20], onTopup, onSelectPackage, onSelectPlan, onCancelSubscription, onEnableAutoTopup, watchFetch = true, allowCustom, customMin, customMax, allowPromoCode, promoCodeLabel, currencySymbol: currencySymbolProp, title, description, accentColor, applyRemoteTheme = true, colorScheme = "system", captureReferrals = true, }) {
     const [open, setOpen] = useState(false);
     // Surfaced in the paywall itself (not just the console) when the built-in
     // checkout fails — e.g. an invalid/expired promo code — so a user isn't
     // left clicking a "dead" button with no visible feedback. Cleared at the
     // start of every attempt so it always reflects the latest one.
     const [checkoutError, setCheckoutError] = useState(null);
+    // Tracks the OS/browser's live prefers-color-scheme, only consulted when
+    // colorScheme is "system" (the default) — an explicit "light"/"dark" prop
+    // always wins, for apps whose own toggle can diverge from the OS setting.
+    const [systemColorScheme, setSystemColorScheme] = useState(getSystemColorScheme);
+    useEffect(() => watchSystemColorScheme(setSystemColorScheme), []);
+    const resolvedColorScheme = colorScheme === "system" ? systemColorScheme : colorScheme;
     // Referral auto-capture: pick up a `?ref=CODE` visit into localStorage (and
     // count the click) as soon as the provider mounts — the visitor usually has
     // no account yet at this point.
@@ -180,7 +186,20 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         packages: pkgs,
         currencySymbol,
         content: uiContent,
-    }), [showPaywall, hidePaywall, open, snapshot, costOf, topUp, refresh, pkgs, currencySymbol, uiContent]);
+        colorScheme: resolvedColorScheme,
+    }), [
+        showPaywall,
+        hidePaywall,
+        open,
+        snapshot,
+        costOf,
+        topUp,
+        refresh,
+        pkgs,
+        currencySymbol,
+        uiContent,
+        resolvedColorScheme,
+    ]);
     // The page to return to after Stripe checkout — the one the user is on now.
     function currentReturnPath() {
         if (typeof window === "undefined")
@@ -272,14 +291,20 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     const effectiveCustomMin = customMin ?? customCfg?.minEur;
     const effectiveCustomMax = customMax ?? customCfg?.maxEur ?? undefined;
     // Same auto-derivation for the promo-code field: a developer who set up a
-    // Checkout promotion in Growth gets the field for free, no code change.
+    // Checkout promotion in Promos gets the field for free, no code change.
     const effectiveAllowPromoCode = allowPromoCode ?? pkgs?.hasActiveCheckoutPromotion ?? false;
     // Published theme → --crediball-* CSS vars, applied on a display:contents
     // wrapper so it themes every descendant (and the paywall) without adding a
     // layout box. Host props/CSS are overridden by design (dashboard wins).
-    const themeVars = applyRemoteTheme ? themeToCssVars(uiTheme) : {};
+    const themeVars = applyRemoteTheme ? themeToCssVars(uiTheme, resolvedColorScheme) : {};
     const hasThemeVars = Object.keys(themeVars).length > 0;
-    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, autoTopup: pkgs?.autoTopup, onEnableAutoTopup: handleEnableAutoTopup, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, allowPromoCode: effectiveAllowPromoCode, promoCodeLabel: promoCodeLabel, customTopupRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, referralLink: referral?.link ?? undefined, referralReward: referral?.rewardCredits, referredReward: referral?.referredRewardCredits, referralLabel: uiContent?.referralLabel, checkoutError: checkoutError, accentColor: accentColor })] }));
+    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, autoTopup: pkgs?.autoTopup, onEnableAutoTopup: handleEnableAutoTopup, 
+                // Connected to live dashboard data: the legacy flat-amounts fallback
+                // only makes sense when there's no catalog to consult at all (see the
+                // `amounts` prop doc). Once a client exists, no packages configured
+                // means no top-up button — never a button whose checkout is
+                // guaranteed to fail.
+                amounts: client ? [] : amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, allowPromoCode: effectiveAllowPromoCode, promoCodeLabel: promoCodeLabel, customTopupRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, referralLink: referral?.link ?? undefined, referralReward: referral?.rewardCredits, referredReward: referral?.referredRewardCredits, referralLabel: uiContent?.referralLabel, checkoutError: checkoutError, accentColor: accentColor })] }));
     const configCtx = useMemo(() => ({ publishableKey, userId, apiUrl }), [publishableKey, userId, apiUrl]);
     return (_jsx(CrediballContext.Provider, { value: ctx, children: _jsx(CrediballConfigContext.Provider, { value: configCtx, children: hasThemeVars ? (_jsx("div", { style: { display: "contents", ...themeVars }, children: inner })) : (inner) }) }));
 }

package/dist/PaywallModal.js

@@ -217,7 +217,7 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                         ? "You've used all your credits for this period."
                         : 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 }), checkoutError ? (_jsx("p", { style: { marginTop: 12, marginBottom: 0, fontSize: 13, color: theme.accent }, children: checkoutError })) : null, activeSubscription && (_jsxs("div", { style: {
+                        : description }), activeSubscription && (_jsxs("div", { style: {
                         marginTop: 16,
                         padding: "12px 16px",
                         borderRadius: theme.radiusCard,
@@ -272,7 +272,7 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                             color: theme.inkMuted,
                             fontFamily: theme.font,
                             textDecoration: "underline",
-                        }, children: promoCodeLabel })) })), packages && packages.length > 0 && (_jsx("div", { style: { marginTop: 16 }, children: autoTopup?.enabled && autoTopup.status === "active" ? (_jsxs("p", { style: { margin: 0, fontSize: 12, color: theme.inkMuted }, children: ["Auto top-up is on \u2014 buying", " ", packages.find((p) => p.id === autoTopup.packageId)?.name ?? "your package", " whenever your balance drops below ", formatCredits(autoTopup.thresholdCredits), " credits."] })) : autoTopup?.enabled && (autoTopup.status === "needs_auth" || autoTopup.status === "failed") ? (_jsxs("div", { children: [_jsx("p", { style: { margin: 0, fontSize: 12, color: theme.accent }, children: autoTopup.status === "needs_auth"
+                        }, children: promoCodeLabel })) })), checkoutError ? (_jsx("p", { style: { marginTop: 12, marginBottom: 0, fontSize: 13, color: theme.accent }, children: checkoutError })) : null, packages && packages.length > 0 && (_jsx("div", { style: { marginTop: 16 }, children: autoTopup?.enabled && autoTopup.status === "active" ? (_jsxs("p", { style: { margin: 0, fontSize: 12, color: theme.inkMuted }, children: ["Auto top-up is on \u2014 buying", " ", packages.find((p) => p.id === autoTopup.packageId)?.name ?? "your package", " whenever your balance drops below ", formatCredits(autoTopup.thresholdCredits), " credits."] })) : autoTopup?.enabled && (autoTopup.status === "needs_auth" || autoTopup.status === "failed") ? (_jsxs("div", { children: [_jsx("p", { style: { margin: 0, fontSize: 12, color: theme.accent }, children: autoTopup.status === "needs_auth"
                                     ? "Auto top-up needs you to re-confirm your payment method."
                                     : "Auto top-up's last charge failed." }), _jsx("button", { onClick: () => onEnableAutoTopup?.({
                                     packageId: autoTopup.packageId,

package/dist/variables/CrediballLowCreditWarning.d.ts

@@ -13,6 +13,14 @@ export interface CrediballLowCreditWarningProps {
     threshold?: number;
     /** Message shown when low. Defaults to a generic nudge. */
     message?: string;
+    /**
+     * Preview/demo override — forces the warning to render regardless of the
+     * live balance, the same way `PaywallModal`'s balance prop and
+     * `ReferralCard`'s `demo` prop let the dashboard's UI-patterns preview show
+     * a component with no connected app. Never pass this in production; the
+     * component is meant to gate on the real live balance.
+     */
+    demo?: boolean;
     children?: ReactNode | ((props: CrediballLowCreditWarningRenderProps) => ReactNode);
 }
 /**
@@ -22,4 +30,4 @@ export interface CrediballLowCreditWarningProps {
  *
  *   <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;
+export declare function CrediballLowCreditWarning({ className, style, threshold, message, demo, children, }: CrediballLowCreditWarningProps): import("react").JSX.Element | null;

package/dist/variables/CrediballLowCreditWarning.js

@@ -10,11 +10,11 @@ import { InlineValue } from "../InlineValue";
  *
  *   <CrediballLowCreditWarning threshold={20} message="Not enough for one more image." />
  */
-export function CrediballLowCreditWarning({ className, style, threshold, message, children, }) {
+export function CrediballLowCreditWarning({ className, style, threshold, message, demo = false, children, }) {
     const { balance, isLow: contextIsLow, content } = useCrediball();
     // Prefer the host prop, then the dashboard-published default, then the provider's.
     const effectiveThreshold = threshold ?? content?.lowCreditThreshold;
-    const isLow = isBalanceLow(balance, effectiveThreshold, contextIsLow);
+    const isLow = demo || isBalanceLow(balance, effectiveThreshold, contextIsLow);
     if (!isLow)
         return null;
     if (typeof children === "function") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Drop-in React components for showing Crediball credits inside your AI app.",
   "license": "MIT",
   "author": "Filippo Rezzadore <filipporezzadore@gmail.com>",
@@ -51,7 +51,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@crediball/core": "^0.9.0"
+    "@crediball/core": "^0.10.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",