@crediball/react 0.11.0 → 0.14.0

package/dist/CrediballProvider.d.ts

@@ -32,14 +32,15 @@ export interface CrediballProviderProps {
      * 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>;
+    onTopup?: (amount: number, code?: string) => 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).
+     * packageId })` server-side). The second argument is the promo code the user
+     * entered, if any (see `allowPromoCode`) — pass it through as `code`.
      */
-    onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    onSelectPackage?: (pkg: PackageOption, code?: string) => void | Promise<void>;
     /**
      * Optional override for subscription plans. If omitted, the paywall starts a
      * recurring Stripe Checkout itself (connect payouts in the dashboard) and Stripe
@@ -85,6 +86,15 @@ export interface CrediballProviderProps {
     customMin?: number;
     /** Override the custom-amount maximum (defaults to the dashboard's configured maximum). */
     customMax?: number;
+    /**
+     * Show a "Have a promo code?" field in the paywall (Growth → Promotions'
+     * Checkout trigger). Off by default. The code is passed through to
+     * `onSelectPackage`/`onTopup`, or included automatically in the built-in
+     * checkout when neither is provided.
+     */
+    allowPromoCode?: boolean;
+    /** Label above the promo code toggle (default "Have a promo code?"). */
+    promoCodeLabel?: string;
     /**
      * Currency symbol shown in the paywall. Auto-derived (via Intl) from the ISO
      * currency you configured on the dashboard's Packages page once packages load,
@@ -153,8 +163,9 @@ interface CrediballContextValue {
     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>;
+    /** Trigger a top-up (delegates to the `onTopup` prop) and refresh balance/usage on completion.
+     * `code` is a checkout promo code, if any. */
+    topUp: (amount: number, code?: string) => Promise<void>;
     /** Refetch balance, usage, costs, and packages immediately. No-op without publishableKey/userId. */
     refresh: () => Promise<void>;
     /** The live packages payload (top-up options, plans, custom-topup, currency, ui). null until loaded. */
@@ -184,7 +195,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, 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, captureReferrals, }: CrediballProviderProps): import("react").JSX.Element;
 /**
  * Access the paywall + live data from anywhere inside <CrediballProvider>.
  *

package/dist/CrediballProvider.js

@@ -63,7 +63,7 @@ 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, 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, captureReferrals = true, }) {
     const [open, setOpen] = useState(false);
     // Referral auto-capture: pick up a `?ref=CODE` visit into localStorage (and
     // count the click) as soon as the provider mounts — the visitor usually has
@@ -150,8 +150,8 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     const refresh = useCallback(async () => {
         await client?.refresh();
     }, [client]);
-    const topUp = useCallback(async (amount) => {
-        await onTopup?.(amount);
+    const topUp = useCallback(async (amount, code) => {
+        await onTopup?.(amount, code);
         notifyBalanceChanged();
         await client?.refresh();
     }, [onTopup, client]);
@@ -194,10 +194,12 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     // handler always wins (and refreshes balance/usage on completion); otherwise fall
     // back to the built-in Stripe checkout when a data client is available, leaving the
     // modal open on failure so the error stays visible; otherwise just close the modal.
-    async function runPaywallAction(hostHandler, arg, builtIn, errorLabel) {
+    // `code` (a promo code from the paywall) is only meaningful for topup-shaped
+    // actions (handleAdd/handleSelectPackage) — other callers simply omit it.
+    async function runPaywallAction(hostHandler, arg, builtIn, errorLabel, code) {
         if (hostHandler) {
             try {
-                await hostHandler(arg);
+                await hostHandler(arg, code);
                 notifyBalanceChanged();
                 await client?.refresh();
             }
@@ -218,11 +220,11 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
         // Data-less mode with no handler: nothing to charge against.
         setOpen(false);
     }
-    function handleAdd(amount) {
-        return runPaywallAction(onTopup, amount, () => startBuiltInCheckout({ eurAmount: amount }), "checkout");
+    function handleAdd(amount, code) {
+        return runPaywallAction(onTopup, amount, () => startBuiltInCheckout({ eurAmount: amount, code }), "checkout", code);
     }
-    function handleSelectPackage(pkg) {
-        return runPaywallAction(onSelectPackage, pkg, () => startBuiltInCheckout({ packageId: pkg.id }), "checkout");
+    function handleSelectPackage(pkg, code) {
+        return runPaywallAction(onSelectPackage, pkg, () => startBuiltInCheckout({ packageId: pkg.id, code }), "checkout", code);
     }
     function handleSelectPlan(plan) {
         return runPaywallAction(onSelectPlan, plan, async () => {
@@ -264,7 +266,7 @@ export function CrediballProvider({ children, publishableKey, userId, apiUrl, po
     // layout box. Host props/CSS are overridden by design (dashboard wins).
     const themeVars = applyRemoteTheme ? themeToCssVars(uiTheme) : {};
     const hasThemeVars = Object.keys(themeVars).length > 0;
-    const inner = (_jsxs(_Fragment, { children: [children, _jsx(PaywallModal, { open: open, packages: pkgs?.packages, onSelectPackage: handleSelectPackage, subscriptionPlans: pkgs?.subscriptionPlans, onSelectPlan: handleSelectPlan, activeSubscription: pkgs?.activeSubscription, onCancelSubscription: onCancelSubscription ? handleCancelSubscription : undefined, autoTopup: pkgs?.autoTopup, onEnableAutoTopup: handleEnableAutoTopup, amounts: amounts, amountPrefix: `Add ${currencySymbol}`, onAdd: handleAdd, onClose: hidePaywall, allowCustom: effectiveAllowCustom, customMin: effectiveCustomMin, customMax: effectiveCustomMax, currencySymbol: currencySymbol, balance: snapshot.balance ?? undefined, balanceRate: pkgs?.customTopup.enabled ? pkgs.customTopup.rate : undefined, currency: pkgs?.currency, usage: snapshot.usage?.usedCredits ?? undefined, title: title ?? uiContent?.paywallTitle, description: description ?? uiContent?.paywallDescription, addButtonText: uiContent?.paywallButtonText, referralLink: referral?.link ?? undefined, referralReward: referral?.rewardCredits, 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: allowPromoCode, 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, referralLabel: uiContent?.referralLabel, 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

@@ -13,7 +13,7 @@ export interface SubscriptionPlanOption {
     name: string;
     price: number;
     credits: number;
-    period: "monthly" | "yearly";
+    period: "weekly" | "monthly" | "yearly";
 }
 /** The end user's current active subscription (returned by listPackages() with userId). */
 export interface ActiveSubscriptionInfo {
@@ -40,9 +40,11 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     /**
      * Called when the user selects a package. Use this with `packages` — call
      * `meter.topup({ userId, packageId: pkg.id })` in your backend. No `amount`
-     * calculation needed; Crediball derives it from the package.
+     * calculation needed; Crediball derives it from the package. The second
+     * argument is the promo code the user entered (if the "Have a promo code?"
+     * field is shown and filled in) — pass it through as `code` to `topup()`.
      */
-    onSelectPackage?: (pkg: PackageOption) => void;
+    onSelectPackage?: (pkg: PackageOption, code?: string) => void;
     /**
      * Subscription plans from `meter.listPackages()`. When provided (and the user
      * has no active subscription), the modal shows a "Subscribe" section above
@@ -67,17 +69,19 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     onCancelSubscription?: (subscriptionId: string) => void | Promise<void>;
     /**
      * The end user's current auto-topup rule (from `meter.listPackages({ userId })`
-     * or `meter.getAutoTopupStatus(userId)`). When absent/null and `onEnableAutoTopup`
-     * is provided, an opt-in row is shown below the packages so the user can turn
-     * on "keep me topped up automatically".
+     * or `meter.getAutoTopupStatus(userId)`). When absent/null, an opt-in row is
+     * shown below the packages so the user can turn on "keep me topped up
+     * automatically".
      */
     autoTopup?: AutoTopupInfo | null;
     /**
-     * Called when the user opts into auto top-up (only shown when `packages` is
-     * non-empty). Call `meter.setupAutoTopupCheckout({ userId, packageId,
-     * thresholdCredits, successUrl, cancelUrl })` in your backend — it saves a
-     * payment method, no money changes hands in this step — then redirect the
-     * browser to the returned `url`.
+     * Called when the user opts into auto top-up. Shown whenever `packages` is
+     * non-empty — same as `onSelectPackage`, this is optional to invoke (a no-op
+     * if you don't wire it, e.g. in a preview with no backend). Call
+     * `meter.setupAutoTopupCheckout({ userId, packageId, thresholdCredits,
+     * successUrl, cancelUrl })` in your backend — it saves a payment method, no
+     * money changes hands in this step — then redirect the browser to the
+     * returned `url`.
      */
     onEnableAutoTopup?: (input: {
         packageId: string;
@@ -92,17 +96,36 @@ export interface PaywallModalProps extends CrediballThemeOverrides {
     amountPrefix?: string;
     title?: string;
     description?: string;
-    /** Called when the user clicks a legacy amount button. */
-    onAdd?: (amount: number) => void;
+    /** Called when the user clicks a legacy amount button. The second argument is
+     * the promo code the user entered, same as `onSelectPackage`'s. */
+    onAdd?: (amount: number, code?: string) => void;
     onClose?: () => void;
     /** When true, show a free-form amount field in addition to the preset buttons. */
     allowCustom?: boolean;
+    /**
+     * When true, show a "Have a promo code?" field above the top-up buttons. The
+     * code is passed as the second argument to `onSelectPackage`/`onAdd`/the
+     * built-in checkout — pass it through as `code` to `topup()` or
+     * `createCheckout()`. Not validated client-side; an invalid code is rejected
+     * when the top-up is actually processed.
+     */
+    allowPromoCode?: boolean;
+    /** Label above the promo code toggle (default "Have a promo code?"). */
+    promoCodeLabel?: string;
     /** Button label for the free-form amount field (default "Add"). */
     addButtonText?: string;
     /** Minimum custom amount (default 1). */
     customMin?: number;
     /** Optional maximum custom amount. */
     customMax?: number;
+    /**
+     * Credits granted per 1 currency unit for the custom-amount field (your
+     * dashboard's custom top-up rate). When provided, a live "≈ N credits"
+     * line appears under the field as the user types, computed the same way
+     * the actual charge is (Math.round(amount * rate)) — so it never promises
+     * a different number than what gets granted.
+     */
+    customTopupRate?: number;
     /** Currency symbol shown beside the custom field (default "€"). */
     currencySymbol?: string;
     /**
@@ -143,4 +166,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, addButtonText, customMin, customMax, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, 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, allowCustom, allowPromoCode, promoCodeLabel, addButtonText, customMin, customMax, customTopupRate, currencySymbol, balance, balanceRate, currency, usage, usageLabel, hideBranding, referralLink, referralReward, referralLabel, accentColor, style, }: PaywallModalProps): import("react").JSX.Element | null;

package/dist/PaywallModal.js

@@ -3,6 +3,12 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from "react";
 import { theme, accentStyle } from "./theme";
 import { formatCredits, formatMoney } from "./format";
+/** Shorthand suffix for a billing period, used in plan price labels (e.g. "€9.99/mo"). */
+const PERIOD_SUFFIX = {
+    weekly: "wk",
+    monthly: "mo",
+    yearly: "yr",
+};
 /** Shared uppercase eyebrow-label style used above the subscribe/buy-credits sections. */
 function sectionLabelStyle(marginBottom) {
     return {
@@ -19,7 +25,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, addButtonText = "Add", customMin = 1, customMax, currencySymbol = "€", balance, balanceRate, currency = "EUR", usage, usageLabel = "Usage", hideBranding = false, referralLink, referralReward, referralLabel = "Refer a friend · earn {credits} credits", 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, 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, referralLabel = "Refer a friend · earn {credits} credits", 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
@@ -35,6 +41,8 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
     const [autoTopupOpen, setAutoTopupOpen] = useState(false);
     const [autoTopupPackageId, setAutoTopupPackageId] = useState("");
     const [autoTopupThreshold, setAutoTopupThreshold] = useState("");
+    const [promoCodeOpen, setPromoCodeOpen] = useState(false);
+    const [promoCode, setPromoCode] = useState("");
     useEffect(() => {
         const el = overlayRef.current;
         if (!el || typeof ResizeObserver === "undefined")
@@ -76,6 +84,12 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         setReferralCopied(true);
         setTimeout(() => setReferralCopied(false), 2000);
     }
+    // Undefined (not "") when empty, so onAdd/onSelectPackage receive `code`
+    // exactly as the SDK expects (an absent field, not an empty string).
+    function enteredCode() {
+        const trimmed = promoCode.trim();
+        return trimmed || undefined;
+    }
     function submitCustom() {
         const amt = Number(customValue);
         if (!Number.isFinite(amt) || amt <= 0) {
@@ -91,7 +105,7 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
             return;
         }
         setCustomError(null);
-        onAdd?.(amt);
+        onAdd?.(amt, enteredCode());
     }
     function submitAutoTopup() {
         const threshold = Number(autoTopupThreshold);
@@ -114,6 +128,12 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
         borderRadius: theme.radiusPill,
     };
     const resolvedReferralLabel = referralLabel.replace("{credits}", formatCredits(referralReward ?? 0));
+    // Same rounding the actual charge uses (see /api/public/topup/checkout),
+    // so this preview never promises a different number than what's granted.
+    const customAmountParsed = Number(customValue);
+    const customCreditsPreview = customTopupRate && customTopupRate > 0 && Number.isFinite(customAmountParsed) && customAmountParsed > 0
+        ? Math.round(customAmountParsed * customTopupRate)
+        : null;
     return (_jsx("div", { ref: overlayRef, role: "dialog", "aria-modal": "true", style: {
             position: "fixed",
             inset: 0,
@@ -174,9 +194,32 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                     display: "flex",
                                     justifyContent: "space-between",
                                     alignItems: "center",
-                                }, 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: {
+                                }, children: [_jsx("span", { children: plan.name }), _jsxs("span", { style: { opacity: 0.85, fontSize: 14 }, children: [formatMoney(plan.price, currency), "/", PERIOD_SUFFIX[plan.period], " \u00B7 ", formatCredits(plan.credits), " cr"] })] }, plan.id))) })] })), allowPromoCode && !activeSubscription && (_jsx("div", { style: { marginTop: 16 }, children: promoCodeOpen ? (_jsxs("div", { children: [_jsx("div", { style: { ...sectionLabelStyle(6) }, children: promoCodeLabel }), _jsx("input", { value: promoCode, onChange: (e) => setPromoCode(e.target.value.toUpperCase()), placeholder: "PROMOCODE", style: {
+                                    width: "100%",
+                                    boxSizing: "border-box",
+                                    appearance: "none",
+                                    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: () => setPromoCodeOpen(true), style: {
+                            appearance: "none",
+                            border: "none",
+                            background: "transparent",
+                            cursor: "pointer",
+                            padding: 0,
+                            fontSize: 12,
+                            color: theme.inkMuted,
+                            fontFamily: theme.font,
+                            textDecoration: "underline",
+                        }, children: promoCodeLabel })) })), _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, enteredCode()), 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, enteredCode()), 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",
@@ -189,9 +232,9 @@ export function PaywallModal({ open, packages, onSelectPackage, subscriptionPlan
                                         color: theme.ink,
                                         background: theme.canvas,
                                         outline: "none",
-                                    } }), _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, onEnableAutoTopup && 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"
+                                    } }), _jsx("button", { onClick: submitCustom, style: { ...buttonStyle, flex: "none" }, children: addButtonText })] }), customCreditsPreview != null ? (_jsxs("p", { style: { margin: "6px 0 0", fontSize: 12, color: theme.inkMuted }, children: ["\u2248 ", formatCredits(customCreditsPreview), " credits"] })) : null, customError ? (_jsx("p", { style: { margin: "8px 0 0", fontSize: 13, color: theme.accent }, children: customError })) : null] })) : 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({
+                                    : "Auto top-up's last charge failed." }), _jsx("button", { onClick: () => onEnableAutoTopup?.({
                                     packageId: autoTopup.packageId,
                                     thresholdCredits: autoTopup.thresholdCredits,
                                 }), style: {

package/dist/usePaywall.d.ts

@@ -7,10 +7,12 @@ import { type PaywallModalProps, type PackageOption, type SubscriptionPlanOption
  * accept async handlers. Add watchFetch to auto-open on detected credit errors.
  */
 export type UsePaywallProps = Omit<PaywallModalProps, "open" | "onClose" | "onAdd" | "style"> & {
-    /** Called when the user picks a legacy preset/custom top-up amount. */
-    onTopup?: (amount: number) => void | Promise<void>;
-    /** Called when the user picks a one-time package (async override). */
-    onSelectPackage?: (pkg: PackageOption) => void | Promise<void>;
+    /** Called when the user picks a legacy preset/custom top-up amount. The
+     * second argument is the promo code entered, if any (see `allowPromoCode`). */
+    onTopup?: (amount: number, code?: string) => void | Promise<void>;
+    /** Called when the user picks a one-time package (async override). The second
+     * argument is the promo code entered, if any (see `allowPromoCode`). */
+    onSelectPackage?: (pkg: PackageOption, code?: string) => void | Promise<void>;
     /** Called when the user picks a subscription plan (async override). */
     onSelectPlan?: (plan: SubscriptionPlanOption) => void | Promise<void>;
     /**

package/dist/usePaywall.js

@@ -36,13 +36,13 @@ export function usePaywall({ onTopup, onSelectPackage, onSelectPlan, watchFetch
             return;
         return subscribeFetchWatcher(() => triggerRef.current());
     }, [watchFetch]);
-    const handleTopup = useCallback(async (amount) => {
+    const handleTopup = useCallback(async (amount, code) => {
         setIsOpen(false);
-        await onTopup?.(amount);
+        await onTopup?.(amount, code);
     }, [onTopup]);
-    const handleSelectPackage = useCallback(async (pkg) => {
+    const handleSelectPackage = useCallback(async (pkg, code) => {
         setIsOpen(false);
-        await onSelectPackage?.(pkg);
+        await onSelectPackage?.(pkg, code);
     }, [onSelectPackage]);
     const handleSelectPlan = useCallback(async (plan) => {
         setIsOpen(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediball/react",
-  "version": "0.11.0",
+  "version": "0.14.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.6.0"
+    "@crediball/core": "^0.8.0"
   },
   "devDependencies": {
     "@types/react": "^18.3.11",