@neondatabase/neon-js 0.1.0-beta.13 → 0.1.0-beta.15

package/llms-full.txt

@@ -0,0 +1,1181 @@
+# @neondatabase/neon-js - Complete Documentation
+
+> The official TypeScript SDK for Neon - unified client combining authentication and PostgreSQL database querying with automatic token management, session caching, and request deduplication.
+
+This comprehensive documentation covers both `@neondatabase/neon-js` (the unified SDK) and `@neondatabase/auth` (the standalone auth package).
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Quick Start](#quick-start)
+3. [Authentication](#authentication)
+4. [Auth Adapters](#auth-adapters)
+5. [Anonymous Access](#anonymous-access)
+6. [Database Querying](#database-querying)
+7. [TypeScript Support](#typescript-support)
+8. [Next.js Integration](#nextjs-integration)
+9. [UI Components](#ui-components)
+10. [Performance Features](#performance-features)
+11. [API Reference](#api-reference)
+
+---
+
+## Installation
+
+### Full SDK (Auth + Data API)
+
+```bash
+npm install @neondatabase/neon-js
+```
+
+### Auth Only
+
+```bash
+npm install @neondatabase/auth
+```
+
+---
+
+## Quick Start
+
+### Unified Client (neon-js)
+
+```typescript
+import { createClient } from '@neondatabase/neon-js';
+
+// Database type generated via: npx neon-js gen-types --db-url "..."
+const client = createClient<Database>({
+  auth: {
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+// Authenticate
+await client.auth.signIn.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+
+// Query database (token automatically injected)
+const { data: users } = await client
+  .from('users')
+  .select('*')
+  .eq('status', 'active');
+```
+
+### Auth Only
+
+```typescript
+import { createAuthClient } from '@neondatabase/auth';
+
+const auth = createAuthClient('https://your-auth-server.com');
+
+// Sign up
+await auth.signUp.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+  name: 'John Doe',
+});
+
+// Sign in
+await auth.signIn.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+
+// Get session
+const session = await auth.getSession();
+
+// Sign out
+await auth.signOut();
+```
+
+---
+
+## Authentication
+
+### Sign Up
+
+```typescript
+// With neon-js
+await client.auth.signUp.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+  name: 'John Doe',
+});
+
+// With auth package
+await auth.signUp.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+  name: 'John Doe',
+});
+```
+
+### Sign In with Email/Password
+
+```typescript
+await client.auth.signIn.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+```
+
+### Sign In with OAuth
+
+```typescript
+await client.auth.signIn.social({
+  provider: 'google',
+  callbackURL: '/dashboard',
+});
+
+// Supported providers: 'google', 'github', etc.
+```
+
+### Session Management
+
+```typescript
+// Get current session
+const session = await client.auth.getSession();
+
+// Session contains:
+// - session.id
+// - session.userId
+// - session.expiresAt
+// - user.id
+// - user.email
+// - user.name
+// - user.image
+
+// Sign out
+await client.auth.signOut();
+```
+
+---
+
+## Auth Adapters
+
+### Default API (Better Auth)
+
+The default API follows Better Auth patterns:
+
+```typescript
+import { createAuthClient } from '@neondatabase/auth';
+
+const auth = createAuthClient('https://your-auth-server.com');
+
+// Methods available:
+auth.signIn.email({ email, password });
+auth.signIn.social({ provider, callbackURL });
+auth.signUp.email({ email, password, name });
+auth.signOut();
+auth.getSession();
+```
+
+### SupabaseAuthAdapter
+
+Supabase-compatible API for easier migrations from Supabase:
+
+```typescript
+import { createAuthClient, SupabaseAuthAdapter } from '@neondatabase/auth';
+
+const auth = createAuthClient('https://your-auth-server.com', {
+  adapter: SupabaseAuthAdapter(),
+});
+
+// Sign up with metadata
+await auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    data: { name: 'John Doe' },
+  },
+});
+
+// Sign in
+await auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+
+// OAuth sign in
+await auth.signInWithOAuth({
+  provider: 'google',
+  options: {
+    redirectTo: '/dashboard',
+  },
+});
+
+// Session with data wrapper
+const { data: session } = await auth.getSession();
+const { data: user } = await auth.getUser();
+
+// Update user
+await auth.updateUser({
+  data: { name: 'New Name' },
+});
+
+// Password reset
+await auth.resetPasswordForEmail('user@example.com', {
+  redirectTo: '/reset-password',
+});
+
+// Auth state changes
+auth.onAuthStateChange((event, session) => {
+  console.log(event, session);
+  // Events: 'SIGNED_IN', 'SIGNED_OUT', 'TOKEN_REFRESHED', etc.
+});
+
+// Identity management
+const { data: identities } = await auth.getUserIdentities();
+await auth.linkIdentity({ provider: 'github' });
+await auth.unlinkIdentity({ providerId: 'github', identityId: '123' });
+```
+
+### BetterAuthReactAdapter
+
+React hooks support for client-side session management:
+
+```typescript
+import { createAuthClient } from '@neondatabase/auth';
+import { BetterAuthReactAdapter } from '@neondatabase/auth/react/adapters';
+
+const auth = createAuthClient('https://your-auth-server.com', {
+  adapter: BetterAuthReactAdapter(),
+});
+
+// Same API as default, plus React hooks
+function MyComponent() {
+  const session = auth.useSession();
+
+  if (session.isPending) return <div>Loading...</div>;
+  if (!session.data) return <div>Not logged in</div>;
+
+  return (
+    <div>
+      <p>Hello, {session.data.user.name}</p>
+      <p>Email: {session.data.user.email}</p>
+      <button onClick={() => auth.signOut()}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+### Using Adapters with neon-js
+
+```typescript
+import { createClient, SupabaseAuthAdapter } from '@neondatabase/neon-js';
+
+const client = createClient<Database>({
+  auth: {
+    adapter: SupabaseAuthAdapter(),
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+// Access Supabase-style methods via client.auth
+await client.auth.signInWithPassword({ email, password });
+```
+
+```typescript
+import { createClient } from '@neondatabase/neon-js';
+import { BetterAuthReactAdapter } from '@neondatabase/neon-js/auth/react/adapters';
+
+const client = createClient<Database>({
+  auth: {
+    adapter: BetterAuthReactAdapter(),
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+// Use React hooks
+function Dashboard() {
+  const session = client.auth.useSession();
+  // ...
+}
+```
+
+---
+
+## Anonymous Access
+
+Enable RLS-based data access for unauthenticated users:
+
+```typescript
+// With neon-js
+const client = createClient<Database>({
+  auth: {
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+    allowAnonymous: true,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+// Works without signing in - uses anonymous token for RLS
+const { data: publicItems } = await client.from('public_items').select();
+
+// With auth package
+const auth = createAuthClient('https://your-auth-server.com', {
+  allowAnonymous: true,
+});
+
+// Returns anonymous token if no user session exists
+const token = await auth.getJWTToken?.();
+```
+
+This is useful for:
+- Public read-only access to certain data
+- Enforcing RLS policies for unauthenticated users
+- Gradual authentication (anonymous → signed in)
+
+---
+
+## Database Querying
+
+### SELECT Queries
+
+```typescript
+// Simple select
+const { data } = await client.from('users').select('id, name, email');
+
+// Select all columns
+const { data } = await client.from('users').select('*');
+
+// Select with count
+const { data, count } = await client
+  .from('users')
+  .select('*', { count: 'exact' });
+```
+
+### Filtering
+
+```typescript
+// Equality
+const { data } = await client.from('users').select('*').eq('status', 'active');
+
+// Not equal
+const { data } = await client.from('users').select('*').neq('status', 'deleted');
+
+// Greater than / Less than
+const { data } = await client
+  .from('posts')
+  .select('*')
+  .gt('views', 100)
+  .lt('views', 1000);
+
+// Greater than or equal / Less than or equal
+const { data } = await client.from('posts').select('*').gte('views', 100).lte('views', 1000);
+
+// Pattern matching
+const { data } = await client.from('users').select('*').like('name', '%John%');
+const { data } = await client.from('users').select('*').ilike('name', '%john%'); // case-insensitive
+
+// In array
+const { data } = await client.from('users').select('*').in('status', ['active', 'pending']);
+
+// Is null / Is not null
+const { data } = await client.from('users').select('*').is('deleted_at', null);
+const { data } = await client.from('users').select('*').not('email', 'is', null);
+
+// Contains (for arrays/JSONB)
+const { data } = await client.from('posts').select('*').contains('tags', ['typescript']);
+
+// Contained by
+const { data } = await client.from('posts').select('*').containedBy('tags', ['typescript', 'javascript']);
+
+// Range filters
+const { data } = await client.from('events').select('*').rangeGt('dates', '[2024-01-01, 2024-12-31]');
+```
+
+### Ordering
+
+```typescript
+const { data } = await client
+  .from('posts')
+  .select('*')
+  .order('created_at', { ascending: false });
+
+// Multiple columns
+const { data } = await client
+  .from('posts')
+  .select('*')
+  .order('category', { ascending: true })
+  .order('created_at', { ascending: false });
+
+// Nulls first/last
+const { data } = await client
+  .from('posts')
+  .select('*')
+  .order('published_at', { ascending: false, nullsFirst: false });
+```
+
+### Pagination
+
+```typescript
+// Limit and offset
+const { data } = await client.from('users').select('*').range(0, 9); // First 10
+
+// Using limit
+const { data } = await client.from('users').select('*').limit(10);
+
+// Pagination with count
+const { data, count } = await client
+  .from('users')
+  .select('*', { count: 'exact' })
+  .range(0, 9);
+```
+
+### Joins (Foreign Tables)
+
+```typescript
+// One-to-many
+const { data } = await client
+  .from('posts')
+  .select(`
+    id,
+    title,
+    author:users(id, name, email)
+  `);
+
+// Many-to-many
+const { data } = await client
+  .from('posts')
+  .select(`
+    id,
+    title,
+    tags:post_tags(
+      tag:tags(id, name)
+    )
+  `);
+
+// Nested joins
+const { data } = await client
+  .from('posts')
+  .select(`
+    id,
+    title,
+    author:users(
+      id,
+      name,
+      organization:organizations(id, name)
+    )
+  `);
+
+// Filter on joined table
+const { data } = await client
+  .from('posts')
+  .select('*, author:users!inner(*)')
+  .eq('author.status', 'active');
+```
+
+### INSERT Queries
+
+```typescript
+// Insert single row
+const { data } = await client
+  .from('users')
+  .insert({
+    name: 'Alice',
+    email: 'alice@example.com',
+  })
+  .select();
+
+// Insert multiple rows
+const { data } = await client
+  .from('users')
+  .insert([
+    { name: 'Bob', email: 'bob@example.com' },
+    { name: 'Carol', email: 'carol@example.com' },
+  ])
+  .select();
+
+// Insert with returning specific columns
+const { data } = await client
+  .from('users')
+  .insert({ name: 'Dave', email: 'dave@example.com' })
+  .select('id, name');
+
+// Upsert (insert or update)
+const { data } = await client
+  .from('users')
+  .upsert({ id: 1, name: 'Updated Name' })
+  .select();
+
+// Upsert with conflict resolution
+const { data } = await client
+  .from('users')
+  .upsert(
+    { email: 'user@example.com', name: 'New Name' },
+    { onConflict: 'email' }
+  )
+  .select();
+```
+
+### UPDATE Queries
+
+```typescript
+// Update with filter
+const { data } = await client
+  .from('users')
+  .update({ status: 'inactive' })
+  .eq('last_login', null)
+  .select();
+
+// Update multiple columns
+const { data } = await client
+  .from('users')
+  .update({
+    name: 'New Name',
+    updated_at: new Date().toISOString(),
+  })
+  .eq('id', 123)
+  .select();
+```
+
+### DELETE Queries
+
+```typescript
+// Delete with filter
+const { data } = await client
+  .from('users')
+  .delete()
+  .eq('status', 'deleted')
+  .select();
+
+// Delete single row
+const { data } = await client
+  .from('users')
+  .delete()
+  .eq('id', 123)
+  .select();
+```
+
+### RPC (Stored Procedures)
+
+```typescript
+// Call a function
+const { data } = await client.rpc('get_user_stats', {
+  user_id: 123,
+  start_date: '2024-01-01',
+});
+
+// Function returning set of rows
+const { data } = await client
+  .rpc('search_users', { query: 'john' })
+  .select('id, name, email')
+  .limit(10);
+```
+
+### Error Handling
+
+```typescript
+const { data, error } = await client.from('users').select('*');
+
+if (error) {
+  console.error('Query failed:', error.message);
+  console.error('Code:', error.code);
+  console.error('Details:', error.details);
+  console.error('Hint:', error.hint);
+  return;
+}
+
+// data is guaranteed to be non-null here
+console.log(data);
+```
+
+---
+
+## TypeScript Support
+
+### Generate Types from Database
+
+```bash
+# Generate types
+npx neon-js gen-types \
+  --db-url "postgresql://user:pass@host/db" \
+  --output ./types/database.ts
+
+# With schema filtering
+npx neon-js gen-types \
+  --db-url "postgresql://user:pass@host/db" \
+  --schemas public,auth \
+  --output ./types/database.ts
+```
+
+### Using Generated Types
+
+```typescript
+import type { Database } from './types/database';
+import { createClient } from '@neondatabase/neon-js';
+
+const client = createClient<Database>({
+  auth: { url: process.env.NEON_AUTH_URL! },
+  dataApi: { url: process.env.NEON_DATA_API_URL! },
+});
+
+// Fully typed queries with autocomplete
+const { data } = await client
+  .from('users')  // Autocomplete for table names
+  .select('id, name, email')  // Autocomplete for column names
+  .eq('status', 'active');  // Type checking for values
+
+// data is typed as Pick<Database['public']['users']['Row'], 'id' | 'name' | 'email'>[]
+```
+
+### CLI Options
+
+- `--db-url`, `-c` - PostgreSQL connection string (required)
+- `--output`, `-o` - Output file path (default: `./types/database.ts`)
+- `--schemas`, `-s` - Comma-separated list of schemas (default: `public`)
+
+---
+
+## Next.js Integration
+
+### 1. Install the Package
+
+```bash
+npm install @neondatabase/auth
+```
+
+### 2. Set Environment Variable
+
+```bash
+# .env.local
+NEON_AUTH_BASE_URL=https://your-neon-auth-url.neon.tech
+```
+
+### 3. Create Auth Handler
+
+Mount the auth handler to an API route:
+
+```typescript
+// app/api/auth/[...path]/route.ts
+import { authApiHandler } from "@neondatabase/auth/next"
+
+export const { GET, POST } = authApiHandler()
+```
+
+### 4. Set Up Middleware
+
+Protect routes and handle session validation:
+
+```typescript
+// middleware.ts
+import { neonAuthMiddleware } from "@neondatabase/auth/next"
+
+export default neonAuthMiddleware({
+  loginUrl: "/auth/sign-in",
+})
+
+export const config = {
+  matcher: [
+    "/((?!_next/static|_next/image|favicon.ico).*)",
+  ],
+}
+```
+
+### 5. Create Auth Client
+
+```typescript
+// lib/auth-client.ts
+"use client"
+
+import { createAuthClient } from "@neondatabase/auth/next"
+
+export const authClient = createAuthClient()
+
+// Or with anonymous access
+export const authClient = createAuthClient({
+  allowAnonymous: true,
+})
+```
+
+### 6. Set Up NeonAuthUIProvider
+
+```typescript
+// app/providers.tsx
+"use client"
+
+import { NeonAuthUIProvider } from "@neondatabase/auth/react/ui"
+import Link from "next/link"
+import { useRouter } from "next/navigation"
+import type { ReactNode } from "react"
+
+import { authClient } from "@/lib/auth-client"
+
+export function Providers({ children }: { children: ReactNode }) {
+  const router = useRouter()
+
+  return (
+    <NeonAuthUIProvider
+      authClient={authClient}
+      navigate={router.push}
+      replace={router.replace}
+      onSessionChange={() => router.refresh()}
+      emailOTP
+      social={{ providers: ["google"] }}
+      redirectTo="/dashboard"
+      Link={Link}
+      organization={{}}
+    >
+      {children}
+    </NeonAuthUIProvider>
+  )
+}
+```
+
+```typescript
+// app/layout.tsx
+import { Providers } from "./providers"
+import "./globals.css"
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+### 7. Import CSS Styles
+
+#### Without Tailwind CSS
+
+```typescript
+// In your root layout or app entry point
+import "@neondatabase/auth/ui/css"
+```
+
+#### With Tailwind CSS v4
+
+```css
+/* globals.css */
+@import "tailwindcss";
+@import "@neondatabase/auth/ui/tailwind";
+```
+
+### 8. Create Auth Pages
+
+#### Auth Page (Sign In, Sign Up, etc.)
+
+```typescript
+// app/auth/[path]/page.tsx
+import { AuthView } from "@neondatabase/auth/react/ui"
+import { authViewPaths } from "@neondatabase/auth/react/ui/server"
+
+export const dynamicParams = false
+
+export function generateStaticParams() {
+  return Object.values(authViewPaths).map((path) => ({ path }))
+}
+
+export default async function AuthPage({
+  params,
+}: {
+  params: Promise<{ path: string }>
+}) {
+  const { path } = await params
+
+  return (
+    <main className="container flex grow flex-col items-center justify-center p-4">
+      <AuthView path={path} />
+    </main>
+  )
+}
+```
+
+Automatically handles these routes:
+- `/auth/sign-in` - Sign in page
+- `/auth/sign-up` - Sign up page
+- `/auth/magic-link` - Magic link authentication
+- `/auth/forgot-password` - Password reset request
+- `/auth/two-factor` - Two-factor authentication
+- `/auth/recover-account` - Account recovery
+- `/auth/reset-password` - Password reset
+- `/auth/sign-out` - Sign out
+- `/auth/callback` - OAuth callback
+- `/auth/accept-invitation` - Accept team invitation
+
+#### Account Page
+
+```typescript
+// app/account/[path]/page.tsx
+import { AccountView } from "@neondatabase/auth/react/ui"
+import { accountViewPaths } from "@neondatabase/auth/react/ui/server"
+
+export const dynamicParams = false
+
+export function generateStaticParams() {
+  return Object.values(accountViewPaths).map((path) => ({ path }))
+}
+
+export default async function AccountPage({
+  params,
+}: {
+  params: Promise<{ path: string }>
+}) {
+  const { path } = await params
+
+  return (
+    <main className="container p-4">
+      <AccountView path={path} />
+    </main>
+  )
+}
+```
+
+#### Organization Page
+
+```typescript
+// app/organization/[path]/page.tsx
+import { OrganizationView } from "@neondatabase/auth/react/ui"
+import { organizationViewPaths } from "@neondatabase/auth/react/ui/server"
+
+export const dynamicParams = false
+
+export function generateStaticParams() {
+  return Object.values(organizationViewPaths).map((path) => ({ path }))
+}
+
+export default async function OrganizationPage({
+  params,
+}: {
+  params: Promise<{ path: string }>
+}) {
+  const { path } = await params
+
+  return (
+    <main className="container p-4">
+      <OrganizationView path={path} />
+    </main>
+  )
+}
+```
+
+### 9. Accessing Session Data
+
+#### React Server Components
+
+```typescript
+import { neonAuth } from "@neondatabase/auth/next"
+
+export async function SessionCard() {
+  const { session, user } = await neonAuth()
+  const isLoggedIn = !!session && !!user
+
+  if (!isLoggedIn) {
+    return <div>Not logged in</div>
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user.name || user.email}</p>
+      <p>User ID: {user.id}</p>
+      <p>Session expires: {new Date(session.expiresAt).toLocaleString()}</p>
+      {user.image && <img src={user.image} alt="User avatar" />}
+    </div>
+  )
+}
+```
+
+#### Client Components
+
+```typescript
+"use client"
+
+import { authClient } from "@/lib/auth-client"
+
+export default function DashboardPage() {
+  const { data: session, isPending } = authClient.useSession()
+
+  if (isPending) {
+    return <div>Loading...</div>
+  }
+
+  if (!session) {
+    return <div>Not authenticated</div>
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {session.user.name || session.user.email}</h1>
+      <p>User ID: {session.user.id}</p>
+      <p>Session ID: {session.session.id}</p>
+    </div>
+  )
+}
+```
+
+### Next.js Project Structure
+
+```
+app/
+├── api/
+│   └── auth/
+│       └── [...path]/
+│           └── route.ts      # Auth API handlers
+├── auth/
+│   └── [path]/
+│       └── page.tsx          # Auth views (sign-in, sign-up, etc.)
+├── account/
+│   └── [path]/
+│       └── page.tsx          # Account management views
+├── organization/
+│   └── [path]/
+│       └── page.tsx          # Organization views
+├── dashboard/
+│   └── page.tsx              # Protected dashboard page
+├── providers.tsx             # NeonAuthUIProvider setup
+├── layout.tsx                # Root layout with providers
+└── globals.css               # Global styles with Neon Auth CSS
+
+lib/
+└── auth-client.ts            # Auth client instance
+
+middleware.ts                 # Route protection
+```
+
+---
+
+## UI Components
+
+### CSS Imports
+
+| Export | Size | Use Case |
+|--------|------|----------|
+| `@neondatabase/neon-js/ui/css` | ~47KB | Projects without Tailwind |
+| `@neondatabase/neon-js/ui/tailwind` | ~3KB | Projects with Tailwind CSS v4 |
+| `@neondatabase/auth/ui/css` | ~47KB | Auth package without Tailwind |
+| `@neondatabase/auth/ui/tailwind` | ~3KB | Auth package with Tailwind |
+
+### Available Components
+
+All components from `@daveyplate/better-auth-ui` are re-exported:
+
+```typescript
+import {
+  AuthView,
+  AccountView,
+  OrganizationView,
+  SignInForm,
+  SignUpForm,
+  UserButton,
+  // ... and more
+} from '@neondatabase/auth/react/ui';
+```
+
+### Customizing Theme
+
+Override CSS custom properties:
+
+```css
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  /* ... */
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  /* ... */
+}
+```
+
+---
+
+## Performance Features
+
+### Session Caching
+
+Sessions are cached in memory with intelligent TTL management:
+
+- **Default TTL**: 60 seconds
+- **Automatic expiration**: Based on JWT `exp` claim
+- **Lazy expiration checking**: On reads
+- **Synchronous cache clearing**: On sign-out
+
+Performance comparison:
+- **Cold start (no cache)**: ~200ms
+- **Cached reads**: <1ms (in-memory, no I/O)
+
+### Request Deduplication
+
+Multiple concurrent authentication calls are automatically deduplicated:
+
+- **Without deduplication**: 10 concurrent calls = 10 requests (~2000ms)
+- **With deduplication**: 10 concurrent calls = 1 request (~200ms)
+- **Result**: 10x faster, N-1 fewer server requests
+
+### Token Management
+
+- Automatic JWT token injection for database queries
+- Token refresh handling
+- Cross-tab session synchronization via BroadcastChannel
+
+---
+
+## API Reference
+
+### createClient(options) - neon-js
+
+```typescript
+import { createClient } from '@neondatabase/neon-js';
+
+const client = createClient<Database>({
+  auth: {
+    url: string;                    // Auth service URL (required)
+    adapter?: AdapterFactory;       // Optional adapter
+    allowAnonymous?: boolean;       // Enable anonymous tokens (default: false)
+  },
+  dataApi: {
+    url: string;                    // Data API URL (required)
+    options?: {
+      db?: {
+        schema?: string;            // Database schema (default: 'public')
+      };
+      global?: {
+        fetch?: typeof fetch;       // Custom fetch implementation
+        headers?: Record<string, string>;  // Global headers
+      };
+    };
+  },
+});
+```
+
+### createAuthClient(url, config?) - auth
+
+```typescript
+import { createAuthClient } from '@neondatabase/auth';
+
+const auth = createAuthClient(
+  url: string,                      // Auth service URL (required)
+  config?: {
+    adapter?: AdapterFactory;       // Optional adapter
+    allowAnonymous?: boolean;       // Enable anonymous tokens (default: false)
+  }
+);
+```
+
+### Default Auth Methods (Better Auth API)
+
+| Method | Description |
+|--------|-------------|
+| `signIn.email({ email, password })` | Sign in with email/password |
+| `signIn.social({ provider, callbackURL })` | Sign in with OAuth |
+| `signUp.email({ email, password, name })` | Create new user |
+| `signOut()` | Sign out current user |
+| `getSession()` | Get current session |
+
+### SupabaseAuthAdapter Methods
+
+| Method | Description |
+|--------|-------------|
+| `signUp({ email, password, options })` | Create user with metadata |
+| `signInWithPassword({ email, password })` | Email/password sign in |
+| `signInWithOAuth({ provider, options })` | OAuth sign in |
+| `getSession()` | Returns `{ data: session }` |
+| `getUser()` | Returns `{ data: user }` |
+| `updateUser({ data })` | Update user metadata |
+| `resetPasswordForEmail(email, options)` | Send password reset |
+| `onAuthStateChange(callback)` | Auth state listener |
+| `getUserIdentities()` | Get linked identities |
+| `linkIdentity({ provider })` | Link OAuth provider |
+| `unlinkIdentity({ providerId, identityId })` | Unlink OAuth provider |
+
+### BetterAuthReactAdapter Methods
+
+Same as default API, plus:
+
+| Method | Description |
+|--------|-------------|
+| `useSession()` | React hook returning `{ data, isPending }` |
+
+### Database Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `from(table)` | Start query on table |
+| `.select(columns)` | Select columns |
+| `.insert(data)` | Insert row(s) |
+| `.update(data)` | Update row(s) |
+| `.delete()` | Delete row(s) |
+| `.upsert(data, options)` | Insert or update |
+| `.rpc(fn, params)` | Call stored procedure |
+
+### Filter Methods
+
+| Method | Description |
+|--------|-------------|
+| `.eq(column, value)` | Equal |
+| `.neq(column, value)` | Not equal |
+| `.gt(column, value)` | Greater than |
+| `.gte(column, value)` | Greater than or equal |
+| `.lt(column, value)` | Less than |
+| `.lte(column, value)` | Less than or equal |
+| `.like(column, pattern)` | Pattern match (case-sensitive) |
+| `.ilike(column, pattern)` | Pattern match (case-insensitive) |
+| `.is(column, value)` | Is null/true/false |
+| `.in(column, values)` | In array |
+| `.contains(column, value)` | Array/JSONB contains |
+| `.containedBy(column, value)` | Contained by |
+| `.range*(column, range)` | Range operations |
+
+### Modifier Methods
+
+| Method | Description |
+|--------|-------------|
+| `.order(column, options)` | Order results |
+| `.limit(count)` | Limit results |
+| `.range(from, to)` | Pagination |
+| `.single()` | Return single row |
+| `.maybeSingle()` | Return single row or null |
+
+---
+
+## Environment Compatibility
+
+- **Node.js**: 14+ (with native fetch or polyfill)
+- **Browser**: All modern browsers
+- **Edge Runtime**: Vercel, Cloudflare Workers, Deno
+- **Bun**: Native support
+
+---
+
+## Related Resources
+
+- [Neon Documentation](https://neon.tech/docs)
+- [Neon Auth Documentation](https://neon.tech/docs/guides/neon-auth)
+- [Better Auth Documentation](https://www.better-auth.com/docs)
+- [better-auth-ui Documentation](https://better-auth-ui.com)
+- [PostgREST Documentation](https://postgrest.org)
+
+## Support
+
+- [GitHub Issues](https://github.com/neondatabase/neon-js/issues)
+- [Neon Community Discord](https://discord.gg/H24eC2UN)
+
+## License
+
+Apache-2.0