@neon/neon-js 0.0.0 → 0.10.0

package/dist/supabase/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/supabase/index.ts"],"sourcesContent":["import {\n\tSupabaseAuthAdapter,\n\ttype SupabaseAuthAdapterInstance,\n\ttype SupabaseAuthAdapterOptions,\n} from \"@neon/auth/vanilla/adapters\";\nimport {\n\ttype CreateClientDataApiConfig,\n\ttype CreateClientResult,\n\tcreateClientImpl,\n} from \"../client/client-factory\";\nimport type { DeriveNeonUrls } from \"../client/derive-urls\";\nimport type { DefaultSchemaName, NeonClient } from \"../client/neon-client\";\n\n/**\n * `url` and `allowAnonymous` configure the client; every other key is forwarded to\n * `SupabaseAuthAdapter(...)`, e.g. `fetchOptions.headers.Cookie` to forward a request\n * cookie from a server.\n */\ntype SupabaseAuthConfig = SupabaseAuthAdapterOptions & {\n\t/** The auth service URL */\n\turl: string;\n\t/** Fall back to an anonymous token when there is no user session. */\n\tallowAnonymous?: boolean;\n};\n\ntype SupabaseDataApiConfig<SchemaName> = CreateClientDataApiConfig<\n\tSchemaName,\n\tSupabaseAuthAdapterInstance\n>;\n\n/** Configuration for the Supabase-compatible `createClient`. */\nexport type CreateSupabaseClientConfig<SchemaName> = {\n\tauth: SupabaseAuthConfig;\n\tdataApi: SupabaseDataApiConfig<SchemaName>;\n};\n\n/** Per-call overrides accepted alongside a single base URL. */\nexport type CreateSupabaseClientStringOptions<SchemaName> = {\n\tauth?: Partial<SupabaseAuthConfig>;\n\tdataApi?: Partial<SupabaseDataApiConfig<SchemaName>>;\n\tderiveUrls?: DeriveNeonUrls;\n};\n\n/**\n * `createClient` with the auth adapter fixed to `SupabaseAuthAdapter`, so `client.auth`\n * has the Supabase-compatible API (`signInWithPassword`, `onAuthStateChange`, ...).\n *\n * @example\n * ```typescript\n * import { createClient } from '@neon/neon-js/supabase';\n *\n * const client = createClient({\n *   auth: { url: 'https://auth.example.com' },\n *   dataApi: { url: 'https://data-api.example.com/rest/v1' },\n * });\n *\n * await client.auth.signInWithPassword({ email, password });\n * const { data: items } = await client.from('items').select();\n * ```\n */\n// biome-ignore lint/suspicious/noExplicitAny: `any` is the default so an unspecified Database generic stays compatible with the upstream PostgrestClient's untyped schema.\nexport function createClient<Database = any>(\n\tconfig: CreateSupabaseClientConfig<DefaultSchemaName<Database>>,\n): CreateClientResult<Database, SupabaseAuthAdapterInstance>;\n// biome-ignore lint/suspicious/noExplicitAny: `any` is the default so an unspecified Database generic stays compatible with the upstream PostgrestClient's untyped schema.\nexport function createClient<Database = any>(\n\tbaseUrl: string,\n\toptions?: CreateSupabaseClientStringOptions<DefaultSchemaName<Database>>,\n): CreateClientResult<Database, SupabaseAuthAdapterInstance>;\nexport function createClient<\n\t// biome-ignore lint/suspicious/noExplicitAny: `any` is the default so an unspecified Database generic stays compatible with the upstream PostgrestClient's untyped schema.\n\tDatabase = any,\n\tSchemaName extends string & keyof Database = DefaultSchemaName<Database>,\n>(\n\targ1: string | CreateSupabaseClientConfig<SchemaName>,\n\targ2?: CreateSupabaseClientStringOptions<SchemaName>,\n): NeonClient<Database, SchemaName, SupabaseAuthAdapterInstance> {\n\t// An `auth` block is always present here, so the implementation never takes its\n\t// external-auth branch and the result always carries `.auth`.\n\tconst client =\n\t\ttypeof arg1 === \"string\"\n\t\t\t? createClientImpl<\n\t\t\t\t\tDatabase,\n\t\t\t\t\tSchemaName,\n\t\t\t\t\tSupabaseAuthAdapterInstance\n\t\t\t\t>(arg1, { ...arg2, auth: withAdapter(arg2?.auth) })\n\t\t\t: createClientImpl<\n\t\t\t\t\tDatabase,\n\t\t\t\t\tSchemaName,\n\t\t\t\t\tSupabaseAuthAdapterInstance\n\t\t\t\t>({\n\t\t\t\t\t...arg1,\n\t\t\t\t\tauth: withAdapter(arg1.auth),\n\t\t\t\t});\n\treturn client as NeonClient<\n\t\tDatabase,\n\t\tSchemaName,\n\t\tSupabaseAuthAdapterInstance\n\t>;\n}\n\nfunction withAdapter<T extends Partial<SupabaseAuthConfig>>(\n\tauth: T | undefined,\n) {\n\tconst { url, allowAnonymous, ...adapterOptions } = auth ?? {};\n\treturn {\n\t\turl,\n\t\tallowAnonymous,\n\t\tadapter: SupabaseAuthAdapter(adapterOptions),\n\t} as Omit<T, keyof SupabaseAuthAdapterOptions> & {\n\t\tadapter: ReturnType<typeof SupabaseAuthAdapter>;\n\t};\n}\n"],"mappings":";;;AAqEA,SAAgB,aAKf,MACA,MACgE;CAkBhE,OAdC,OAAO,SAAS,WACb,iBAIC,MAAM;EAAE,GAAG;EAAM,MAAM,YAAY,MAAM,IAAI;CAAE,CAAC,IACjD,iBAIC;EACD,GAAG;EACH,MAAM,YAAY,KAAK,IAAI;CAC5B,CAAC;AAML;AAEA,SAAS,YACR,MACC;CACD,MAAM,EAAE,KAAK,gBAAgB,GAAG,mBAAmB,QAAQ,CAAC;CAC5D,OAAO;EACN;EACA;EACA,SAAS,oBAAoB,cAAc;CAC5C;AAGD"}

package/llms.txt

@@ -0,0 +1,397 @@
+# @neon/neon-js
+
+> The official TypeScript SDK for Neon - unified client combining authentication and PostgreSQL database querying with automatic token management.
+
+`@neon/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) | `@neon/neon-js` |
+| Auth only (no database) | `@neon/auth` |
+| Database only (external auth) | `@neon/postgrest-js` |
+
+## Installation
+
+```bash
+npm install @neon/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 '@neon/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
+// Supabase-compatible API: import createClient from the /supabase subpath (no adapter option)
+import { createClient } from '@neon/neon-js/supabase';
+
+const client = createClient<Database>({
+  auth: {
+    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();
+
+// Supabase adapter options (fetchOptions, sessionOptions, ...) go on the auth config, e.g. to forward a request cookie on a server:
+// auth: { url, fetchOptions: { headers: { Cookie: request.headers.get('cookie') ?? '' } } }
+```
+
+```typescript
+// BetterAuthVanillaAdapter - Direct Better Auth API
+import { createClient, BetterAuthVanillaAdapter } from '@neon/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 '@neon/neon-js';
+import { BetterAuthReactAdapter } from '@neon/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 [@neon/auth/NEXT-JS.md](https://github.com/neondatabase/neon-pkgs/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 '@neon/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 '@neon/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 '@neon/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
+
+Pass a `Database` type generated from your schema to `createClient`:
+
+```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' } },
+    },
+  },
+});
+```
+
+## Critical Rules
+
+1. **Adapters are factories** - Call them: `BetterAuthVanillaAdapter()` not `BetterAuthVanillaAdapter`
+2. **Supabase API lives at `/supabase`** - `import { createClient } from '@neon/neon-js/supabase'`; the main `createClient` does not accept `SupabaseAuthAdapter`
+3. **React adapter import path** - Must use subpath: `@neon/neon-js/auth/react/adapters`
+4. **Anonymous access requires RLS** - Must configure database policies and grants
+5. **Type generation** - Regenerate your `Database` type 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 `BetterAuthVanillaAdapter()` not `BetterAuthVanillaAdapter` |
+| 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
+
+- [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-pkgs/blob/main/packages/auth/NEXT-JS.md): Full Next.js setup

package/package.json

@@ -1,10 +1,114 @@
 {
   "name": "@neon/neon-js",
-  "version": "0.0.0",
+  "version": "0.10.0",
+  "description": "TypeScript SDK for Neon Auth and Data API - authentication and PostgreSQL querying",
+  "keywords": [
+    "neon",
+    "neondb",
+    "postgresql",
+    "postgres",
+    "database",
+    "authentication",
+    "auth",
+    "typescript",
+    "sdk",
+    "better-auth",
+    "supabase",
+    "data-api"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neondatabase/neon-pkgs.git",
+    "directory": "packages/neon-js"
+  },
+  "homepage": "https://github.com/neondatabase/neon-pkgs/tree/main/packages/neon-js#readme",
+  "bugs": {
+    "url": "https://github.com/neondatabase/neon-pkgs/issues"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Neon",
+    "url": "https://neon.com"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./supabase": {
+      "types": "./dist/supabase/index.d.ts",
+      "default": "./dist/supabase/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./auth/types": {
+      "types": "./dist/auth/types/index.d.ts",
+      "default": "./dist/auth/types/index.js"
+    },
+    "./auth/react": {
+      "types": "./dist/auth/react/index.d.ts",
+      "default": "./dist/auth/react/index.js"
+    },
+    "./auth/react/adapters": {
+      "types": "./dist/auth/react/adapters/index.d.ts",
+      "default": "./dist/auth/react/adapters/index.js"
+    },
+    "./auth/vanilla": {
+      "types": "./dist/auth/vanilla/index.d.ts",
+      "default": "./dist/auth/vanilla/index.js"
+    },
+    "./auth/vanilla/adapters": {
+      "types": "./dist/auth/vanilla/adapters/index.d.ts",
+      "default": "./dist/auth/vanilla/adapters/index.js"
+    },
+    "./auth/next": {
+      "types": "./dist/auth/next/index.d.ts",
+      "default": "./dist/auth/next/index.js"
+    },
+    "./auth/next/server": {
+      "types": "./dist/auth/next/server/index.d.ts",
+      "default": "./dist/auth/next/server/index.js"
+    },
+    "./auth/server": {
+      "types": "./dist/auth/server/index.d.ts",
+      "default": "./dist/auth/server/index.js"
+    }
+  },
   "files": [
-    "README.md"
+    "README.md",
+    "dist/",
+    "package.json",
+    "llms.txt"
   ],
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "@vitest/coverage-v8": "^3.0.9",
+    "tsdown": "^0.14.1",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.9",
+    "@neon-internals/internal": "0.0.0"
+  },
+  "dependencies": {
+    "@neon/auth": "0.8.0",
+    "@neon/postgrest-js": "0.3.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
   "publishConfig": {
-    "access": "public"
+    "provenance": false
+  },
+  "scripts": {
+    "build": "tsc --noEmit && tsdown",
+    "test": "vitest",
+    "test:node": "node --run test",
+    "test:ci": "vitest run --typecheck --passWithNoTests",
+    "tsc": "tsc"
   }
-}
+}