npm package: @quotadev/react
Description: React components for displaying AI usage and billing information
Latest version: 0.1.1

# `@quotadev/react`

Drop-in React components for displaying AI usage and billing to your customers.

## Install

```bash
npm install @quotadev/react @quotadev/sdk
```

## Quick Start

Wrap your app with `QuotaProvider`, then use the components anywhere:

```tsx
import { QuotaProvider, UsageMeter, UsageHistory } from "@quotadev/react";

function App() {
  return (
    <QuotaProvider apiKey={process.env.QUOTA_API_KEY}>
      <Dashboard />
    </QuotaProvider>
  );
}

function Dashboard() {
  return (
    <>
      <UsageMeter
        customerId="cus_abc123"
        feature="ai-summarization"
        showUpgradePrompt
        upgradeUrl="/pricing"
      />
      <UsageHistory
        customerId="cus_abc123"
        period="current_month"
        theme="dark"
      />
    </>
  );
}
```

## Components

### `<QuotaProvider>`

Context provider that configures the SDK for all child components.

| Prop      | Type     | Default                    | Description        |
| --------- | -------- | -------------------------- | ------------------ |
| `apiKey`  | `string` | —                          | Your Quota API key |
| `baseUrl` | `string` | `https://api.usequota.dev` | API base URL       |

### `<UsageMeter>`

Displays current usage as a progress bar with optional upgrade prompt.

| Prop                | Type                   | Default | Description                      |
| ------------------- | ---------------------- | ------- | -------------------------------- |
| `customerId`        | `string`               | —       | Customer to show usage for       |
| `feature`           | `string`               | —       | Filter by feature                |
| `showUpgradePrompt` | `boolean`              | `false` | Show prompt when near/over limit |
| `upgradeUrl`        | `string`               | —       | URL for the upgrade CTA          |
| `label`             | `string`               | —       | Custom label text                |
| `size`              | `"sm" \| "md" \| "lg"` | `"md"`  | Size variant                     |
| `className`         | `string`               | —       | Custom CSS class                 |

### `<UsageHistory>`

Displays usage history as a chart or table.

| Prop         | Type                                                 | Default           | Description                  |
| ------------ | ---------------------------------------------------- | ----------------- | ---------------------------- |
| `customerId` | `string`                                             | —                 | Customer to show history for |
| `period`     | `"current_month" \| "last_30_days" \| "last_7_days"` | `"current_month"` | Time period                  |
| `feature`    | `string`                                             | —                 | Filter by feature            |
| `theme`      | `"light" \| "dark" \| "auto"`                        | `"auto"`          | Color theme                  |
| `view`       | `"chart" \| "table"`                                 | `"chart"`         | Display mode                 |
| `className`  | `string`                                             | —                 | Custom CSS class             |

## Hooks

### `useQuota()`

Returns a configured `Quota` SDK instance from context.

```tsx
import { useQuota } from "@quotadev/react";

function MyComponent() {
  const quota = useQuota();

  const handleAction = async () => {
    const check = await quota.check({
      customerId: "cus_abc123",
      feature: "ai-summarization",
      estimatedTokens: 500,
    });

    if (!check.allowed) {
      alert("Usage limit reached");
    }
  };
}
```

### `useUsage(options)`

Fetches current usage data for a customer.

```tsx
import { useUsage } from "@quotadev/react";

function UsageDisplay() {
  const { data, isLoading, error } = useUsage({
    customerId: "cus_abc123",
    feature: "ai-summarization",
    pollInterval: 30000, // refresh every 30s
  });

  if (isLoading) return <span>Loading...</span>;
  if (!data) return null;

  return (
    <div>
      <p>{data.tokens.toLocaleString()} tokens used</p>
      <p>{data.percentUsed}% of limit</p>
    </div>
  );
}
```

### `useHistory()`

Fetches usage history records for a customer.

## Peer Dependencies

- `react` >= 18
- `react-dom` >= 18

## License

MIT