@neondatabase/neon-js 0.1.0-beta.9 → 0.2.0-beta.1

package/llms.txt

@@ -0,0 +1,416 @@
+# @neondatabase/neon-js
+
+> The official TypeScript SDK for Neon - unified client combining authentication and PostgreSQL database querying with automatic token management.
+
+`@neondatabase/neon-js` brings together Neon Auth and Neon Data API in a single client. It provides a familiar interface for authentication and type-safe database queries with PostgREST.
+
+## When to Use This Package
+
+| Use Case | Package |
+|----------|---------|
+| Auth + Database (most apps) | `@neondatabase/neon-js` |
+| Auth only (no database) | `@neondatabase/auth` |
+| Database only (external auth) | `@neondatabase/postgrest-js` |
+| Pre-built UI components | Add `@neondatabase/auth-ui` |
+
+## Installation
+
+```bash
+npm install @neondatabase/neon-js
+```
+
+## Environment Variables
+
+```bash
+# React/Vite
+VITE_NEON_AUTH_URL=https://your-project.neon.tech/auth
+VITE_NEON_DATA_API_URL=https://your-project.neon.tech/rest/v1
+
+# Next.js
+NEON_AUTH_BASE_URL=https://your-project.neon.tech
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@neondatabase/neon-js';
+
+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');
+```
+
+## Authentication
+
+### Sign Up & Sign In
+
+```typescript
+// Sign up
+await client.auth.signUp.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+  name: 'John Doe',
+});
+
+// Sign in with email
+await client.auth.signIn.email({
+  email: 'user@example.com',
+  password: 'secure-password',
+});
+
+// Sign in with OAuth
+await client.auth.signIn.social({
+  provider: 'google',
+  callbackURL: '/dashboard',
+});
+
+// Get session
+const session = await client.auth.getSession();
+
+// Sign out
+await client.auth.signOut();
+```
+
+### Adapters
+
+**Critical:** Adapters are factory functions - must call with `()`.
+
+```typescript
+// SupabaseAuthAdapter - Supabase-compatible API
+import { createClient, SupabaseAuthAdapter } from '@neondatabase/neon-js';
+
+const client = createClient<Database>({
+  auth: {
+    adapter: SupabaseAuthAdapter(), // Must call with ()
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+await client.auth.signInWithPassword({ email, password });
+const { data: session } = await client.auth.getSession();
+```
+
+```typescript
+// BetterAuthVanillaAdapter - Direct Better Auth API
+import { createClient, BetterAuthVanillaAdapter } from '@neondatabase/neon-js';
+
+const client = createClient<Database>({
+  auth: {
+    adapter: BetterAuthVanillaAdapter(),
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+  },
+  dataApi: {
+    url: import.meta.env.VITE_NEON_DATA_API_URL,
+  },
+});
+
+await client.auth.signIn.email({ email, password });
+const session = await client.auth.getSession();
+```
+
+```typescript
+// BetterAuthReactAdapter - React hooks (MUST use subpath import)
+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,
+  },
+});
+
+function MyComponent() {
+  const session = client.auth.useSession();
+  if (session.isPending) return <div>Loading...</div>;
+  return <div>Hello, {session.data?.user.name}</div>;
+}
+```
+
+### Anonymous Access
+
+Enable RLS-based data access for unauthenticated users:
+
+```typescript
+const client = createClient<Database>({
+  auth: {
+    url: import.meta.env.VITE_NEON_AUTH_URL,
+    allowAnonymous: true, // Enable anonymous data access via RLS
+  },
+  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();
+```
+
+**Required SQL setup:**
+
+```sql
+-- Enable RLS on table
+ALTER TABLE public.public_items ENABLE ROW LEVEL SECURITY;
+
+-- Allow anonymous read access
+CREATE POLICY "anonymous_read" ON public.public_items
+  FOR SELECT TO anonymous USING (true);
+
+-- Grant permissions to roles
+GRANT SELECT ON public.public_items TO anonymous;
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.public_items TO authenticated;
+```
+
+## Next.js Integration
+
+See [@neondatabase/auth/NEXT-JS.md](https://github.com/neondatabase/neon-js/blob/main/packages/auth/NEXT-JS.md) for full guide.
+
+**Environment variables:**
+
+```bash
+NEON_AUTH_BASE_URL=https://your-project.neon.tech
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+```
+
+**Quick setup:**
+
+```typescript
+// lib/auth/server.ts - Unified server instance
+import { createNeonAuth } from '@neondatabase/neon-js/auth/next/server';
+
+export const auth = createNeonAuth({
+  baseUrl: process.env.NEON_AUTH_BASE_URL!,
+  cookies: {
+    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+    sessionDataTtl: 300,          // Optional: session data cache TTL in seconds (default: 300 = 5 min)
+    domain: '.example.com',       // Optional: for cross-subdomain cookies
+  },
+});
+
+// app/api/auth/[...path]/route.ts - API handler
+import { auth } from '@/lib/auth/server';
+export const { GET, POST } = auth.handler();
+
+// middleware.ts - Route protection
+import { auth } from '@/lib/auth/server';
+export default auth.middleware({ loginUrl: '/auth/sign-in' });
+
+// lib/auth/client.ts - Client-side auth
+"use client"
+import { createAuthClient } from '@neondatabase/neon-js/auth/next';
+export const authClient = createAuthClient();
+
+// Server Components
+import { auth } from '@/lib/auth/server';
+// Server components using `auth` methods must be rendered dynamically
+export const dynamic = 'force-dynamic';
+const { data: session } = await auth.getSession();
+
+// Server Actions
+import { auth } from '@/lib/auth/server';
+await auth.signIn.email({ email, password });
+```
+
+## Database Querying
+
+### SELECT
+
+```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');
+```
+
+### INSERT
+
+```typescript
+// Single row
+const { data } = await client
+  .from('users')
+  .insert({ name: 'Alice', email: 'alice@example.com' })
+  .select();
+
+// Multiple rows
+const { data } = await client
+  .from('users')
+  .insert([
+    { name: 'Bob', email: 'bob@example.com' },
+    { name: 'Carol', email: 'carol@example.com' },
+  ])
+  .select();
+```
+
+### UPDATE
+
+```typescript
+const { data } = await client
+  .from('users')
+  .update({ status: 'inactive' })
+  .eq('last_login', null)
+  .select();
+```
+
+### DELETE
+
+```typescript
+const { data } = await client
+  .from('users')
+  .delete()
+  .eq('status', 'deleted')
+  .select();
+```
+
+### RPC (Stored Procedures)
+
+```typescript
+const { data } = await client.rpc('get_user_stats', {
+  user_id: 123,
+  start_date: '2024-01-01',
+});
+```
+
+## Error Handling
+
+```typescript
+import { AuthRequiredError } from '@neondatabase/neon-js';
+
+try {
+  const { data } = await client.from('posts').select();
+} catch (error) {
+  if (error instanceof AuthRequiredError) {
+    // User not authenticated - redirect to login
+    window.location.href = '/login';
+  }
+  // Handle PostgREST errors
+  if (error.code === 'PGRST301') {
+    // Row-level security violation - check RLS policies
+  }
+  if (error.code === '42501') {
+    // Permission denied - check GRANT statements
+  }
+}
+```
+
+## TypeScript
+
+Generate types from your database schema:
+
+```bash
+npx @neondatabase/neon-js gen-types --db-url "postgresql://user:pass@host/db"
+```
+
+Use generated types:
+
+```typescript
+import type { Database } from './types/database';
+
+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')
+  .select('id, name, email')
+  .eq('status', 'active');
+```
+
+## Configuration
+
+```typescript
+const client = createClient({
+  auth: {
+    url: 'https://your-auth-server.neon.tech/auth',
+    allowAnonymous: true,
+  },
+  dataApi: {
+    url: 'https://your-data-api.neon.tech/rest/v1',
+    options: {
+      db: { schema: 'public' },
+      global: { headers: { 'X-Custom-Header': 'value' } },
+    },
+  },
+});
+```
+
+## CSS for UI Components
+
+```css
+/* Without Tailwind - pre-built bundle (~47KB) */
+@import '@neondatabase/neon-js/ui/css';
+
+/* With Tailwind CSS v4 - theme tokens only (~2KB) */
+@import 'tailwindcss';
+@import '@neondatabase/neon-js/ui/tailwind';
+```
+
+**Rule:** Never import both - causes duplicate styles.
+
+## Critical Rules
+
+1. **Adapters are factories** - Call them: `SupabaseAuthAdapter()` not `SupabaseAuthAdapter`
+2. **React adapter import path** - Must use subpath: `@neondatabase/neon-js/auth/react/adapters`
+3. **CSS choice** - Pick ONE: `/ui/css` OR `/ui/tailwind`, never both
+4. **Anonymous access requires RLS** - Must configure database policies and grants
+5. **Type generation** - Run CLI after schema changes to keep types in sync
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `AuthRequiredError` | No session when querying | Sign in first or enable `allowAnonymous` |
+| `permission denied for table` | RLS blocking access | Add RLS policy + GRANT for role |
+| `adapter is not a function` | Missing `()` on adapter | Use `SupabaseAuthAdapter()` not `SupabaseAuthAdapter` |
+| OAuth popup blocked | Browser blocking popup | User must allow popups for domain |
+| `PGRST301` | JWT expired or invalid | Session expired - re-authenticate |
+| Cross-tab sync not working | Node.js environment | BroadcastChannel is browser-only feature |
+| Session always null | Cookies blocked | Check browser settings, try non-incognito |
+
+## Optional
+
+- [CLI Tool](https://github.com/neondatabase/neon-js/tree/main/packages/neon-js#cli-tool): Generate TypeScript types from database
+- [PostgREST Documentation](https://postgrest.org): Query syntax reference
+- [Better Auth Documentation](https://www.better-auth.com/docs): Authentication library docs
+- [Next.js Integration Guide](https://github.com/neondatabase/neon-js/blob/main/packages/auth/NEXT-JS.md): Full Next.js setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neondatabase/neon-js",
-  "version": "0.1.0-beta.9",
+  "version": "0.2.0-beta.1",
   "description": "TypeScript SDK for Neon Auth and Data API - authentication and PostgreSQL querying",
   "type": "module",
   "license": "Apache-2.0",
@@ -18,13 +18,13 @@
     "supabase",
     "data-api"
   ],
-  "homepage": "https://github.com/neondatabase-labs/neon-js/tree/main/packages/neon-js#readme",
+  "homepage": "https://github.com/neondatabase/neon-js/tree/main/packages/neon-js#readme",
   "bugs": {
-    "url": "https://github.com/neondatabase-labs/neon-js/issues"
+    "url": "https://github.com/neondatabase/neon-js/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/neondatabase-labs/neon-js.git",
+    "url": "git+https://github.com/neondatabase/neon-js.git",
     "directory": "packages/neon-js"
   },
   "funding": {
@@ -83,6 +83,10 @@
       "types": "./dist/auth/next/index.d.mts",
       "default": "./dist/auth/next/index.mjs"
     },
+    "./auth/next/server": {
+      "types": "./dist/auth/next/server/index.d.mts",
+      "default": "./dist/auth/next/server/index.mjs"
+    },
     "./ui/css": {
       "types": "./dist/ui/css.d.ts",
       "default": "./dist/ui/css.css"
@@ -92,7 +96,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"
@@ -102,9 +107,9 @@
     "dev": "tsdown --watch",
     "test": "vitest",
     "test:node": "node --run test",
-    "test:ci": "vitest run",
+    "test:ci": "vitest run --typecheck --passWithNoTests",
     "typecheck": "tsc --noEmit",
-    "test:types": "tsc --noEmit",
+    "test:types": "vitest --typecheck.only --run",
     "release": "bun run build && bumpp --tag 'neon-js-v%s' && bun publish --tag latest",
     "lint": "eslint .",
     "clean": "rm -rf node_modules dist"
@@ -113,8 +118,8 @@
     "msw": "2.6.8"
   },
   "dependencies": {
-    "@neondatabase/postgrest-js": "0.1.0-alpha.1",
-    "@neondatabase/auth": "0.1.0-beta.9",
+    "@neondatabase/auth": "0.2.0-beta.1",
+    "@neondatabase/postgrest-js": "0.1.0-alpha.2",
     "@supabase/postgres-meta": "0.93.1",
     "meow": "14.0.0",
     "zod": "4.1.12"