@crediball/react 0.16.0 → 0.18.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;
     /**
@@ -118,6 +118,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 +187,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 +210,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,8 +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.
@@ -104,7 +115,10 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
             cancelled = true;
         };
     }, [publishableKey, userId, apiUrl]);
-    const showPaywall = useCallback(() => setOpen(true), []);
+    const showPaywall = useCallback(() => {
+        setCheckoutError(null);
+        setOpen(true);
+    }, []);
     const hidePaywall = useCallback(() => setOpen(false), []);
     // Keep a ref so the fetch-watcher closure always calls the latest version.
     const showPaywallRef = useRef(showPaywall);
@@ -172,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")
@@ -209,11 +236,13 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
             return;
         }
         if (client) {
+            setCheckoutError(null);
             try {
                 await builtIn();
             }
             catch (err) {
                 console.error(`[crediball] ${errorLabel} failed:`, err);
+                setCheckoutError(err instanceof Error ? err.message : `Could not start ${errorLabel}. Please try again.`);
             }
             return;
         }
@@ -267,9 +296,9 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     // 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, 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, 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 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.d.ts

@@ -100,6 +100,13 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
      * the promo code the user entered, same as `onSelectPackage`'s. */
     onAdd?: (amount: number, code?: string) => void;
     onClose?: () => void;
+    /**
+     * An error from the last checkout attempt (e.g. "Invalid or expired promo
+     * code.") to show inline, so a failed purchase isn't silently invisible.
+     * Wired automatically by <CrediballProvider> when its built-in checkout
+     * fails; pass it yourself when using the modal standalone.
+     */
+    checkoutError?: string | null;
     /** When true, show a free-form amount field in addition to the preset buttons. */
     allowCustom?: boolean;
     /**
@@ -175,4 +182,4 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
  * continue. The host controls when it appears; shows a small "Powered by
  * Crediball" line by default (set `hideBranding` to remove it).
  */
-export declare function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts, amountPrefix, title, description, onAdd, onClose, allowCustom, allowPromoCode, promoCodeLabel, addButtonText, customMin, customMax, customTopupRate, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, referredReward, referralLabel, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;
+export declare function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts, amountPrefix, title, description, onAdd, onClose, checkoutError, allowCustom, allowPromoCode, promoCodeLabel, addButtonText, customMin, customMax, customTopupRate, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, referredReward, referralLabel, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;

package/dist/PaywallModal.js

@@ -24,7 +24,7 @@ function sectionLabelStyle(marginBottom) {
  * continue. The host controls when it appears; shows a small "Powered by
  * Crediball" line by default (set `hideBranding` to remove it).
  */
-export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, allowCustom = false, allowPromoCode = false, promoCodeLabel = "Have a promo code?", addButtonText = "Add", customMin = 1, customMax, customTopupRate, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, referralLink, referralReward, referredReward, referralLabel, accentColor, style, }) {
+export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlans, onSelectPlan, activeSubscription, onCancelSubscription, autoTopup, onEnableAutoTopup, amounts = [5, 10], amountPrefix = "Add €", title = "You need more credits to continue.", description = "Top up to keep using this feature.", onAdd, onClose, checkoutError, allowCustom = false, allowPromoCode = false, promoCodeLabel = "Have a promo code?", addButtonText = "Add", customMin = 1, customMax, customTopupRate, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, referralLink, referralReward, referredReward, referralLabel, 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
@@ -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.16.0",
+  "version": "0.18.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",