@crediball/react

Drop-in, unbranded React components for showing Crediball credits inside your AI app — a credit balance, a top-bar chip, and an automatic paywall. Self-contained (no CSS framework), and your end users never see Crediball branding or log into Crediball.

npm install @crediball/react

react >= 18 is a peer dependency. Pair this with @crediball/sdk, which does the server-side metering.

Automatic paywall (recommended)

Wrap your app once. When any request returns 402 with { code: "insufficient_credits" } (your server forwarding Crediball's error), the paywall opens automatically — no per-call wiring.

import { CrediballProvider } from "@crediball/react";

<CrediballProvider
  amounts={[5, 10, 20]}           // top-up options (match your dashboard packages)
  currencySymbol="€"
  onTopup={(amount) => checkout(amount)}  // wire to your checkout / top-up route
>
  <App />
</CrediballProvider>;

Open or close it yourself from anywhere inside the provider:

import { useCrediball } from "@crediball/react";

const { showPaywall, hidePaywall, open } = useCrediball();

Set watchFetch={false} on the provider to disable auto-detection and drive the paywall only via showPaywall().

Components

| Export | Use | |---|---| | CrediballProvider | App-wide paywall + auto-detect of 402 insufficient_credits. | | useCrediball() | { showPaywall, hidePaywall, open } from inside the provider. | | CreditsBadge | A balance block for a settings page (big number + optional ≈ money value). | | CreditIndicator | A quiet balance chip for the top bar; clickable to open top-up. | | PaywallModal | The standalone paywall dialog (used by the provider; usable directly). | | tokens | The default theme tokens (colors, fonts) if you want to match the look. |

import { CreditsBadge, CreditIndicator, PaywallModal } from "@crediball/react";

// Settings page
<CreditsBadge credits={840} rate={100} currency="EUR" onAddCredits={openTopUp} />

// Top bar
<CreditIndicator balanceLabel="6.20" onClick={openTopUp} />

// Manual paywall
<PaywallModal open={broke} amounts={[5, 10]} onAdd={topUp} onClose={close} />

All components accept theme overrides (e.g. accentColor) and inline style, and render without any CSS framework.

Principles

• Unbranded. Crediball never appears to your end users.
• Client-side UI only. Metering and your cb_live_ key stay on the server — see @crediball/sdk.

MIT © Crediball