@authon/react 0.3.0 → 0.3.2

package/README.md

@@ -2,786 +2,217 @@
 
 # @authon/react
 
-React components and hooks for [Authon](https://authon.dev) authentication.
+> Drop-in React authentication with hooks and components — Auth0 alternative, open-source auth
 
-## Install
-
-```bash
-npm install @authon/react @authon/js
-# or
-pnpm add @authon/react @authon/js
-```
-
-Requires `react >= 18.0.0`.
-
-## Setup
-
-Wrap your app with `<AuthonProvider>` at the root level:
-
-```tsx
-// src/main.tsx
-import { AuthonProvider } from '@authon/react';
-
-function App() {
-  return (
-    <AuthonProvider publishableKey="pk_live_...">
-      <Router />
-    </AuthonProvider>
-  );
-}
-```
-
-Get your publishable key from the [Authon Dashboard](https://authon.dev/dashboard).
-
----
+[![npm version](https://img.shields.io/npm/v/@authon/react?color=6d28d9)](https://www.npmjs.com/package/@authon/react)
+[![License](https://img.shields.io/badge/license-MIT-blue)](../../LICENSE)
 
-## Components
+## Prerequisites
 
-### `<AuthonProvider>`
+Before installing the SDK, create an Authon project and get your API keys:
 
-Initializes the Authon client and provides auth context to your entire component tree. Must wrap all other Authon components and hooks.
-
-```tsx
-import { AuthonProvider } from '@authon/react';
-
-<AuthonProvider
-  publishableKey="pk_live_..."
-  config={{
-    apiUrl: 'https://api.authon.dev',
-    theme: 'auto',
-    locale: 'en',
-    appearance: {
-      primaryColorStart: '#7c3aed',
-      primaryColorEnd: '#4f46e5',
-      borderRadius: 12,
-    },
-  }}
->
-  {children}
-</AuthonProvider>
-```
+1. **Create a project** at [Authon Dashboard](https://authon.dev/dashboard/overview)
+   - Click "Create Project" and enter your app name
+   - Select the authentication methods you want (Email/Password, OAuth providers, etc.)
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `publishableKey` | `string` | Your project's publishable key |
-| `config` | `AuthonConfig` (optional) | Additional client configuration |
+2. **Get your API keys** from Project Settings → API Keys
+   - **Publishable Key** (`pk_live_...`) — use in your frontend code
+   - **Test Key** (`pk_test_...`) — for development, enables Dev Teleport
 
----
+3. **Configure OAuth providers** (optional) in Project Settings → OAuth
+   - Add Google, Apple, GitHub, etc. with their respective Client ID and Secret
+   - Set the redirect URL to `https://api.authon.dev/v1/auth/oauth/redirect`
 
-### `<SignIn>`
+> **Test vs Live keys:** Use `pk_test_...` during development. Switch to `pk_live_...` before deploying to production. Test keys use a sandbox environment with no rate limits.
 
-Opens the sign-in modal or renders an embedded sign-in form.
-
-```tsx
-import { SignIn } from '@authon/react';
-
-// Popup mode (default) — opens the modal immediately on mount
-<SignIn mode="popup" />
+## Install
 
-// Embedded mode — renders a container div for the hosted form
-<SignIn mode="embedded" />
+```bash
+npm install @authon/react
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` | `'popup' \| 'embedded'` | `'popup'` | Display mode |
-| `redirectUrl` | `string` (optional) | — | URL to redirect after sign-in |
-
----
-
-### `<SignUp>`
-
-Opens the sign-up modal or renders an embedded sign-up form.
+## Quick Start
 
 ```tsx
-import { SignUp } from '@authon/react';
-
-// Popup mode (default)
-<SignUp mode="popup" />
-
-// Embedded mode
-<SignUp mode="embedded" />
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `mode` | `'popup' \| 'embedded'` | `'popup'` | Display mode |
-
----
+// src/main.tsx — complete working file
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AuthonProvider, useAuthon, useUser, SignedIn, SignedOut, UserButton } from '@authon/react';
 
-### `<UserButton>`
-
-Displays a user avatar button. When clicked, opens a dropdown with the user's name, email, and a sign-out option. When the user is signed out, renders a "Sign In" button instead.
-
-```tsx
-import { UserButton } from '@authon/react';
+function App() {
+  const { openSignIn, signOut } = useAuthon();
+  const { user } = useUser();
 
-function Navbar() {
   return (
-    <nav>
-      <UserButton />
-    </nav>
+    <div>
+      <SignedOut>
+        <button onClick={() => openSignIn()}>Sign In</button>
+      </SignedOut>
+      <SignedIn>
+        <p>Welcome, {user?.email}</p>
+        <UserButton />
+        <button onClick={() => signOut()}>Sign Out</button>
+      </SignedIn>
+    </div>
   );
 }
-```
-
-No props required.
-
----
-
-### `<SignedIn>`
-
-Renders `children` only when a user is signed in. Renders nothing while auth is loading.
-
-```tsx
-import { SignedIn } from '@authon/react';
-
-<SignedIn>
-  <Dashboard />
-</SignedIn>
-```
-
----
-
-### `<SignedOut>`
-
-Renders `children` only when no user is signed in. Renders nothing while auth is loading.
-
-```tsx
-import { SignedOut } from '@authon/react';
 
-<SignedOut>
-  <a href="/sign-in">Sign In</a>
-</SignedOut>
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <AuthonProvider
+    publishableKey="pk_live_YOUR_PUBLISHABLE_KEY"
+  >
+    <App />
+  </AuthonProvider>
+);
 ```
 
----
-
-### `<Protect>`
+## Common Tasks
 
-Guards content based on authentication status and an optional custom condition. Useful for role-based access control.
+### Add Google OAuth Login
 
 ```tsx
-import { Protect } from '@authon/react';
-
-// Require sign-in only
-<Protect fallback={<p>Please sign in to continue.</p>}>
-  <PrivatePage />
-</Protect>
-
-// Require a specific role
-<Protect
-  fallback={<p>Admin access required.</p>}
-  condition={(user) => user.publicMetadata?.role === 'admin'}
->
-  <AdminPanel />
-</Protect>
-```
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `children` | `ReactNode` | Content to render when access is granted |
-| `fallback` | `ReactNode` (optional) | Content to render when access is denied |
-| `condition` | `(user: AuthonUser) => boolean` (optional) | Additional check beyond sign-in status |
-
----
-
-### `<SocialButton>`
-
-A single OAuth provider button with built-in styles, icons, and loading state.
-
-```tsx
-import { SocialButton } from '@authon/react';
+import { useAuthon } from '@authon/react';
 
-function SocialLogin() {
+function GoogleLoginButton() {
   const { client } = useAuthon();
-
   return (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: 10 }}>
-      <SocialButton
-        provider="google"
-        onClick={async (provider) => {
-          await client!.signInWithOAuth(provider);
-        }}
-      />
-      <SocialButton
-        provider="github"
-        onClick={async (provider) => {
-          await client!.signInWithOAuth(provider);
-        }}
-        compact
-        size={48}
-      />
-    </div>
+    <button onClick={() => client?.signInWithOAuth('google')}>
+      Sign in with Google
+    </button>
   );
 }
 ```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `provider` | `OAuthProviderType` | — | OAuth provider identifier |
-| `onClick` | `(provider: OAuthProviderType) => void \| Promise<void>` | — | Click handler |
-| `loading` | `boolean` | `false` | Show spinner |
-| `disabled` | `boolean` | `false` | Disable button |
-| `label` | `string` (optional) | `"Continue with {Provider}"` | Override button label |
-| `compact` | `boolean` | `false` | Icon-only square button |
-| `className` | `string` (optional) | — | Custom class |
-| `style` | `CSSProperties` (optional) | — | Custom inline style |
-| `iconSize` | `number` (optional) | `20` (`24` in compact) | Icon size in px |
-| `borderRadius` | `number` | `10` | Border radius in px |
-| `height` | `number` | `48` | Button height in px (full mode) |
-| `size` | `number` | `48` | Button size in px (compact mode) |
-
-Supported `OAuthProviderType` values: `'google' | 'apple' | 'kakao' | 'naver' | 'facebook' | 'github' | 'discord' | 'x' | 'line' | 'microsoft'`
-
----
-
-### `<SocialButtons>`
-
-Automatically fetches your project's enabled OAuth providers and renders a list of `<SocialButton>` components. Handles OAuth sign-in flow internally.
-
-```tsx
-import { SocialButtons } from '@authon/react';
-
-// Vertical list (default)
-<SocialButtons
-  onSuccess={() => console.log('Signed in!')}
-  onError={(error) => console.error(error)}
-/>
-
-// Compact icon row
-<SocialButtons
-  compact
-  gap={12}
-  labels={{ google: 'Sign in with Google', kakao: '카카오로 로그인' }}
-  buttonProps={{ borderRadius: 8 }}
-/>
-```
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `onSuccess` | `() => void` (optional) | — | Called after successful OAuth sign-in |
-| `onError` | `(error: Error) => void` (optional) | — | Called on OAuth error |
-| `className` | `string` (optional) | — | Container class |
-| `style` | `CSSProperties` (optional) | — | Container style |
-| `gap` | `number` (optional) | `10` (`12` compact) | Gap between buttons in px |
-| `compact` | `boolean` | `false` | Render icon-only buttons in a row |
-| `labels` | `Partial<Record<OAuthProviderType, string>>` (optional) | — | Custom label per provider |
-| `buttonProps` | `Partial<SocialButtonProps>` (optional) | — | Props forwarded to each `<SocialButton>` |
-
----
-
-## Hooks
-
-### `useAuthon()`
-
-Returns the full auth context. Throws if used outside `<AuthonProvider>`.
+### Protect a Route
 
 ```tsx
-import { useAuthon } from '@authon/react';
-
-function ProfileButton() {
-  const { isSignedIn, isLoading, user, signOut, openSignIn, openSignUp, getToken, client } = useAuthon();
-
-  if (isLoading) return <span>Loading...</span>;
-
-  if (!isSignedIn) {
-    return <button onClick={() => openSignIn()}>Sign In</button>;
-  }
+import { Protect } from '@authon/react';
 
+function Dashboard() {
   return (
-    <div>
-      <span>Hello, {user?.displayName}</span>
-      <button onClick={() => signOut()}>Sign Out</button>
-    </div>
+    <Protect fallback={<p>Please sign in to view this page.</p>}>
+      <h1>Dashboard</h1>
+    </Protect>
   );
 }
-```
 
-**Return type:**
-
-```ts
-interface AuthonContextValue {
-  isSignedIn: boolean;
-  isLoading: boolean;
-  user: AuthonUser | null;
-  signOut: () => Promise<void>;
-  openSignIn: () => Promise<void>;
-  openSignUp: () => Promise<void>;
-  getToken: () => string | null;
-  client: Authon | null;
+// With role-based condition
+function AdminPanel() {
+  return (
+    <Protect
+      condition={(user) => user.publicMetadata?.role === 'admin'}
+      fallback={<p>Admin access required.</p>}
+    >
+      <h1>Admin Panel</h1>
+    </Protect>
+  );
 }
 ```
 
----
-
-### `useUser()`
-
-Shorthand hook that returns only the current user and loading state.
+### Get Current User
 
 ```tsx
 import { useUser } from '@authon/react';
 
-function WelcomeBanner() {
+function Profile() {
   const { user, isLoading } = useUser();
-
   if (isLoading) return <p>Loading...</p>;
-  if (!user) return null;
-
-  return <h2>Welcome back, {user.displayName ?? user.email}!</h2>;
-}
-```
-
-**Return type:**
-
-```ts
-{
-  user: AuthonUser | null;
-  isLoading: boolean;
-}
-```
-
----
-
-### `useAuthonMfa()`
-
-Manages TOTP-based multi-factor authentication (Google Authenticator, Authy, etc.).
-
-```tsx
-import { useAuthonMfa } from '@authon/react';
-import { useState } from 'react';
-
-function MfaSetupPage() {
-  const { setupMfa, verifyMfaSetup, disableMfa, getMfaStatus, regenerateBackupCodes, isLoading, error } = useAuthonMfa();
-  const [qrSvg, setQrSvg] = useState('');
-  const [backupCodes, setBackupCodes] = useState<string[]>([]);
-  const [code, setCode] = useState('');
-
-  const handleSetup = async () => {
-    const result = await setupMfa();
-    if (result) {
-      setQrSvg(result.qrCodeSvg);
-      setBackupCodes(result.backupCodes);
-    }
-  };
-
-  const handleVerify = async () => {
-    const success = await verifyMfaSetup(code);
-    if (success) alert('MFA enabled successfully!');
-  };
-
-  const handleCheckStatus = async () => {
-    const status = await getMfaStatus();
-    console.log('MFA enabled:', status?.enabled, 'Backup codes left:', status?.backupCodesRemaining);
-  };
-
-  return (
-    <div>
-      <button onClick={handleSetup} disabled={isLoading}>
-        Enable MFA
-      </button>
-
-      {qrSvg && (
-        <>
-          <div dangerouslySetInnerHTML={{ __html: qrSvg }} />
-          <p>Backup codes: {backupCodes.join(', ')}</p>
-          <input
-            value={code}
-            onChange={(e) => setCode(e.target.value)}
-            placeholder="Enter 6-digit code"
-          />
-          <button onClick={handleVerify} disabled={isLoading}>
-            Verify & Enable
-          </button>
-        </>
-      )}
-
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
-    </div>
-  );
-}
-```
-
-**MFA sign-in flow (verifying TOTP after password):**
-
-```tsx
-import { useAuthon, useAuthonMfa } from '@authon/react';
-import { AuthonMfaRequiredError } from '@authon/js';
-
-function LoginForm() {
-  const { client } = useAuthon();
-  const { verifyMfa, isLoading } = useAuthonMfa();
-  const [mfaToken, setMfaToken] = useState('');
-  const [mfaStep, setMfaStep] = useState(false);
-
-  const handleSignIn = async (email: string, password: string) => {
-    try {
-      await client!.signInWithEmail(email, password);
-      // signed in — no MFA required
-    } catch (err) {
-      if (err instanceof AuthonMfaRequiredError) {
-        setMfaToken(err.mfaToken);
-        setMfaStep(true);
-      }
-    }
-  };
-
-  const handleMfa = async (code: string) => {
-    const success = await verifyMfa(mfaToken, code);
-    if (success) console.log('Signed in with MFA!');
-  };
-
-  // ...
-}
-```
-
-**Return type:**
-
-```ts
-interface UseAuthonMfaReturn {
-  setupMfa: () => Promise<(MfaSetupResponse & { qrCodeSvg: string }) | null>;
-  verifyMfaSetup: (code: string) => Promise<boolean>;
-  verifyMfa: (mfaToken: string, code: string) => Promise<boolean>;
-  disableMfa: (code: string) => Promise<boolean>;
-  getMfaStatus: () => Promise<MfaStatus | null>;
-  regenerateBackupCodes: (code: string) => Promise<string[] | null>;
-  isLoading: boolean;
-  error: Error | null;
-}
-```
-
----
-
-### `useAuthonPasskeys()`
-
-Manages WebAuthn passkey registration and authentication.
-
-```tsx
-import { useAuthonPasskeys } from '@authon/react';
-
-function PasskeySettings() {
-  const {
-    registerPasskey,
-    authenticateWithPasskey,
-    listPasskeys,
-    renamePasskey,
-    revokePasskey,
-    isLoading,
-    error,
-  } = useAuthonPasskeys();
-
-  const handleRegister = async () => {
-    const passkey = await registerPasskey('My MacBook');
-    if (passkey) {
-      console.log('Passkey registered:', passkey.id);
-    }
-  };
-
-  const handleList = async () => {
-    const passkeys = await listPasskeys();
-    console.log('Registered passkeys:', passkeys);
-  };
-
-  const handleRevoke = async (id: string) => {
-    const success = await revokePasskey(id);
-    if (success) console.log('Passkey revoked');
-  };
-
+  if (!user) return <p>Not signed in</p>;
   return (
     <div>
-      <button onClick={handleRegister} disabled={isLoading}>
-        Add Passkey
-      </button>
-      <button onClick={handleList} disabled={isLoading}>
-        List Passkeys
-      </button>
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
+      <p>Email: {user.email}</p>
+      <p>Name: {user.displayName}</p>
     </div>
   );
 }
 ```
 
-**Return type:**
-
-```ts
-interface UseAuthonPasskeysReturn {
-  registerPasskey: (name?: string) => Promise<PasskeyCredential | null>;
-  authenticateWithPasskey: (email?: string) => Promise<boolean>;
-  listPasskeys: () => Promise<PasskeyCredential[] | null>;
-  renamePasskey: (id: string, name: string) => Promise<PasskeyCredential | null>;
-  revokePasskey: (id: string) => Promise<boolean>;
-  isLoading: boolean;
-  error: Error | null;
-}
-```
-
----
-
-### `useAuthonPasswordless()`
-
-Handles magic link and email OTP (one-time password) authentication flows.
+### Add Email/Password Auth
 
 ```tsx
-import { useAuthonPasswordless } from '@authon/react';
+import { useAuthon } from '@authon/react';
 import { useState } from 'react';
 
-function PasswordlessLogin() {
-  const { sendMagicLink, sendEmailOtp, verifyPasswordless, isLoading, error } = useAuthonPasswordless();
+function EmailSignIn() {
+  const { client } = useAuthon();
   const [email, setEmail] = useState('');
-  const [otpSent, setOtpSent] = useState(false);
-  const [code, setCode] = useState('');
+  const [password, setPassword] = useState('');
 
-  const handleSendOtp = async () => {
-    const success = await sendEmailOtp(email);
-    if (success) setOtpSent(true);
-  };
-
-  const handleVerifyOtp = async () => {
-    const success = await verifyPasswordless({ email, code });
-    if (success) console.log('Signed in!');
-  };
-
-  const handleMagicLink = async () => {
-    const success = await sendMagicLink(email);
-    if (success) alert('Check your email for a sign-in link!');
-  };
-
-  // Verify magic link token from URL
-  const handleTokenVerify = async (token: string) => {
-    const success = await verifyPasswordless({ token });
-    if (success) console.log('Signed in via magic link!');
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    await client?.signInWithEmail(email, password);
   };
 
   return (
-    <div>
-      <input value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
-      <button onClick={handleMagicLink} disabled={isLoading}>Send Magic Link</button>
-      <button onClick={handleSendOtp} disabled={isLoading}>Send OTP</button>
-
-      {otpSent && (
-        <>
-          <input value={code} onChange={(e) => setCode(e.target.value)} placeholder="Enter code" />
-          <button onClick={handleVerifyOtp} disabled={isLoading}>Verify</button>
-        </>
-      )}
-
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
-    </div>
+    <form onSubmit={handleSubmit}>
+      <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email" />
+      <input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" />
+      <button type="submit">Sign In</button>
+    </form>
   );
 }
 ```
 
-**Return type:**
-
-```ts
-interface UseAuthonPasswordlessReturn {
-  sendMagicLink: (email: string) => Promise<boolean>;
-  sendEmailOtp: (email: string) => Promise<boolean>;
-  verifyPasswordless: (opts: { token?: string; email?: string; code?: string }) => Promise<boolean>;
-  isLoading: boolean;
-  error: Error | null;
-}
-```
-
----
-
-### `useAuthonWeb3()`
-
-Handles Web3 wallet authentication (Sign-In with Ethereum / Solana).
+### Handle Sign Out
 
 ```tsx
-import { useAuthonWeb3 } from '@authon/react';
-
-function Web3Login() {
-  const { getNonce, verify, listWallets, linkWallet, unlinkWallet, isLoading, error } = useAuthonWeb3();
-
-  const handleSignIn = async () => {
-    const address = '0xYourAddress';
-
-    // 1. Get a nonce to sign
-    const nonceResponse = await getNonce(address, 'evm', 'metamask', 1);
-    if (!nonceResponse) return;
-
-    // 2. Sign the message with your wallet (e.g. MetaMask)
-    const signature = await window.ethereum.request({
-      method: 'personal_sign',
-      params: [nonceResponse.message, address],
-    });
-
-    // 3. Verify the signature to sign in
-    const success = await verify(nonceResponse.message, signature, address, 'evm', 'metamask');
-    if (success) console.log('Signed in with wallet!');
-  };
-
-  const handleLinkWallet = async () => {
-    const address = '0xYourAddress';
-    const nonceResponse = await getNonce(address, 'evm', 'metamask');
-    if (!nonceResponse) return;
-
-    const signature = await window.ethereum.request({
-      method: 'personal_sign',
-      params: [nonceResponse.message, address],
-    });
-
-    const wallet = await linkWallet({
-      address,
-      chain: 'evm',
-      walletType: 'metamask',
-      message: nonceResponse.message,
-      signature,
-    });
-
-    if (wallet) console.log('Wallet linked:', wallet.id);
-  };
-
-  const handleListWallets = async () => {
-    const wallets = await listWallets();
-    console.log('Linked wallets:', wallets);
-  };
-
-  return (
-    <div>
-      <button onClick={handleSignIn} disabled={isLoading}>Sign In with MetaMask</button>
-      <button onClick={handleLinkWallet} disabled={isLoading}>Link Wallet</button>
-      <button onClick={handleListWallets} disabled={isLoading}>List Wallets</button>
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
-    </div>
-  );
-}
-```
-
-**Return type:**
-
-```ts
-interface UseAuthonWeb3Return {
-  getNonce: (
-    address: string,
-    chain: Web3Chain,
-    walletType: Web3WalletType,
-    chainId?: number,
-  ) => Promise<Web3NonceResponse | null>;
-  verify: (
-    message: string,
-    signature: string,
-    address: string,
-    chain: Web3Chain,
-    walletType: Web3WalletType,
-  ) => Promise<boolean>;
-  listWallets: () => Promise<Web3Wallet[] | null>;
-  linkWallet: (params: LinkWalletParams) => Promise<Web3Wallet | null>;
-  unlinkWallet: (walletId: string) => Promise<boolean>;
-  isLoading: boolean;
-  error: Error | null;
-}
-
-interface LinkWalletParams {
-  address: string;
-  chain: Web3Chain;
-  walletType: Web3WalletType;
-  chainId?: number;
-  message: string;
-  signature: string;
-}
-
-type Web3Chain = 'evm' | 'solana';
-type Web3WalletType = 'metamask' | 'pexus' | 'walletconnect' | 'coinbase' | 'phantom' | 'trust' | 'other';
-```
-
----
-
-### `useAuthonSessions()`
-
-Lists and revokes active user sessions.
-
-```tsx
-import { useAuthonSessions } from '@authon/react';
-import { useEffect, useState } from 'react';
-import type { SessionInfo } from '@authon/shared';
-
-function SessionManager() {
-  const { listSessions, revokeSession, isLoading, error } = useAuthonSessions();
-  const [sessions, setSessions] = useState<SessionInfo[]>([]);
-
-  useEffect(() => {
-    listSessions().then((s) => {
-      if (s) setSessions(s);
-    });
-  }, []);
-
-  const handleRevoke = async (sessionId: string) => {
-    const success = await revokeSession(sessionId);
-    if (success) {
-      setSessions((prev) => prev.filter((s) => s.id !== sessionId));
-    }
-  };
-
-  if (isLoading) return <p>Loading sessions...</p>;
-
-  return (
-    <ul>
-      {sessions.map((session) => (
-        <li key={session.id}>
-          <span>{session.userAgent ?? 'Unknown device'}</span>
-          <span>{session.ipAddress}</span>
-          <button onClick={() => handleRevoke(session.id)}>Revoke</button>
-        </li>
-      ))}
-      {error && <p style={{ color: 'red' }}>{error.message}</p>}
-    </ul>
-  );
-}
-```
-
-**Return type:**
-
-```ts
-interface UseAuthonSessionsReturn {
-  listSessions: () => Promise<SessionInfo[] | null>;
-  revokeSession: (sessionId: string) => Promise<boolean>;
-  isLoading: boolean;
-  error: Error | null;
-}
-```
-
----
-
-## TypeScript Types
-
-Key types exported from `@authon/react` and `@authon/shared`:
-
-```ts
-import type {
-  AuthonContextValue,
-  SocialButtonProps,
-  SocialButtonsProps,
-  UseAuthonMfaReturn,
-  UseAuthonPasskeysReturn,
-  UseAuthonPasswordlessReturn,
-  UseAuthonWeb3Return,
-  LinkWalletParams,
-  UseAuthonSessionsReturn,
-} from '@authon/react';
-
-import type {
-  AuthonUser,
-  SessionInfo,
-  PasskeyCredential,
-  Web3Wallet,
-  Web3NonceResponse,
-  MfaSetupResponse,
-  MfaStatus,
-  OAuthProviderType,
-  Web3Chain,
-  Web3WalletType,
-} from '@authon/shared';
-```
-
----
-
-## Documentation
+import { useAuthon } from '@authon/react';
 
-[authon.dev/docs](https://authon.dev/docs)
+function SignOutButton() {
+  const { signOut } = useAuthon();
+  return <button onClick={() => signOut()}>Sign Out</button>;
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `AUTHON_PUBLISHABLE_KEY` | Yes | Project publishable key (`pk_live_...` or `pk_test_...`) |
+| `AUTHON_API_URL` | No | Optional — defaults to `api.authon.dev` |
+
+## API Reference
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `<AuthonProvider>` | Context provider. Props: `publishableKey`, `config?` |
+| `<SignIn>` | Pre-built sign-in form (`mode="popup"` or `"embedded"`) |
+| `<SignUp>` | Pre-built sign-up form |
+| `<UserButton>` | Avatar dropdown with user info and sign-out |
+| `<UserProfile>` | Full user profile management |
+| `<SignedIn>` | Renders children only when signed in |
+| `<SignedOut>` | Renders children only when signed out |
+| `<Protect>` | Conditional render with `fallback` and `condition` |
+| `<SocialButton>` | Single OAuth provider button |
+| `<SocialButtons>` | All enabled OAuth provider buttons |
+
+### Hooks
+
+| Hook | Returns |
+|------|---------|
+| `useAuthon()` | `{ isSignedIn, isLoading, user, signOut, openSignIn, openSignUp, getToken, client }` |
+| `useUser()` | `{ user, isLoading }` |
+| `useAuthonMfa()` | MFA setup, verification, and management |
+| `useAuthonPasskeys()` | Passkey registration and authentication |
+| `useAuthonPasswordless()` | Magic link and email OTP |
+| `useAuthonWeb3()` | Web3 wallet sign-in and management |
+| `useAuthonSessions()` | List and revoke active sessions |
+| `useOrganization()` | Active organization management |
+| `useOrganizationList()` | List and switch organizations |
+
+## Comparison
+
+| Feature | Authon | Clerk | Auth.js |
+|---------|--------|-------|---------|
+| Pricing | Free | $25/mo+ | Free |
+| OAuth providers | 10+ | 20+ | 80+ |
+| ShadowDOM modal | Yes | No | No |
+| MFA/Passkeys | Yes | Yes | Plugin |
+| Web3 auth | Yes | No | No |
+| Organizations | Yes | Yes | No |
 
 ## License
 
-[MIT](../../LICENSE)
+MIT