@netlify/identity 0.1.1-alpha.8 → 0.1.1

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`. Never throws.
+Returns `true` if a user is currently authenticated. Equivalent to `getUser() !== null`.
 
 #### `getIdentityConfig`
 
@@ -90,135 +90,7 @@ 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 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?: Record<string, unknown>): Promise<User>
-```
-
-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`
-
-```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.
-
-**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`
-
-```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. `Error` 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). Returns an unsubscribe function. Also fires on cross-tab session changes. No-op on the server.
-
-#### `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: 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.
+Fetches your project's Identity settings (enabled providers, autoconfirm, signup disabled). Throws `MissingIdentityError` if not configured; throws `AuthError` if the endpoint is unreachable.
 
 ### Types
 
@@ -274,33 +146,6 @@ interface AppMetadata {
 }
 ```
 
-#### `AuthEvent`
-
-```ts
-type AuthEvent = 'login' | 'logout' | 'token_refresh' | 'user_updated'
-```
-
-#### `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`
@@ -320,107 +165,6 @@ class MissingIdentityError extends Error {}
 
 Thrown when Identity is not configured in the current environment.
 
-## 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.
-
-**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 })
-}
-```
-
-### 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