@netlify/identity 0.1.1-alpha.2 → 0.1.1-alpha.20

package/README.md

@@ -74,7 +74,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 +90,9 @@ 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`
 
@@ -98,7 +100,11 @@ Fetches your project's Identity settings (enabled providers, autoconfirm, signup
 login(email: string, password: string): Promise<User>
 ```
 
-Logs in with email and password. Browser only.
+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`
 
@@ -106,7 +112,11 @@ Logs in with email and password. Browser only.
 signup(email: string, password: string, data?: Record<string, unknown>): Promise<User>
 ```
 
-Creates a new account. Emits `'login'` if autoconfirm is enabled. Browser only.
+Creates a new account. Works in both browser and server contexts.
+
+In the browser, uses gotrue-js and emits `'login'` if autoconfirm is enabled. On the server, calls the GoTrue HTTP API directly and sets the `nf_jwt` cookie if the user is auto-confirmed.
+
+**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`
 
@@ -114,7 +124,11 @@ Creates a new account. Emits `'login'` if autoconfirm is enabled. Browser only.
 logout(): Promise<void>
 ```
 
-Logs out the current user and clears the session. Browser only.
+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.
+
+**Throws:** `AuthError` on network failure. In the browser, `MissingIdentityError` if Identity is not configured. On the server, `AuthError` if the Netlify Functions runtime is not available.
 
 #### `oauthLogin`
 
@@ -122,7 +136,11 @@ Logs out the current user and clears the session. Browser only.
 oauthLogin(provider: string): never
 ```
 
-Redirects to an OAuth provider. Always throws (the page navigates away). Browser only.
+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. `Error` if called on the server.
 
 #### `handleAuthCallback`
 
@@ -132,6 +150,8 @@ 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
@@ -148,6 +168,8 @@ 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
@@ -156,6 +178,8 @@ 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
@@ -164,13 +188,27 @@ 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. Requires an active session.
+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`
 
@@ -180,6 +218,8 @@ updateUser(updates: Record<string, unknown>): Promise<User>
 
 Updates the current user's metadata or credentials. Requires an active session.
 
+**Throws:** `MissingIdentityError` if Identity is not configured. `AuthError` if no user is logged in, or the update fails.
+
 ### Types
 
 #### `User`
@@ -256,6 +296,10 @@ interface CallbackResult {
 }
 ```
 
+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`
@@ -275,8 +319,299 @@ 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 actions return HTTP responses, so `redirect()` after server-side `login()` works correctly with 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>
+```
+
+### 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.
+
+```tsx
+// React component (works with Next.js, Remix, TanStack Start)
+import { useEffect } from 'react'
+import { handleAuthCallback } from '@netlify/identity'
+
+export function CallbackHandler() {
+  useEffect(() => {
+    if (!window.location.hash) return
+
+    handleAuthCallback().then((result) => {
+      if (!result) return
+      if (result.type === 'invite') {
+        window.location.href = `/accept-invite?token=${result.token}`
+      } else {
+        window.location.href = '/dashboard'
+      }
+    })
+  }, [])
+
+  return null
+}
+```
+
+Mount this component in your root layout so it processes callbacks on any page.
+
 ## Guides
 
+### Listening for auth changes
+
+Use `onAuthChange` to keep your UI in sync with auth state. It fires on login, logout, token refresh, and user updates. It also detects session changes in other browser tabs (via `localStorage`).
+
+```ts
+import { onAuthChange } from '@netlify/identity'
+
+const unsubscribe = onAuthChange((event, user) => {
+  switch (event) {
+    case 'login':
+      console.log('Logged in:', user?.email)
+      break
+    case 'logout':
+      console.log('Logged out')
+      break
+    case 'token_refresh':
+      console.log('Token refreshed for:', user?.email)
+      break
+    case 'user_updated':
+      console.log('User updated:', user?.email)
+      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 a `'login'` event via `onAuthChange`.
+
 ### 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}`. You then show a "set new password" form and call `updateUser()` to save it.
@@ -300,6 +635,27 @@ if (result?.type === 'recovery') {
 }
 ```
 
+### 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)
+}
+```
+
 ## License
 
 MIT