@botparty/react

React hooks and headless components for BotParty auth + payments. Zero framework dependency — works with any React 18/19 app.

Next.js? Use @botparty/nextjs instead — it wraps this package with SSR support, middleware, and auto route handlers.

Install

npm install @botparty/react

Quick Start

Wrap your app with <BotPartyProvider>:

import { BotPartyProvider } from '@botparty/react';

function App() {
  return (
    <BotPartyProvider>
      <MyApp />
    </BotPartyProvider>
  );
}

Import default styles (optional — all components work headless):

import '@botparty/react/styles.css';

Hooks

useAuth()

const {
  isLoaded, isSignedIn, type, userId, namespaceId, keyId,
  email, name, picture, hasLinkedUser, signIn, signOut,
} = useAuth();

| Field | Type | Description | |-----------------|-----------------------------|------------------------------------| | isLoaded | boolean | Context finished loading | | isSignedIn | boolean | User is authenticated | | type | 'human' \| 'bot' \| null | Human OAuth or bot namespace JWT | | userId | string \| null | User ID | | namespaceId | string \| null | Namespace slug (bots) | | keyId | string \| null | Bot signing key ID | | email | string \| null | User email | | name | string \| null | Display name | | picture | string \| null | Avatar URL | | hasLinkedUser | boolean | Bot namespace linked to a human | | signIn() | (returnUrl?) => void | Redirect to login | | signOut() | () => Promise<void> | Sign out and redirect to / |

useUser()

const { user, isLoaded } = useUser();
// user: { userId, email?, name?, picture?, namespaceId? }

useWallet()

const { isLoaded, balance, currency, refetch } = useWallet();

useLedger()

const { isLoaded, entries, hasMore, loadMore, refetch } = useLedger({ autoLoad: true });

Components

Conditional Rendering

import { SignedIn, SignedOut, HasLinkedUser } from '@botparty/react';

<SignedIn>Welcome back!</SignedIn>
<SignedOut>Please sign in</SignedOut>
<HasLinkedUser>Human-linked account</HasLinkedUser>

Identity

import { UserButton, NamespaceBadge } from '@botparty/react';

<UserButton />                         // Avatar + dropdown (email, namespace, sign-out)
<UserButton afterSignOutUrl="/bye" />
<NamespaceBadge />                     // @brave-hawk-a3f2

Payments

import { WalletBalance, TransactionList, TopUpButton, SpendingControls } from '@botparty/react';

<WalletBalance />                      // "$12.50"
<WalletBalance format="full" />        // "$12.50 USD"
<TransactionList limit={10} />         // Scrollable ledger
<TopUpButton amounts={[5_000_000, 10_000_000, 25_000_000]} />  // Add credits → Stripe
<SpendingControls />                   // Spending policy editor

Styling

All components use data-botparty-* attributes. Import the default stylesheet or write your own:

[data-botparty-user-button-trigger] {
  /* your styles */
}

Override CSS custom properties for theming:

:root {
  --bp-accent: #8b5cf6;
  --bp-radius: 12px;
  --bp-bg: #1a1a1a;
  --bp-fg: #fafafa;
}

asChild Pattern

Components that support asChild replace their wrapper with your element (Radix-style):

<NamespaceBadge asChild>
  <code className="my-badge" />
</NamespaceBadge>

Provider Props

| Prop | Type | Default | Description | |----------------|--------------------|--------------------------|--------------------------------| | initialState | InitialAuthState | — | SSR-hydrated auth state | | basePath | string | "/api/botparty" | Base path for auth API routes |

Types

All types are exported:

import type {
  AuthState, AuthType, BotPartyUser, InitialAuthState,
  WalletState, LedgerEntry,
  SpendingPolicyType, SpendingPolicy,
} from '@botparty/react';