@botparty/react

@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';