@netlify/identity 0.1.1-alpha.21 → 0.1.1-alpha.23

package/README.md

@@ -164,7 +164,7 @@ Processes the URL hash after an OAuth redirect, email confirmation, password rec
 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.
+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`
 
@@ -323,10 +323,24 @@ 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'
+type AuthEvent = 'login' | 'logout' | 'token_refresh' | 'user_updated' | 'recovery'
 ```
 
 #### `AuthCallback`
@@ -620,32 +634,60 @@ export function load() {
 
 ### 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.
+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 } from 'react'
+import { useEffect, useState } from 'react'
 import { handleAuthCallback } from '@netlify/identity'
 
-export function CallbackHandler() {
+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) return
-
-    handleAuthCallback().then((result) => {
-      if (!result) return
-      if (result.type === 'invite') {
-        window.location.href = `/accept-invite?token=${result.token}`
-      } else {
-        window.location.href = '/dashboard'
-      }
-    })
+    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)
+      })
   }, [])
 
-  return null
+  if (error) return <div>Auth error: {error}</div>
+  if (processing) return <div>Confirming your account...</div>
+  return <>{children}</>
 }
 ```
 
-Mount this component in your **root layout** so it runs on every page. If you only mount it on a `/callback` route, OAuth redirects and email confirmation links that land on other pages will not be processed.
+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
 
@@ -678,25 +720,29 @@ function NavBar() {
 
 ### 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`).
+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 } from '@netlify/identity'
+import { onAuthChange, AUTH_EVENTS } from '@netlify/identity'
 
 const unsubscribe = onAuthChange((event, user) => {
   switch (event) {
-    case 'login':
+    case AUTH_EVENTS.LOGIN:
       console.log('Logged in:', user?.email)
       break
-    case 'logout':
+    case AUTH_EVENTS.LOGOUT:
       console.log('Logged out')
       break
-    case 'token_refresh':
+    case AUTH_EVENTS.TOKEN_REFRESH:
       console.log('Token refreshed for:', user?.email)
       break
-    case 'user_updated':
+    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
   }
 })
 
@@ -729,11 +775,11 @@ if (result?.type === 'oauth') {
 }
 ```
 
-`handleAuthCallback()` exchanges the token in the URL hash, logs the user in, clears the hash, and emits a `'login'` event via `onAuthChange`.
+`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}`. You then show a "set new password" form and call `updateUser()` to save it.
+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:**
 
@@ -754,6 +800,19 @@ if (result?.type === 'recovery') {
 }
 ```
 
+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.

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AUTH_EVENTS: () => AUTH_EVENTS,
   AuthError: () => AuthError,
   MissingIdentityError: () => MissingIdentityError,
   acceptInvite: () => acceptInvite,
@@ -348,22 +349,15 @@ var getSettings = async () => {
   }
 };
 
-// src/auth.ts
-var getCookies = () => {
-  const cookies = globalThis.Netlify?.context?.cookies;
-  if (!cookies) {
-    throw new AuthError("Server-side auth requires Netlify Functions runtime");
-  }
-  return cookies;
+// src/events.ts
+var AUTH_EVENTS = {
+  LOGIN: "login",
+  LOGOUT: "logout",
+  TOKEN_REFRESH: "token_refresh",
+  USER_UPDATED: "user_updated",
+  RECOVERY: "recovery"
 };
-var getServerIdentityUrl = () => {
-  const ctx = getIdentityContext();
-  if (!ctx?.url) {
-    throw new AuthError("Could not determine the Identity endpoint URL on the server");
-  }
-  return ctx.url;
-};
-var persistSession = true;
+var GOTRUE_STORAGE_KEY = "gotrue.user";
 var listeners = /* @__PURE__ */ new Set();
 var emitAuthEvent = (event, user) => {
   for (const listener of listeners) {
@@ -373,19 +367,18 @@ var emitAuthEvent = (event, user) => {
     }
   }
 };
-var GOTRUE_STORAGE_KEY = "gotrue.user";
 var storageListenerAttached = false;
 var attachStorageListener = () => {
-  if (storageListenerAttached) return;
+  if (storageListenerAttached || !isBrowser()) return;
   storageListenerAttached = true;
   window.addEventListener("storage", (event) => {
     if (event.key !== GOTRUE_STORAGE_KEY) return;
     if (event.newValue) {
       const client = getGoTrueClient();
       const currentUser = client?.currentUser();
-      emitAuthEvent("login", currentUser ? toUser(currentUser) : null);
+      emitAuthEvent(AUTH_EVENTS.LOGIN, currentUser ? toUser(currentUser) : null);
     } else {
-      emitAuthEvent("logout", null);
+      emitAuthEvent(AUTH_EVENTS.LOGOUT, null);
     }
   });
 };
@@ -400,6 +393,23 @@ var onAuthChange = (callback) => {
     listeners.delete(callback);
   };
 };
+
+// src/auth.ts
+var getCookies = () => {
+  const cookies = globalThis.Netlify?.context?.cookies;
+  if (!cookies) {
+    throw new AuthError("Server-side auth requires Netlify Functions runtime");
+  }
+  return cookies;
+};
+var getServerIdentityUrl = () => {
+  const ctx = getIdentityContext();
+  if (!ctx?.url) {
+    throw new AuthError("Could not determine the Identity endpoint URL on the server");
+  }
+  return ctx.url;
+};
+var persistSession = true;
 var login = async (email, password) => {
   if (!isBrowser()) {
     const identityUrl = getServerIdentityUrl();
@@ -421,10 +431,7 @@ var login = async (email, password) => {
     }
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({}));
-      throw new AuthError(
-        errorBody.msg || errorBody.error_description || `Login failed (${res.status})`,
-        res.status
-      );
+      throw new AuthError(errorBody.msg || errorBody.error_description || `Login failed (${res.status})`, res.status);
     }
     const data = await res.json();
     const accessToken = data.access_token;
@@ -438,10 +445,7 @@ var login = async (email, password) => {
     }
     if (!userRes.ok) {
       const errorBody = await userRes.json().catch(() => ({}));
-      throw new AuthError(
-        errorBody.msg || `Failed to fetch user data (${userRes.status})`,
-        userRes.status
-      );
+      throw new AuthError(errorBody.msg || `Failed to fetch user data (${userRes.status})`, userRes.status);
     }
     const userData = await userRes.json();
     const user = toUser(userData);
@@ -454,7 +458,7 @@ var login = async (email, password) => {
     const jwt = await gotrueUser.jwt();
     setBrowserAuthCookies(jwt);
     const user = toUser(gotrueUser);
-    emitAuthEvent("login", user);
+    emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     return user;
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
@@ -481,10 +485,9 @@ var signup = async (email, password, data) => {
     const responseData = await res.json();
     const user = toUser(responseData);
     if (responseData.confirmed_at) {
-      const responseRecord = responseData;
-      const accessToken = responseRecord.access_token;
+      const accessToken = responseData.access_token;
       if (accessToken) {
-        setAuthCookies(cookies, accessToken, responseRecord.refresh_token);
+        setAuthCookies(cookies, accessToken, responseData.refresh_token);
       }
     }
     return user;
@@ -498,7 +501,7 @@ var signup = async (email, password, data) => {
       if (jwt) {
         setBrowserAuthCookies(jwt);
       }
-      emitAuthEvent("login", user);
+      emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     }
     return user;
   } catch (error) {
@@ -529,7 +532,7 @@ var logout = async () => {
       await currentUser.logout();
     }
     deleteBrowserAuthCookies();
-    emitAuthEvent("logout", null);
+    emitAuthEvent(AUTH_EVENTS.LOGOUT, null);
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
   }
@@ -565,7 +568,7 @@ var handleAuthCallback = async () => {
       setBrowserAuthCookies(accessToken, refreshToken || void 0);
       const user = toUser(gotrueUser);
       clearHash();
-      emitAuthEvent("login", user);
+      emitAuthEvent(AUTH_EVENTS.LOGIN, user);
       return { type: "oauth", user };
     }
     const confirmationToken = params.get("confirmation_token");
@@ -575,7 +578,7 @@ var handleAuthCallback = async () => {
       setBrowserAuthCookies(jwt);
       const user = toUser(gotrueUser);
       clearHash();
-      emitAuthEvent("login", user);
+      emitAuthEvent(AUTH_EVENTS.LOGIN, user);
       return { type: "confirmation", user };
     }
     const recoveryToken = params.get("recovery_token");
@@ -585,7 +588,7 @@ var handleAuthCallback = async () => {
       setBrowserAuthCookies(jwt);
       const user = toUser(gotrueUser);
       clearHash();
-      emitAuthEvent("login", user);
+      emitAuthEvent(AUTH_EVENTS.RECOVERY, user);
       return { type: "recovery", user };
     }
     const inviteToken = params.get("invite_token");
@@ -619,7 +622,7 @@ var handleAuthCallback = async () => {
       const emailChangeData = await emailChangeRes.json();
       const user = toUser(emailChangeData);
       clearHash();
-      emitAuthEvent("user_updated", user);
+      emitAuthEvent(AUTH_EVENTS.USER_UPDATED, user);
       return { type: "email_change", user };
     }
     return null;
@@ -653,12 +656,12 @@ var hydrateSession = async () => {
     persistSession
   );
   const user = toUser(gotrueUser);
-  emitAuthEvent("login", user);
+  emitAuthEvent(AUTH_EVENTS.LOGIN, user);
   return user;
 };
 
 // src/account.ts
-var ensureCurrentUser = async () => {
+var resolveCurrentUser = async () => {
   const client = getClient();
   let currentUser = client.currentUser();
   if (!currentUser && isBrowser()) {
@@ -685,7 +688,7 @@ var recoverPassword = async (token, newPassword) => {
     const gotrueUser = await client.recover(token, persistSession);
     const updatedUser = await gotrueUser.update({ password: newPassword });
     const user = toUser(updatedUser);
-    emitAuthEvent("login", user);
+    emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     return user;
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
@@ -696,7 +699,7 @@ var confirmEmail = async (token) => {
   try {
     const gotrueUser = await client.confirm(token, persistSession);
     const user = toUser(gotrueUser);
-    emitAuthEvent("login", user);
+    emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     return user;
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
@@ -707,7 +710,7 @@ var acceptInvite = async (token, password) => {
   try {
     const gotrueUser = await client.acceptInvite(token, password, persistSession);
     const user = toUser(gotrueUser);
-    emitAuthEvent("login", user);
+    emitAuthEvent(AUTH_EVENTS.LOGIN, user);
     return user;
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
@@ -715,7 +718,7 @@ var acceptInvite = async (token, password) => {
 };
 var verifyEmailChange = async (token) => {
   if (!isBrowser()) throw new AuthError("verifyEmailChange() is only available in the browser");
-  const currentUser = await ensureCurrentUser();
+  const currentUser = await resolveCurrentUser();
   const jwt = await currentUser.jwt();
   const identityUrl = `${window.location.origin}${IDENTITY_PATH}`;
   try {
@@ -729,14 +732,11 @@ var verifyEmailChange = async (token) => {
     });
     if (!res.ok) {
       const errorBody = await res.json().catch(() => ({}));
-      throw new AuthError(
-        errorBody.msg || `Email change verification failed (${res.status})`,
-        res.status
-      );
+      throw new AuthError(errorBody.msg || `Email change verification failed (${res.status})`, res.status);
     }
     const userData = await res.json();
     const user = toUser(userData);
-    emitAuthEvent("user_updated", user);
+    emitAuthEvent(AUTH_EVENTS.USER_UPDATED, user);
     return user;
   } catch (error) {
     if (error instanceof AuthError) throw error;
@@ -744,11 +744,11 @@ var verifyEmailChange = async (token) => {
   }
 };
 var updateUser = async (updates) => {
-  const currentUser = await ensureCurrentUser();
+  const currentUser = await resolveCurrentUser();
   try {
     const updatedUser = await currentUser.update(updates);
     const user = toUser(updatedUser);
-    emitAuthEvent("user_updated", user);
+    emitAuthEvent(AUTH_EVENTS.USER_UPDATED, user);
     return user;
   } catch (error) {
     throw new AuthError(error.message, void 0, { cause: error });
@@ -756,6 +756,7 @@ var updateUser = async (updates) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTH_EVENTS,
   AuthError,
   MissingIdentityError,
   acceptInvite,