@teerai/teer-react/README.md

React components and hooks for Teer billing integration

# Teer React

React components and hooks for Teer billing integration.

Teer helps users track the spend of their LLM calls and provides a convenience layer to map tracked usage to usage-based billing via Stripe.

## Installation

```bash
npm install @teerai/teer-react
# or
yarn add @teerai/teer-react
# or
pnpm add @teerai/teer-react
```

## Quick Start

Wrap your application with the `TeerProvider` component:

```jsx
import { TeerProvider } from '@teerai/teer-react'

function App() {
  return (
    <TeerProvider publishableKey="your_publishable_key">
      <YourApp />
    </TeerProvider>
  )
}
```

## Usage

### Basic Usage

```jsx
import { useTeer } from '@teerai/teer-react'

function CheckoutButton({ priceId }) {
  const { checkout, isLoading } = useTeer()

  const handleCheckout = async () => {
    await checkout(priceId)
  }

  return (
    <button onClick={handleCheckout} disabled={isLoading}>
      {isLoading ? 'Loading...' : 'Checkout'}
    </button>
  )
}
```

### Accessing Billing Configuration

```jsx
import { useBillingConfig } from '@teerai/teer-react'

function PricingTable() {
  const { billingConfig, isLoading, error } = useBillingConfig()

  if (isLoading) {
    return <div>Loading...</div>
  }

  if (error) {
    return <div>Error: {error.message}</div>
  }

  if (!billingConfig) {
    return <div>No billing configuration available</div>
  }

  return (
    <div>
      {billingConfig.plans.map((plan) => (
        <div key={plan.id}>
          <h2>{plan.name}</h2>
          <p>{plan.description}</p>
          <ul>
            {plan.features?.map((feature) => (
              <li key={feature.id}>{feature.name}</li>
            ))}
          </ul>
        </div>
      ))}
    </div>
  )
}
```

### Managing Subscriptions

```jsx
import { useSubscriptions, useBillingPortal } from '@teerai/teer-react'

function SubscriptionManager() {
  const { subscriptions, isLoading } = useSubscriptions()
  const { billingPortal } = useBillingPortal()

  const handleManageBilling = async () => {
    await billingPortal()
  }

  if (isLoading) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h2>Your Subscriptions</h2>
      {subscriptions.length === 0 ? (
        <p>No active subscriptions</p>
      ) : (
        <ul>
          {subscriptions.map((subscription) => (
            <li key={subscription.id}>
              {subscription.planId} - {subscription.status}
            </li>
          ))}
        </ul>
      )}
      <button onClick={handleManageBilling}>Manage Billing</button>
    </div>
  )
}
```

### Reporting Usage

```jsx
import { useUsageReporting } from '@teerai/teer-react'

function UsageReporter() {
  const { reportUsage, isLoading } = useUsageReporting()
  const subscriptionItemId = 'your_subscription_item_id'

  const handleReportUsage = async () => {
    try {
      await reportUsage(subscriptionItemId, 1)
      alert('Usage reported successfully')
    } catch (error) {
      alert(`Error reporting usage: ${error.message}`)
    }
  }

  return (
    <button onClick={handleReportUsage} disabled={isLoading}>
      {isLoading ? 'Reporting...' : 'Report Usage'}
    </button>
  )
}
```

## API Reference

### TeerProvider

The `TeerProvider` component is used to wrap your application and provide the Teer context.

#### Props

| Prop           | Type      | Description                                                                |
| -------------- | --------- | -------------------------------------------------------------------------- |
| publishableKey | string    | Your Teer publishable API key                                              |
| customerId     | string    | (Optional) Customer ID to associate with the session                       |
| customerEmail  | string    | (Optional) Customer email to associate with the session                    |
| successUrl     | string    | (Optional) URL to redirect to after successful checkout                    |
| cancelUrl      | string    | (Optional) URL to redirect to after cancelled checkout                     |
| fetchOnMount   | boolean   | (Optional) Whether to fetch billing configuration on mount (default: true) |
| children       | ReactNode | Your application components                                                |

### Hooks

#### useTeer

The main hook to access the Teer context.

```jsx
const { isLoading, isReady, error, billingConfig, customer, subscriptions, refetch, checkout, billingPortal, reportUsage } = useTeer()
```

#### useBillingConfig

Hook to access billing configuration.

```jsx
const { billingConfig, isLoading, error } = useBillingConfig()
```

#### useCustomer

Hook to access customer data.

```jsx
const { customer, isLoading, error } = useCustomer()
```

#### useSubscriptions

Hook to access subscriptions.

```jsx
const { subscriptions, isLoading, error } = useSubscriptions()
```

#### useCheckout

Hook to access checkout functionality.

```jsx
const { checkout, isLoading, error } = useCheckout()
```

#### useBillingPortal

Hook to access billing portal functionality.

```jsx
const { billingPortal, isLoading, error } = useBillingPortal()
```

#### useUsageReporting

Hook to access usage reporting functionality.

```jsx
const { reportUsage, isLoading, error } = useUsageReporting()
```

## Utility Functions

### getActiveSubscriptions

Get active subscriptions (active or trialing).

```jsx
import { getActiveSubscriptions } from '@teerai/teer-react'

const activeSubscriptions = getActiveSubscriptions(subscriptions)
```

### getPlanById

Get a plan by ID.

```jsx
import { getPlanById } from '@teerai/teer-react'

const plan = getPlanById(billingConfig.plans, planId)
```

### getPriceById

Get a price by ID.

```jsx
import { getPriceById } from '@teerai/teer-react'

const price = getPriceById(billingConfig.plans, priceId)
```

### getActivePlanPrice

Get active price for a plan based on currency and interval.

```jsx
import { getActivePlanPrice } from '@teerai/teer-react'

const price = getActivePlanPrice(plan, { currency: 'usd', interval: 'month' })
```

## License

MIT

- check