# @crediball/react

Drop-in, **unbranded** React components for showing
[Crediball](https://github.com/filipporezzadore/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.

```bash
npm install @crediball/react
```

> `react >= 18` is a peer dependency. Pair this with
> [`@crediball/sdk`](https://www.npmjs.com/package/@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.

```tsx
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:

```tsx
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. |

```tsx
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`](https://www.npmjs.com/package/@crediball/sdk).

MIT © Crediball