@neondatabase/neon-js 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -1,388 +1,519 @@
-# neon-js
+# @neondatabase/neon-js
 
-A unified TypeScript SDK for Neon services, providing seamless integration with **Neon Auth** (authentication service) and **Neon Data API** (PostgreSQL database queries). Built with a Supabase-compatible interface for easy migration and familiar developer experience.
+[![npm downloads](https://img.shields.io/npm/dm/@neondatabase/neon-js.svg)](https://www.npmjs.com/package/@neondatabase/neon-js)
 
-## Features
+The official TypeScript SDK for Neon, combining authentication and database querying in a familiar interface.
 
-- **Unified SDK**: Single client for Neon Auth and Neon Data API
-- **Supabase-Compatible**: Drop-in replacement for easy migration from Supabase
-- **Adapter Pattern**: Pluggable authentication providers (Stack Auth included)
-- **Automatic Token Injection**: Auth-aware fetch wrapper for seamless API calls
-- **TypeScript**: Full type safety with strict mode enabled
-- **Performance Optimized**: Leverages Stack Auth's internal session cache for <5ms session reads
-- **CLI Tool**: Generate TypeScript types from your database schema
+## Overview
 
-## Installation
+`@neondatabase/neon-js` is a comprehensive SDK that brings together Neon Auth and Neon Data API. It provides a unified client for managing authentication and querying PostgreSQL databases with a familiar, intuitive interface.
+
+**Key Features:**
 
-### From npm
+- **Integrated Authentication** - Works out of the box with optional adapters (Supabase-compatible, React hooks)
+- **PostgreSQL Querying** - Full PostgREST client with type-safe queries
+- **High Performance** - Session caching, request deduplication
+- **Automatic Token Management** - Seamless token injection for database queries
+- **TypeScript First** - Fully typed with strict type checking
+- **Universal** - Works in Node.js, browsers, and edge runtimes
+
+## Installation
 
 ```bash
 npm install @neondatabase/neon-js
+# or
+bun add @neondatabase/neon-js
 ```
 
-## Using neon-js
+## Quick Start
 
-1. Create a Neon project with Data API enabled
-2. Copy env vars from the Data API page and set them in your environment
-```bash
-VITE_STACK_PROJECT_ID=
-VITE_STACK_PUBLISHABLE_CLIENT_KEY=
-VITE_NEON_DATA_API_URL=
-```
-3. Instantiate `createClient` with the correct parameters
 ```typescript
-import { createClient } from 'neon-js';
+import { createClient } from '@neondatabase/neon-js';
 
-const client = createClient({
-  url: 'https://your-api.com',
+const client = createClient<Database>({
   auth: {
-    projectId: 'your-project-id',
-    publishableClientKey: 'pk_...',
-    tokenStore: 'cookie', // or 'memory'
+    url: import.meta.env.VITE_NEON_AUTH_URL,
   },
-  options: {
-    // Optional: custom configuration
-    global: {
-      headers: { 'X-Custom-Header': 'value' },
-    },
-    db: {
-      schema: 'public',
-    },
+  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');
 ```
 
-## Migrating from Supabase
+### Using Adapters
+
+You can optionally specify an adapter for different API styles:
+
+#### SupabaseAuthAdapter (Supabase-compatible API)
 
-neon-js provides a Supabase-compatible API, making migration straightforward with minimal code changes. Here's a real-world migration example from the [Todo Guardian Pro project](https://github.com/pffigueiredo/todo-guardian-pro/pull/1).
+Use this adapter if you're migrating from Supabase or prefer the Supabase API style:
 
-### Migration Steps
+```typescript
+import { createClient, SupabaseAuthAdapter } from '@neondatabase/neon-js';
 
-**1. Update Dependencies**
+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,
+  },
+});
 
-Replace `@supabase/supabase-js` with `neon-js` in your `package.json`:
+// Supabase-compatible API
+await client.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
 
-```diff
-- "@supabase/supabase-js": "^2.74.0"
-+ "neon-js": "^0.0.0"
+const { data: session } = await client.auth.getSession();
 ```
 
-**2. Update Environment Variables**
+#### BetterAuthReactAdapter (React Hooks)
 
-Replace Supabase environment variables with Neon equivalents:
+Use this adapter in React applications to get access to hooks like `useSession`:
 
-```diff
-- VITE_SUPABASE_PROJECT_ID="..."
-- VITE_SUPABASE_PUBLISHABLE_KEY="..."
-- VITE_SUPABASE_URL="https://xxx.supabase.co"
-+ VITE_NEON_DATA_API_URL="https://xxx.apirest.c-2.us-east-1.aws.neon.tech/neondb/rest/v1"
-+ VITE_STACK_PROJECT_ID="..."
-+ VITE_STACK_PUBLISHABLE_CLIENT_KEY="..."
-```
+```typescript
+import { createClient, BetterAuthReactAdapter } from '@neondatabase/neon-js';
 
-Get these values from your Neon dashboard:
-- **Data API URL**: Available in the Neon console under "Data API"
-- **Stack Auth credentials**: Project ID and Publishable Client Key from Neon Auth setup
-
-**3. Update Client Initialization**
-
-Update your client configuration to use neon-js:
-
-```diff
-- import { createClient } from '@supabase/supabase-js';
-+ import { createClient } from 'neon-js';
-
-- export const supabase = createClient(
--   import.meta.env.VITE_SUPABASE_URL,
--   import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
-- );
-+ export const supabase = createClient({
-+   url: import.meta.env.VITE_NEON_DATA_API_URL,
-+   auth: {
-+     tokenStore: 'cookie',
-+     projectId: import.meta.env.VITE_STACK_PROJECT_ID,
-+     publishableClientKey: import.meta.env.VITE_STACK_PUBLISHABLE_CLIENT_KEY,
-+   },
-+ });
-```
+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,
+  },
+});
 
-**4. Done!**
+// Use in React components
+function MyComponent() {
+  const session = client.auth.useSession();
 
-That's it! The rest of your code remains unchanged. All authentication methods (`signInWithPassword`, `signOut`, `getUser`, etc.) and database queries (`from().select()`, etc.) work exactly the same.
+  if (session.isPending) return <div>Loading...</div>;
+  if (!session.data) return <div>Not logged in</div>;
 
-### What Stays the Same
+  return <div>Hello, {session.data.user.name}</div>;
+}
+```
 
-- ✅ All authentication method signatures
-- ✅ All database query methods
-- ✅ Session management APIs
-- ✅ User management APIs
-- ✅ OAuth flows
-- ✅ Error handling patterns
+## Authentication
 
-### Real-World Example
+### Sign Up
 
-See the complete migration in this PR: [pffigueiredo/todo-guardian-pro#1](https://github.com/pffigueiredo/todo-guardian-pro/pull/1)
+```typescript
+await client.auth.signUp.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+  name: 'John Doe',
+});
+```
 
-The migration changed only:
-- 1 dependency in `package.json`
-- 3 environment variables in `.env`
-- Client initialization in `src/integrations/supabase/client.ts`
+### Sign In
 
-Everything else stayed the same!
+```typescript
+// Email & Password
+await client.auth.signIn.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
 
-## Quick Start
+// OAuth
+await client.auth.signIn.social({
+  provider: 'google',
+  callbackURL: '/dashboard',
+});
+```
+
+### Session Management
 
 ```typescript
-import { createClient } from 'neon-js';
+// Get current session
+const session = await client.auth.getSession();
 
-// Create client with Stack Auth integration
-const client = createClient({
-  url: 'https://your-api.com',
-  auth: {
-    projectId: 'your-project-id',
-    publishableClientKey: 'pk_...',
-    tokenStore: 'cookie', // or 'memory'
+// Sign out
+await client.auth.signOut();
+```
+
+### SupabaseAuthAdapter API
+
+When using `SupabaseAuthAdapter`, you get access to the Supabase-compatible API:
+
+```typescript
+// Sign up with metadata
+await client.auth.signUp({
+  email: 'user@example.com',
+  password: 'secure-password',
+  options: {
+    data: { name: 'John Doe' },
   },
 });
 
 // Sign in
 await client.auth.signInWithPassword({
   email: 'user@example.com',
-  password: 'password123',
+  password: 'secure-password',
 });
 
-// Get current session
-const { data } = await client.auth.getSession();
+// OAuth
+await client.auth.signInWithOAuth({
+  provider: 'google',
+  options: { redirectTo: '/dashboard' },
+});
+
+// Session with data wrapper
+const { data: session } = await client.auth.getSession();
+const { data: user } = await client.auth.getUser();
 
-// Make authenticated API calls (tokens injected automatically)
-const { data: items } = await client.from('items').select();
+// Auth state changes
+client.auth.onAuthStateChange((event, session) => {
+  console.log(event, session);
+});
 ```
 
-## Environment Support
+## Database Querying
+
+### SELECT Queries
 
-The SDK works in both browser and Node.js environments:
+```typescript
+// Simple select
+const { data } = await client
+  .from('users')
+  .select('id, name, email');
+
+// With filters
+const { data } = await client
+  .from('posts')
+  .select('*')
+  .eq('status', 'published')
+  .gt('views', 100)
+  .order('created_at', { ascending: false })
+  .limit(10);
+
+// Joins
+const { data } = await client
+  .from('posts')
+  .select(`
+    id,
+    title,
+    author:users(name, email)
+  `)
+  .eq('status', 'published');
+```
 
-### Browser
+### INSERT Queries
 
 ```typescript
-// Full feature support including cross-tab sync
-import { createClient } from 'neon-js';
+// 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();
+```
 
-const client = createClient({
-  url: 'https://your-api.com',
-  auth: {
-    projectId: 'your-project-id',
-    publishableClientKey: 'pk_...',
-    tokenStore: 'cookie', // Use cookies in browser
-  },
-});
+### UPDATE Queries
+
+```typescript
+const { data } = await client
+  .from('users')
+  .update({ status: 'inactive' })
+  .eq('last_login', null)
+  .select();
 ```
 
-### Node.js
+### DELETE Queries
 
 ```typescript
-// All auth methods work, cross-tab features automatically disabled
-import { createClient } from 'neon-js';
+const { data } = await client
+  .from('users')
+  .delete()
+  .eq('status', 'deleted')
+  .select();
+```
 
-const client = createClient({
-  url: 'https://your-api.com',
-  auth: {
-    projectId: 'your-project-id',
-    publishableClientKey: 'pk_...',
-    tokenStore: 'memory', // Use memory storage in Node.js
-  },
-});
+### RPC (Stored Procedures)
+
+```typescript
+const { data } = await client
+  .rpc('get_user_stats', {
+    user_id: 123,
+    start_date: '2024-01-01',
+  });
 ```
 
-### Server-Side (with secret key)
+## Configuration
+
+### Client Options
 
 ```typescript
-import { createClient } from 'neon-js';
+import { createClient } from '@neondatabase/neon-js';
 
 const client = createClient({
-  url: 'https://your-api.com',
+  // Auth configuration
   auth: {
-    projectId: 'your-project-id',
-    secretServerKey: 'sk_...', // Server key for server-side operations
-    tokenStore: 'memory',
+    url: 'https://your-auth-server.neon.tech/auth',
+  },
+
+  // Data API configuration
+  dataApi: {
+    url: 'https://your-data-api.neon.tech/rest/v1',
+    options: {
+      db: {
+        schema: 'public', // Default schema
+      },
+      global: {
+        headers: {
+          'X-Custom-Header': 'value',
+        },
+      },
+    },
   },
 });
 ```
 
-## Architecture
-
-- **NeonClient**: Unified client for Neon Auth and Data API (extends PostgrestClient)
-- **AuthClient Interface**: Supabase-compatible authentication interface for easy migration
-- **Adapter Pattern**: Pluggable authentication providers (Stack Auth included)
-- **Factory Pattern**: `createClient()` handles initialization and wiring
-- **Performance Optimized**: Session caching, automatic token injection, and retry logic
-
-## Development
-
-Install dependencies:
+### Environment Variables
 
 ```bash
-bun install
+# Auth URL
+NEON_AUTH_URL=https://your-auth-server.neon.tech/auth
+
+# Data API URL
+NEON_DATA_API_URL=https://your-data-api.neon.tech/rest/v1
 ```
 
-Run development server with watch mode:
+```typescript
+import { createClient } from '@neondatabase/neon-js';
 
-```bash
-bun dev
+const client = createClient({
+  auth: {
+    url: process.env.NEON_AUTH_URL!,
+  },
+  dataApi: {
+    url: process.env.NEON_DATA_API_URL!,
+  },
+});
 ```
 
-Build the library:
+## TypeScript
+
+Generate TypeScript types from your database schema:
 
 ```bash
-bun build
+npx neon-js gen-types --db-url "postgresql://user:pass@host/db"
 ```
 
-Run tests:
+Use generated types for full type safety:
 
-```bash
-bun test
-```
+```typescript
+import type { Database } from './types/database';
+import { createClient } from '@neondatabase/neon-js';
 
-Type check:
+const client = createClient<Database>({
+  auth: {
+    url: process.env.NEON_AUTH_URL!,
+  },
+  dataApi: {
+    url: process.env.NEON_DATA_API_URL!,
+  },
+});
 
-```bash
-bun typecheck
+// Fully typed queries!
+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
 ```
 
-## Publishing
+## CLI Tool
 
-Bump version and publish to npm:
+Generate TypeScript types from your database:
 
 ```bash
-bun release
+# 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
 ```
 
-## Project Structure
+**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`)
 
-```
-src/
-├── auth/
-│   ├── auth-interface.ts          # Core AuthClient interface
-│   ├── utils.ts                   # Shared utility functions
-│   ├── __tests__/                 # Comprehensive test suite
-│   │   ├── auth-flows.test.ts
-│   │   ├── session-management.test.ts
-│   │   ├── error-handling.test.ts
-│   │   ├── oauth.test.ts
-│   │   ├── oauth.browser.test.ts
-│   │   ├── otp.test.ts
-│   │   ├── user-management.test.ts
-│   │   ├── stack-auth-helpers.test.ts
-│   │   ├── supabase-compatibility.test.ts
-│   │   ├── msw-setup.ts
-│   │   ├── msw-handlers.ts
-│   │   └── README.md
-│   └── adapters/
-│       └── stack-auth/
-│           ├── stack-auth-adapter.ts   # Stack Auth implementation (2000+ lines)
-│           ├── stack-auth-types.ts     # Type definitions and interfaces
-│           ├── stack-auth-schemas.ts   # Zod schemas for JWT validation
-│           └── stack-auth-helpers.ts   # Helper utilities
-├── client/
-│   ├── neon-client.ts             # NeonClient class (extends PostgrestClient)
-│   ├── client-factory.ts          # createClient() factory function
-│   ├── neon-client.test.ts        # Client tests
-│   └── fetch-with-auth.ts         # Auth-aware fetch wrapper
-├── cli/
-│   ├── index.ts                   # CLI entry point (bin: neon-js)
-│   ├── commands/
-│   │   ├── gen-types.ts           # Type generation command
-│   │   └── generate-types.ts      # Core type generation logic
-│   └── utils/
-│       └── parse-duration.ts      # Duration parsing utility
-└── index.ts                        # Public exports
-```
+## Performance
 
-## CLI Tool: Generate Types
+### Session Caching
 
-The `neon-js` package includes a CLI tool for generating TypeScript types from your database schema.
+Sessions are cached in memory with intelligent TTL:
+- **Cold start:** ~200ms (single network request)
+- **Cached reads:** <1ms (in-memory, no I/O)
+- **Cache TTL:** 60 seconds or until JWT expires
+- **Smart expiration:** Automatic based on JWT claims
 
-### Installation
+### Request Deduplication
 
-No installation required! Use via npx:
+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
 
-```bash
-npx neon-js gen-types --db-url "postgresql://..."
-```
+## Environment Compatibility
 
-### Usage
+- **Node.js** 14+ (with native fetch or polyfill)
+- **Browser** (all modern browsers)
+- **Edge Runtime** (Vercel, Cloudflare Workers, Deno, etc.)
+- **Bun** (native support)
 
-```bash
-npx neon-js gen-types --db-url <url> [flags]
+## Error Handling
+
+```typescript
+import { AuthError } from '@neondatabase/neon-js';
+
+// Auth errors (SupabaseAuthAdapter)
+try {
+  await client.auth.signInWithPassword({ email, password });
+} catch (error) {
+  if (error instanceof AuthError) {
+    console.error('Auth error:', error.message);
+  }
+}
+
+// Database errors
+const { data, error } = await client.from('users').select();
+if (error) {
+  console.error('Database error:', error.message);
+}
 ```
 
-#### Required Flags
+## Examples
 
-- `--db-url <url>` - Database connection string
+### Next.js App Router
 
-#### Optional Flags
+```typescript
+// app/lib/neon.ts
+import { createClient } from '@neondatabase/neon-js';
 
-- `--output <path>`, `-o <path>` - Output file path (default: `database.types.ts`)
-- `--schema <name>`, `-s <name>` - Schema to include (can be used multiple times, default: `public`)
-- `--postgrest-v9-compat` - Disable one-to-one relationship detection
-- `--query-timeout <duration>` - Query timeout (default: `15s`, format: `30s`, `1m`, `90s`)
+export const neon = createClient({
+  auth: {
+    url: process.env.NEON_AUTH_URL!,
+  },
+  dataApi: {
+    url: process.env.NEON_DATA_API_URL!,
+  },
+});
 
-#### Examples
+// app/api/users/route.ts
+import { neon } from '@/lib/neon';
 
-```bash
-# Basic usage
-npx neon-js gen-types --db-url "postgresql://user:pass@host:5432/db"
+export async function GET() {
+  const { data: users } = await neon.from('users').select('*');
+  return Response.json(users);
+}
+```
 
-# Custom output path
-npx neon-js gen-types --db-url "postgresql://..." --output src/types/db.ts
+### React Hook with BetterAuthReactAdapter
 
-# Multiple schemas
-npx neon-js gen-types --db-url "postgresql://..." -s public -s auth
+```typescript
+import { createClient, BetterAuthReactAdapter } from '@neondatabase/neon-js';
 
-# PostgREST v9 compatibility
-npx neon-js gen-types --db-url "postgresql://..." --postgrest-v9-compat
+const client = createClient({
+  auth: {
+    adapter: BetterAuthReactAdapter(),
+    url: process.env.NEXT_PUBLIC_NEON_AUTH_URL!,
+  },
+  dataApi: {
+    url: process.env.NEXT_PUBLIC_NEON_DATA_API_URL!,
+  },
+});
 
-# Custom timeout
-npx neon-js gen-types --db-url "postgresql://..." --query-timeout 30s
+export function useAuth() {
+  const session = client.auth.useSession();
+
+  return {
+    user: session.data?.user ?? null,
+    isPending: session.isPending,
+    signIn: (email: string, password: string) =>
+      client.auth.signIn.email({ email, password }),
+    signOut: () => client.auth.signOut(),
+  };
+}
 ```
 
-## Authentication Methods
+## Related Packages
 
-The SDK supports the following authentication methods via the Stack Auth adapter:
+This package combines two underlying packages:
 
-### Fully Supported Methods
-- **Email/Password**: `signUp()`, `signInWithPassword()`
-- **OAuth**: `signInWithOAuth()` (supports all Stack Auth OAuth providers)
-- **Magic Link**: `signInWithOtp()`, `verifyOtp()` (email-based passwordless authentication)
-- **Session Management**: `getSession()`, `refreshSession()`, `setSession()`, `signOut()`
-- **User Management**: `getUser()`, `updateUser()`, `getClaims()`, `getUserIdentities()`
-- **Identity Linking**: `linkIdentity()`, `unlinkIdentity()`
-- **Password Reset**: `resetPasswordForEmail()`, `resend()`
-- **OAuth Callback**: `exchangeCodeForSession()`
-- **State Monitoring**: `onAuthStateChange()`
+- [`@neondatabase/neon-auth`](../neon-auth) - Authentication adapters (can be used standalone)
+- [`@neondatabase/postgrest-js`](../postgrest-js) - PostgreSQL client (can be used standalone)
 
-### Unsupported Methods (Return Detailed Errors)
-- **OIDC ID Token**: `signInWithIdToken()` - Stack Auth uses OAuth redirects only
-- **SAML SSO**: `signInWithSSO()` - Stack Auth only supports OAuth social providers
-- **Web3/Crypto**: `signInWithWeb3()` - Stack Auth does not support blockchain authentication
-- **Anonymous**: `signInAnonymously()` - Use OAuth or email/password instead
+## Migration from Previous Version
 
-For unsupported methods, the adapter returns comprehensive error messages explaining the limitation and suggesting alternatives.
+If you're migrating from the old API that used `dataApiUrl` and `authUrl` directly:
 
-## Performance
+```typescript
+// Before (old API)
+const client = createClient({
+  dataApiUrl: 'https://data-api.example.com/rest/v1',
+  authUrl: 'https://auth.example.com',
+});
+
+// After (new API with adapters)
+import { createClient, SupabaseAuthAdapter } from '@neondatabase/neon-js';
+
+const client = createClient({
+  auth: {
+    adapter: SupabaseAuthAdapter(),
+    url: 'https://auth.example.com',
+  },
+  dataApi: {
+    url: 'https://data-api.example.com/rest/v1',
+  },
+});
+```
 
-The Stack Auth adapter is optimized for performance:
+## Resources
 
-- **Cached `getSession()`**: <5ms (reads from Stack Auth internal cache, no I/O)
-- **First `getSession()` after reload**: <50ms (Stack Auth reads from tokenStore)
-- **Token refresh**: <200ms (network call to Stack Auth, happens automatically)
+- [Neon Documentation](https://neon.tech/docs)
+- [Neon Auth Documentation](https://neon.tech/docs/neon-auth)
+- [Better Auth Documentation](https://www.better-auth.com/docs)
+- [PostgREST Documentation](https://postgrest.org)
 
-## License
+## Support
 
-MIT
+- [GitHub Issues](https://github.com/neondatabase/neon-js/issues)
+- [Neon Community Discord](https://discord.gg/H24eC2UN)
 
-## Links
+## License
 
-- [Stack Auth Documentation](https://docs.stack-auth.com/)
-- [Supabase Auth Documentation](https://supabase.com/docs/guides/auth)
-- [PostgrestClient Documentation](https://github.com/supabase/postgrest-js)
+Apache-2.0