@netlify/identity 0.1.1 → 0.3.0-alpha.1

package/README.md

@@ -4,13 +4,38 @@ A lightweight, no-config headless authentication library for projects using Netl
 
 > **Status:** Beta. The API may change before 1.0.
 
-For a pre-built login widget, see [netlify-identity-widget](https://github.com/netlify/netlify-identity-widget).
-
 **Prerequisites:**
 
 - [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/) must be enabled on your Netlify project
 - For local development, use [`netlify dev`](https://docs.netlify.com/cli/local-development/) so the Identity endpoint is available
 
+### How this library relates to other Netlify auth packages
+
+| Package                                                                         | What it is                                     | When to use it                                                                             |
+| ------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **`@netlify/identity`** (this library)                                          | Headless TypeScript API for browser and server | You want full control over your auth UI and need server-side auth (SSR, Netlify Functions) |
+| [`netlify-identity-widget`](https://github.com/netlify/netlify-identity-widget) | Pre-built login/signup modal (HTML + CSS)      | You want a drop-in UI component with no custom design                                      |
+| [`gotrue-js`](https://github.com/netlify/gotrue-js)                             | Low-level GoTrue HTTP client (browser only)    | You're building your own auth wrapper and need direct API access                           |
+
+This library wraps `gotrue-js` in the browser and calls the GoTrue HTTP API directly on the server. It provides a unified API that works in both contexts, handles cookie management, and normalizes the user object. You do not need to install `gotrue-js` or the widget separately.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [API](#api)
+  - [Functions](#functions) -- `getUser`, `login`, `signup`, `logout`, `oauthLogin`, `handleAuthCallback`, `onAuthChange`, `hydrateSession`, and more
+  - [Types](#types) -- `User`, `AuthEvent`, `CallbackResult`, `Settings`, etc.
+  - [Errors](#errors) -- `AuthError`, `MissingIdentityError`
+- [Framework integration](#framework-integration) -- Next.js, Remix, TanStack Start, Astro, SvelteKit
+- [Guides](#guides)
+  - [React `useAuth` hook](#react-useauth-hook)
+  - [Listening for auth changes](#listening-for-auth-changes)
+  - [OAuth login](#oauth-login)
+  - [Password recovery](#password-recovery)
+  - [Invite acceptance](#invite-acceptance)
+  - [Session lifetime](#session-lifetime)
+
 ## Installation
 
 ```bash
@@ -19,18 +44,20 @@ npm install @netlify/identity
 
 ## Quick start
 
-### Browser
+### Log in (browser)
 
 ```ts
-import { getUser } from '@netlify/identity'
+import { login, getUser } from '@netlify/identity'
 
-const user = getUser()
-if (user) {
-  console.log(`Hello, ${user.name}`)
-}
+// Log in
+const user = await login('jane@example.com', 'password123')
+console.log(`Hello, ${user.name}`)
+
+// Later, check auth state synchronously
+const currentUser = getUser()
 ```
 
-### Netlify Function
+### Protect a Netlify Function
 
 ```ts
 import { getUser } from '@netlify/identity'
@@ -43,7 +70,7 @@ export default async (req: Request, context: Context) => {
 }
 ```
 
-### Edge Function
+### Protect an Edge Function
 
 ```ts
 import { getUser } from '@netlify/identity'
@@ -66,7 +93,9 @@ export default async (req: Request, context: Context) => {
 getUser(): User | null
 ```
 
-Returns the current authenticated user, or `null` if not logged in. Synchronous, never throws.
+Returns the current authenticated user, or `null` if not logged in. Synchronous. Never throws.
+
+> **Next.js note:** Calling `getUser()` in a Server Component opts the page into [dynamic rendering](https://nextjs.org/docs/app/building-your-application/rendering/server-components#dynamic-rendering) because it reads cookies. This is expected and correct for authenticated pages. Next.js handles the internal dynamic rendering signal automatically.
 
 #### `isAuthenticated`
 
@@ -74,7 +103,7 @@ Returns the current authenticated user, or `null` if not logged in. Synchronous,
 isAuthenticated(): boolean
 ```
 
-Returns `true` if a user is currently authenticated. Equivalent to `getUser() !== null`.
+Returns `true` if a user is currently authenticated. Equivalent to `getUser() !== null`. Never throws.
 
 #### `getIdentityConfig`
 
@@ -90,7 +119,220 @@ Returns the Identity endpoint URL (and operator token on the server), or `null`
 getSettings(): Promise<Settings>
 ```
 
-Fetches your project's Identity settings (enabled providers, autoconfirm, signup disabled). Throws `MissingIdentityError` if not configured; throws `AuthError` if the endpoint is unreachable.
+Fetches your project's Identity settings (enabled providers, autoconfirm, signup disabled).
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if the endpoint is unreachable.
+
+#### `login`
+
+```ts
+login(email: string, password: string): Promise<User>
+```
+
+Logs in with email and password. Works in both browser and server contexts.
+
+In the browser, uses gotrue-js and emits a `'login'` event. On the server (Netlify Functions, Edge Functions), calls the GoTrue HTTP API directly and sets the `nf_jwt` cookie via the Netlify runtime.
+
+**Throws:** `AuthError` on invalid credentials or network failure. In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+
+#### `signup`
+
+```ts
+signup(email: string, password: string, data?: SignupData): Promise<User>
+```
+
+Creates a new account. Works in both browser and server contexts.
+
+If autoconfirm is enabled in your Identity settings, the user is logged in immediately: cookies are set and a `'login'` event is emitted. If autoconfirm is **disabled** (the default), the user receives a confirmation email and must click the link before they can log in. In that case, no cookies are set and no auth event is emitted.
+
+The optional `data` parameter sets user metadata (e.g., `{ full_name: 'Jane Doe' }`), stored in the user's `user_metadata` field.
+
+**Throws:** `AuthError` on failure (e.g., email already registered, signup disabled). In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+
+#### `logout`
+
+```ts
+logout(): Promise<void>
+```
+
+Logs out the current user and clears the session. Works in both browser and server contexts.
+
+In the browser, uses gotrue-js and emits a `'logout'` event. On the server, calls GoTrue's `/logout` endpoint with the JWT from the `nf_jwt` cookie, then deletes the cookie. Auth cookies are always cleared, even if the GoTrue call fails.
+
+**Throws:** In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
+
+#### `oauthLogin`
+
+```ts
+oauthLogin(provider: string): never
+```
+
+Redirects to an OAuth provider. The page navigates away, so this function never returns normally. Browser only.
+
+The `provider` argument should be one of the `AuthProvider` values: `'google'`, `'github'`, `'gitlab'`, `'bitbucket'`, `'facebook'`, or `'saml'`.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if called on the server.
+
+#### `handleAuthCallback`
+
+```ts
+handleAuthCallback(): Promise<CallbackResult | null>
+```
+
+Processes the URL hash after an OAuth redirect, email confirmation, password recovery, invite acceptance, or email change. Call on page load. Returns `null` if the hash contains no auth parameters. Browser only.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if token exchange fails.
+
+#### `onAuthChange`
+
+```ts
+onAuthChange(callback: AuthCallback): () => void
+```
+
+Subscribes to auth state changes (login, logout, token refresh, user updates, and recovery). Returns an unsubscribe function. Also fires on cross-tab session changes. No-op on the server. The `'recovery'` event fires when `handleAuthCallback()` processes a password recovery token; listen for it to redirect users to a password reset form.
+
+#### `hydrateSession`
+
+```ts
+hydrateSession(): Promise<User | null>
+```
+
+Bootstraps the browser-side gotrue-js session from server-set auth cookies (`nf_jwt`, `nf_refresh`). Returns the hydrated `User`, or `null` if no auth cookies are present. No-op on the server.
+
+**When to use:** After a server-side login (e.g., via a Netlify Function or Server Action), the `nf_jwt` cookie is set but gotrue-js has no browser session yet. `getUser()` works immediately (it decodes the cookie), but account operations like `updateUser()` or `verifyEmailChange()` require a live gotrue-js session. Call `hydrateSession()` once on page load to bridge this gap.
+
+If a gotrue-js session already exists (e.g., from a browser-side login), this is a no-op and returns the existing user.
+
+```ts
+import { hydrateSession, updateUser } from '@netlify/identity'
+
+// On page load, hydrate the session from server-set cookies
+await hydrateSession()
+
+// Now browser account operations work
+await updateUser({ data: { full_name: 'Jane Doe' } })
+```
+
+#### `requestPasswordRecovery`
+
+```ts
+requestPasswordRecovery(email: string): Promise<void>
+```
+
+Sends a password recovery email to the given address.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` on network failure.
+
+#### `confirmEmail`
+
+```ts
+confirmEmail(token: string): Promise<User>
+```
+
+Confirms an email address using the token from a confirmation email. Logs the user in on success.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if the token is invalid or expired.
+
+#### `acceptInvite`
+
+```ts
+acceptInvite(token: string, password: string): Promise<User>
+```
+
+Accepts an invite token and sets a password for the new account. Logs the user in on success.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if the token is invalid or expired.
+
+#### `verifyEmailChange`
+
+```ts
+verifyEmailChange(token: string): Promise<User>
+```
+
+Verifies an email change using the token from a verification email.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if the token is invalid.
+
+#### `recoverPassword`
+
+```ts
+recoverPassword(token: string, newPassword: string): Promise<User>
+```
+
+Redeems a recovery token and sets a new password. Logs the user in on success.
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if the token is invalid or expired.
+
+#### `updateUser`
+
+```ts
+updateUser(updates: UserUpdates): Promise<User>
+```
+
+Updates the current user's metadata or credentials. Requires an active session. Pass `email` or `password` to change credentials, or `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
+
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if no user is logged in, or the update fails.
+
+### Admin Operations
+
+The `admin` namespace provides user management functions for administrators. These work in two contexts:
+
+- **Server:** Uses the operator token from the Netlify runtime for full admin access. No logged-in user required.
+- **Browser:** Uses the logged-in user's JWT via gotrue-js. The user must have an admin role.
+
+```ts
+import { admin } from '@netlify/identity'
+```
+
+#### `admin.listUsers`
+
+```ts
+admin.listUsers(options?: { page?: number; perPage?: number }): Promise<User[]>
+```
+
+Lists all users. Pagination options are supported on the server; they are ignored in the browser (gotrue-js does not support pagination for this method).
+
+**Throws:** `AuthError` if the operator token is missing (server) or no user is logged in (browser).
+
+#### `admin.getUser`
+
+```ts
+admin.getUser(userId: string): Promise<User>
+```
+
+Gets a single user by ID.
+
+**Throws:** `AuthError` if the user is not found, the operator token is missing (server), or no user is logged in (browser).
+
+#### `admin.createUser`
+
+```ts
+admin.createUser(params: { email: string; password: string; data?: Record<string, unknown> }): Promise<User>
+```
+
+Creates a new user. The user is auto-confirmed. Optional `data` is spread into the request body as additional attributes.
+
+**Throws:** `AuthError` on failure (e.g., email already exists).
+
+#### `admin.updateUser`
+
+```ts
+admin.updateUser(userId: string, attributes: Record<string, unknown>): Promise<User>
+```
+
+Updates an existing user by ID. Pass any attributes to change (e.g., `{ email: 'new@example.com' }`).
+
+**Throws:** `AuthError` if the user is not found or the update fails.
+
+#### `admin.deleteUser`
+
+```ts
+admin.deleteUser(userId: string): Promise<void>
+```
+
+Deletes a user by ID.
+
+**Throws:** `AuthError` if the user is not found or the deletion fails.
 
 ### Types
 
@@ -136,6 +378,27 @@ interface IdentityConfig {
 type AuthProvider = 'google' | 'github' | 'gitlab' | 'bitbucket' | 'facebook' | 'saml' | 'email'
 ```
 
+#### `UserUpdates`
+
+```ts
+interface UserUpdates {
+  email?: string
+  password?: string
+  data?: Record<string, unknown>
+  [key: string]: unknown
+}
+```
+
+Fields accepted by `updateUser()`. All fields are optional.
+
+#### `SignupData`
+
+```ts
+type SignupData = Record<string, unknown>
+```
+
+User metadata passed as the third argument to `signup()`. Stored in the user's `user_metadata` field.
+
 #### `AppMetadata`
 
 ```ts
@@ -146,6 +409,46 @@ interface AppMetadata {
 }
 ```
 
+#### `AUTH_EVENTS`
+
+```ts
+const AUTH_EVENTS: {
+  LOGIN: 'login'
+  LOGOUT: 'logout'
+  TOKEN_REFRESH: 'token_refresh'
+  USER_UPDATED: 'user_updated'
+  RECOVERY: 'recovery'
+}
+```
+
+Constants for auth event names. Use these instead of string literals for type safety and autocomplete.
+
+#### `AuthEvent`
+
+```ts
+type AuthEvent = 'login' | 'logout' | 'token_refresh' | 'user_updated' | 'recovery'
+```
+
+#### `AuthCallback`
+
+```ts
+type AuthCallback = (event: AuthEvent, user: User | null) => void
+```
+
+#### `CallbackResult`
+
+```ts
+interface CallbackResult {
+  type: 'oauth' | 'confirmation' | 'recovery' | 'invite' | 'email_change'
+  user: User | null
+  token?: string
+}
+```
+
+The `token` field is only present for `invite` callbacks, where the user hasn't set a password yet. Pass `token` to `acceptInvite(token, password)` to finish.
+
+For all other types (`oauth`, `confirmation`, `recovery`, `email_change`), the user is logged in directly and `token` is not set.
+
 ### Errors
 
 #### `AuthError`
@@ -165,6 +468,469 @@ class MissingIdentityError extends Error {}
 
 Thrown when Identity is not configured in the current environment.
 
+## Framework integration
+
+### Recommended pattern for SSR frameworks
+
+For SSR frameworks (Next.js, Remix, Astro, TanStack Start), the recommended pattern is:
+
+- **Browser-side** for auth mutations: `login()`, `signup()`, `logout()`, `oauthLogin()`
+- **Server-side** for reading auth state: `getUser()`, `getSettings()`, `getIdentityConfig()`
+
+Browser-side auth mutations call the GoTrue API directly from the browser, set the `nf_jwt` cookie and gotrue-js localStorage, and emit `onAuthChange` events. This keeps the client UI in sync immediately. Server-side reads work because the cookie is sent with every request.
+
+The library also supports server-side mutations (`login()`, `signup()`, `logout()` inside Netlify Functions), but these require the Netlify Functions runtime to set cookies. After a server-side mutation, you need a full page navigation so the browser sends the new cookie.
+
+### Next.js (App Router)
+
+**Server Actions return results; the client handles navigation:**
+
+```tsx
+// app/actions.ts
+'use server'
+import { login, logout } from '@netlify/identity'
+
+export async function loginAction(formData: FormData) {
+  const email = formData.get('email') as string
+  const password = formData.get('password') as string
+  await login(email, password)
+  return { success: true }
+}
+
+export async function logoutAction() {
+  await logout()
+  return { success: true }
+}
+```
+
+```tsx
+// app/login/page.tsx
+'use client'
+import { loginAction } from '../actions'
+
+export default function LoginPage() {
+  async function handleSubmit(formData: FormData) {
+    const result = await loginAction(formData)
+    if (result.success) {
+      window.location.href = '/dashboard' // full page load
+    }
+  }
+
+  return <form action={handleSubmit}>...</form>
+}
+```
+
+```tsx
+// app/dashboard/page.tsx
+import { getUser } from '@netlify/identity'
+import { redirect } from 'next/navigation'
+
+export default function Dashboard() {
+  const user = getUser()
+  if (!user) redirect('/login')
+
+  return <h1>Hello, {user.email}</h1>
+}
+```
+
+Use `window.location.href` instead of Next.js `redirect()` after server-side auth mutations. Next.js `redirect()` triggers a soft navigation via the Router, which may not include the newly-set auth cookie. A full page load ensures the cookie is sent and the server sees the updated auth state. Reading auth state with `getUser()` in Server Components works normally, and `redirect()` is fine for auth gates (where no cookie was just set).
+
+### Remix
+
+**Login with Action (server-side pattern):**
+
+```tsx
+// app/routes/login.tsx
+import { login } from '@netlify/identity'
+import { redirect, json } from '@remix-run/node'
+import type { ActionFunctionArgs } from '@remix-run/node'
+
+export async function action({ request }: ActionFunctionArgs) {
+  const formData = await request.formData()
+  const email = formData.get('email') as string
+  const password = formData.get('password') as string
+
+  try {
+    await login(email, password)
+    return redirect('/dashboard')
+  } catch (error) {
+    return json({ error: (error as Error).message }, { status: 400 })
+  }
+}
+```
+
+```tsx
+// app/routes/dashboard.tsx
+import { getUser } from '@netlify/identity'
+import { redirect } from '@remix-run/node'
+
+export async function loader() {
+  const user = getUser()
+  if (!user) return redirect('/login')
+  return { user }
+}
+```
+
+Remix `redirect()` works after server-side `login()` because Remix actions return real HTTP responses. The browser receives a 302 with the `Set-Cookie` header already applied, so the next request includes the auth cookie. This is different from Next.js, where `redirect()` in a Server Action triggers a client-side (soft) navigation that may not include newly-set cookies.
+
+### TanStack Start
+
+**Login from the browser (recommended):**
+
+```tsx
+// app/server/auth.ts - server functions for reads only
+import { createServerFn } from '@tanstack/react-start'
+import { getUser } from '@netlify/identity'
+
+export const getServerUser = createServerFn({ method: 'GET' }).handler(async () => {
+  const user = getUser()
+  return user ?? null
+})
+```
+
+```tsx
+// app/routes/login.tsx - browser-side auth for mutations
+import { login, signup, onAuthChange } from '@netlify/identity'
+import { getServerUser } from '~/server/auth'
+
+export const Route = createFileRoute('/login')({
+  beforeLoad: async () => {
+    const user = await getServerUser()
+    if (user) throw redirect({ to: '/dashboard' })
+  },
+  component: Login,
+})
+
+function Login() {
+  const handleLogin = async (email: string, password: string) => {
+    await login(email, password) // browser-side: sets cookie + localStorage
+    window.location.href = '/dashboard'
+  }
+  // ...
+}
+```
+
+```tsx
+// app/routes/dashboard.tsx
+import { logout } from '@netlify/identity'
+import { getServerUser } from '~/server/auth'
+
+export const Route = createFileRoute('/dashboard')({
+  beforeLoad: async () => {
+    const user = await getServerUser()
+    if (!user) throw redirect({ to: '/login' })
+  },
+  loader: async () => {
+    const user = await getServerUser()
+    return { user: user! }
+  },
+  component: Dashboard,
+})
+
+function Dashboard() {
+  const { user } = Route.useLoaderData()
+
+  const handleLogout = async () => {
+    await logout() // browser-side: clears cookie + localStorage
+    window.location.href = '/'
+  }
+  // ...
+}
+```
+
+Use `window.location.href` instead of TanStack Router's `navigate()` after auth changes. This ensures the browser sends the updated cookie on the next request.
+
+### Astro (SSR)
+
+**Login via API endpoint (server-side pattern):**
+
+```ts
+// src/pages/api/login.ts
+import type { APIRoute } from 'astro'
+import { login } from '@netlify/identity'
+
+export const POST: APIRoute = async ({ request }) => {
+  const { email, password } = await request.json()
+
+  try {
+    await login(email, password)
+    return new Response(null, {
+      status: 302,
+      headers: { Location: '/dashboard' },
+    })
+  } catch (error) {
+    return Response.json({ error: (error as Error).message }, { status: 400 })
+  }
+}
+```
+
+```astro
+---
+// src/pages/dashboard.astro
+import { getUser } from '@netlify/identity'
+
+const user = getUser()
+if (!user) return Astro.redirect('/login')
+---
+<h1>Hello, {user.email}</h1>
+```
+
+### SvelteKit
+
+**Login from the browser (recommended):**
+
+```svelte
+<!-- src/routes/login/+page.svelte -->
+<script lang="ts">
+  import { login } from '@netlify/identity'
+
+  let email = ''
+  let password = ''
+  let error = ''
+
+  async function handleLogin() {
+    try {
+      await login(email, password)
+      window.location.href = '/dashboard'
+    } catch (e) {
+      error = (e as Error).message
+    }
+  }
+</script>
+
+<form on:submit|preventDefault={handleLogin}>
+  <input bind:value={email} type="email" />
+  <input bind:value={password} type="password" />
+  <button type="submit">Log in</button>
+  {#if error}<p>{error}</p>{/if}
+</form>
+```
+
+```ts
+// src/routes/dashboard/+page.server.ts
+import { getUser } from '@netlify/identity'
+import { redirect } from '@sveltejs/kit'
+
+export function load() {
+  const user = getUser()
+  if (!user) redirect(302, '/login')
+  return { user }
+}
+```
+
+### Handling OAuth callbacks in SPAs
+
+All SPA frameworks need a callback handler that runs on page load to process OAuth redirects, email confirmations, and password recovery tokens. Use a **wrapper component** that blocks page content while processing tokens. This prevents a flash of unauthenticated content that occurs when the page renders before the callback completes.
+
+```tsx
+// React component (works with Next.js, Remix, TanStack Start)
+import { useEffect, useState } from 'react'
+import { handleAuthCallback } from '@netlify/identity'
+
+const AUTH_HASH_PATTERN = /^#(confirmation_token|recovery_token|invite_token|email_change_token|access_token)=/
+
+export function CallbackHandler({ children }: { children: React.ReactNode }) {
+  const [processing, setProcessing] = useState(
+    () => typeof window !== 'undefined' && AUTH_HASH_PATTERN.test(window.location.hash),
+  )
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!window.location.hash || !AUTH_HASH_PATTERN.test(window.location.hash)) return
+
+    handleAuthCallback()
+      .then((result) => {
+        if (!result) {
+          setProcessing(false)
+          return
+        }
+        if (result.type === 'invite') {
+          window.location.href = `/accept-invite?token=${result.token}`
+        } else if (result.type === 'recovery') {
+          window.location.href = '/reset-password'
+        } else {
+          window.location.href = '/dashboard'
+        }
+      })
+      .catch((err) => {
+        setError(err instanceof Error ? err.message : 'Callback failed')
+        setProcessing(false)
+      })
+  }, [])
+
+  if (error) return <div>Auth error: {error}</div>
+  if (processing) return <div>Confirming your account...</div>
+  return <>{children}</>
+}
+```
+
+Wrap your page content with this component in your **root layout** so it runs on every page:
+
+```tsx
+// Root layout
+<CallbackHandler>
+  <Outlet /> {/* or {children} in Next.js */}
+</CallbackHandler>
+```
+
+If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will not be processed.
+
+## Guides
+
+### React `useAuth` hook
+
+The library is framework-agnostic, but here's a simple React hook for keeping components in sync with auth state:
+
+```tsx
+import { useState, useEffect } from 'react'
+import { getUser, onAuthChange } from '@netlify/identity'
+import type { User } from '@netlify/identity'
+
+export function useAuth() {
+  const [user, setUser] = useState<User | null>(getUser())
+
+  useEffect(() => {
+    return onAuthChange((_event, user) => setUser(user))
+  }, [])
+
+  return user
+}
+```
+
+```tsx
+function NavBar() {
+  const user = useAuth()
+  return user ? <p>Hello, {user.name}</p> : <a href="/login">Log in</a>
+}
+```
+
+### Listening for auth changes
+
+Use `onAuthChange` to keep your UI in sync with auth state. It fires on login, logout, token refresh, user updates, and recovery. It also detects session changes in other browser tabs (via `localStorage`).
+
+```ts
+import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
+
+const unsubscribe = onAuthChange((event, user) => {
+  switch (event) {
+    case AUTH_EVENTS.LOGIN:
+      console.log('Logged in:', user?.email)
+      break
+    case AUTH_EVENTS.LOGOUT:
+      console.log('Logged out')
+      break
+    case AUTH_EVENTS.TOKEN_REFRESH:
+      console.log('Token refreshed for:', user?.email)
+      break
+    case AUTH_EVENTS.USER_UPDATED:
+      console.log('User updated:', user?.email)
+      break
+    case AUTH_EVENTS.RECOVERY:
+      console.log('Recovery login:', user?.email)
+      // Redirect to password reset form, then call updateUser({ password })
+      break
+  }
+})
+
+// Later, to stop listening:
+unsubscribe()
+```
+
+On the server, `onAuthChange` is a no-op and the returned unsubscribe function does nothing.
+
+### OAuth login
+
+OAuth login is a two-step flow: redirect the user to the provider, then process the callback when they return.
+
+**Step by step:**
+
+```ts
+import { oauthLogin, handleAuthCallback } from '@netlify/identity'
+
+// 1. Kick off the OAuth flow (e.g., from a "Sign in with GitHub" button).
+//    This navigates away from the page and does not return.
+oauthLogin('github')
+```
+
+```ts
+// 2. On page load, handle the redirect back from the provider.
+const result = await handleAuthCallback()
+
+if (result?.type === 'oauth') {
+  console.log('Logged in via OAuth:', result.user?.email)
+}
+```
+
+`handleAuthCallback()` exchanges the token in the URL hash, logs the user in, clears the hash, and emits an auth event via `onAuthChange` (`'login'` for OAuth/confirmation, `'recovery'` for password recovery).
+
+### Password recovery
+
+Password recovery is a two-step flow. The library handles the token exchange automatically via `handleAuthCallback()`, which logs the user in and returns `{type: 'recovery', user}`. A `'recovery'` event (not `'login'`) is emitted via `onAuthChange`, so event-based listeners can also detect this flow. You then show a "set new password" form and call `updateUser()` to save it.
+
+**Step by step:**
+
+```ts
+import { requestPasswordRecovery, handleAuthCallback, updateUser } from '@netlify/identity'
+
+// 1. Send recovery email (e.g., from a "forgot password" form)
+await requestPasswordRecovery('jane@example.com')
+
+// 2-3. On page load, handle the callback
+const result = await handleAuthCallback()
+
+if (result?.type === 'recovery') {
+  // 4. User is now logged in. Show your "set new password" form.
+  //    When they submit:
+  const newPassword = document.getElementById('new-password').value
+  await updateUser({ password: newPassword })
+}
+```
+
+If you use the event-based pattern instead of checking `result.type`, listen for the `'recovery'` event:
+
+```ts
+import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
+
+onAuthChange((event, user) => {
+  if (event === AUTH_EVENTS.RECOVERY) {
+    // Redirect to password reset form.
+    // The user is authenticated, so call updateUser({ password }) to set the new password.
+  }
+})
+```
+
+### Invite acceptance
+
+When an admin invites a user, they receive an email with an invite link. Clicking it redirects to your site with an `invite_token` in the URL hash. Unlike other callback types, the user is not logged in automatically because they need to set a password first.
+
+**Step by step:**
+
+```ts
+import { handleAuthCallback, acceptInvite } from '@netlify/identity'
+
+// 1. On page load, handle the callback.
+const result = await handleAuthCallback()
+
+if (result?.type === 'invite' && result.token) {
+  // 2. The user is NOT logged in yet. Show a "set your password" form.
+  //    When they submit:
+  const password = document.getElementById('password').value
+  const user = await acceptInvite(result.token, password)
+  console.log('Account created:', user.email)
+}
+```
+
+### Session lifetime
+
+Sessions are managed by Netlify Identity (GoTrue) on the server side. The library stores two cookies:
+
+- **`nf_jwt`**: A short-lived JWT access token (default: 1 hour). Automatically refreshed by gotrue-js in the browser using the refresh token.
+- **`nf_refresh`**: A long-lived refresh token used to obtain new access tokens without re-authenticating.
+
+In the browser, gotrue-js handles token refresh automatically in the background. On the server, the access token in the `nf_jwt` cookie is validated as-is; if it has expired, `getUser()` returns `null`. The user will need to refresh the page (which triggers a browser-side token refresh) or log in again.
+
+Session lifetime is configured in your GoTrue/Identity server settings, not in this library.
+
 ## License
 
 MIT