@netlify/identity 0.1.1-alpha.22 → 0.1.1-alpha.24

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`
@@ -646,6 +660,8 @@ export function CallbackHandler({ children }: { children: React.ReactNode }) {
         }
         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'
         }
@@ -704,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
   }
 })
 
@@ -755,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:**
 
@@ -780,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,
@@ -70,7 +71,7 @@ var AuthError = class extends Error {
   }
 };
 var MissingIdentityError = class extends Error {
-  constructor(message = "Netlify Identity is not available. Enable Identity in your site dashboard and use `netlify dev` for local development.") {
+  constructor(message = "Netlify Identity is not available.") {
     super(message);
     this.name = "MissingIdentityError";
   }
@@ -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;
-};
-var getServerIdentityUrl = () => {
-  const ctx = getIdentityContext();
-  if (!ctx?.url) {
-    throw new AuthError("Could not determine the Identity endpoint URL on the server");
-  }
-  return ctx.url;
+// src/events.ts
+var AUTH_EVENTS = {
+  LOGIN: "login",
+  LOGOUT: "logout",
+  TOKEN_REFRESH: "token_refresh",
+  USER_UPDATED: "user_updated",
+  RECOVERY: "recovery"
 };
-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 });
   }
@@ -547,87 +550,92 @@ var handleAuthCallback = async () => {
   const hash = window.location.hash.substring(1);
   if (!hash) return null;
   const client = getClient();
+  const params = new URLSearchParams(hash);
   try {
-    const params = new URLSearchParams(hash);
     const accessToken = params.get("access_token");
-    if (accessToken) {
-      const refreshToken = params.get("refresh_token") ?? "";
-      const gotrueUser = await client.createUser(
-        {
-          access_token: accessToken,
-          token_type: params.get("token_type") ?? "bearer",
-          expires_in: Number(params.get("expires_in")),
-          expires_at: Number(params.get("expires_at")),
-          refresh_token: refreshToken
-        },
-        persistSession
-      );
-      setBrowserAuthCookies(accessToken, refreshToken || void 0);
-      const user = toUser(gotrueUser);
-      clearHash();
-      emitAuthEvent("login", user);
-      return { type: "oauth", user };
-    }
+    if (accessToken) return await handleOAuthCallback(client, params, accessToken);
     const confirmationToken = params.get("confirmation_token");
-    if (confirmationToken) {
-      const gotrueUser = await client.confirm(confirmationToken, persistSession);
-      const jwt = await gotrueUser.jwt();
-      setBrowserAuthCookies(jwt);
-      const user = toUser(gotrueUser);
-      clearHash();
-      emitAuthEvent("login", user);
-      return { type: "confirmation", user };
-    }
+    if (confirmationToken) return await handleConfirmationCallback(client, confirmationToken);
     const recoveryToken = params.get("recovery_token");
-    if (recoveryToken) {
-      const gotrueUser = await client.recover(recoveryToken, persistSession);
-      const jwt = await gotrueUser.jwt();
-      setBrowserAuthCookies(jwt);
-      const user = toUser(gotrueUser);
-      clearHash();
-      emitAuthEvent("login", user);
-      return { type: "recovery", user };
-    }
+    if (recoveryToken) return await handleRecoveryCallback(client, recoveryToken);
     const inviteToken = params.get("invite_token");
-    if (inviteToken) {
-      clearHash();
-      return { type: "invite", user: null, token: inviteToken };
-    }
+    if (inviteToken) return handleInviteCallback(inviteToken);
     const emailChangeToken = params.get("email_change_token");
-    if (emailChangeToken) {
-      const currentUser = client.currentUser();
-      if (!currentUser) {
-        throw new AuthError("Email change verification requires an active browser session");
-      }
-      const jwt = await currentUser.jwt();
-      const identityUrl = `${window.location.origin}${IDENTITY_PATH}`;
-      const emailChangeRes = await fetch(`${identityUrl}/user`, {
-        method: "PUT",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${jwt}`
-        },
-        body: JSON.stringify({ email_change_token: emailChangeToken })
-      });
-      if (!emailChangeRes.ok) {
-        const errorBody = await emailChangeRes.json().catch(() => ({}));
-        throw new AuthError(
-          errorBody.msg || `Email change verification failed (${emailChangeRes.status})`,
-          emailChangeRes.status
-        );
-      }
-      const emailChangeData = await emailChangeRes.json();
-      const user = toUser(emailChangeData);
-      clearHash();
-      emitAuthEvent("user_updated", user);
-      return { type: "email_change", user };
-    }
+    if (emailChangeToken) return await handleEmailChangeCallback(client, emailChangeToken);
     return null;
   } catch (error) {
     if (error instanceof AuthError) throw error;
     throw new AuthError(error.message, void 0, { cause: error });
   }
 };
+var handleOAuthCallback = async (client, params, accessToken) => {
+  const refreshToken = params.get("refresh_token") ?? "";
+  const gotrueUser = await client.createUser(
+    {
+      access_token: accessToken,
+      token_type: params.get("token_type") ?? "bearer",
+      expires_in: Number(params.get("expires_in")),
+      expires_at: Number(params.get("expires_at")),
+      refresh_token: refreshToken
+    },
+    persistSession
+  );
+  setBrowserAuthCookies(accessToken, refreshToken || void 0);
+  const user = toUser(gotrueUser);
+  clearHash();
+  emitAuthEvent(AUTH_EVENTS.LOGIN, user);
+  return { type: "oauth", user };
+};
+var handleConfirmationCallback = async (client, token) => {
+  const gotrueUser = await client.confirm(token, persistSession);
+  const jwt = await gotrueUser.jwt();
+  setBrowserAuthCookies(jwt);
+  const user = toUser(gotrueUser);
+  clearHash();
+  emitAuthEvent(AUTH_EVENTS.LOGIN, user);
+  return { type: "confirmation", user };
+};
+var handleRecoveryCallback = async (client, token) => {
+  const gotrueUser = await client.recover(token, persistSession);
+  const jwt = await gotrueUser.jwt();
+  setBrowserAuthCookies(jwt);
+  const user = toUser(gotrueUser);
+  clearHash();
+  emitAuthEvent(AUTH_EVENTS.RECOVERY, user);
+  return { type: "recovery", user };
+};
+var handleInviteCallback = (token) => {
+  clearHash();
+  return { type: "invite", user: null, token };
+};
+var handleEmailChangeCallback = async (client, emailChangeToken) => {
+  const currentUser = client.currentUser();
+  if (!currentUser) {
+    throw new AuthError("Email change verification requires an active browser session");
+  }
+  const jwt = await currentUser.jwt();
+  const identityUrl = `${window.location.origin}${IDENTITY_PATH}`;
+  const emailChangeRes = await fetch(`${identityUrl}/user`, {
+    method: "PUT",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${jwt}`
+    },
+    body: JSON.stringify({ email_change_token: emailChangeToken })
+  });
+  if (!emailChangeRes.ok) {
+    const errorBody = await emailChangeRes.json().catch(() => ({}));
+    throw new AuthError(
+      errorBody.msg || `Email change verification failed (${emailChangeRes.status})`,
+      emailChangeRes.status
+    );
+  }
+  const emailChangeData = await emailChangeRes.json();
+  const user = toUser(emailChangeData);
+  clearHash();
+  emitAuthEvent(AUTH_EVENTS.USER_UPDATED, user);
+  return { type: "email_change", user };
+};
 var clearHash = () => {
   history.replaceState(null, "", window.location.pathname + window.location.search);
 };
@@ -653,12 +661,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 +693,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 +704,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 +715,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 +723,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 +737,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 +749,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 +761,7 @@ var updateUser = async (updates) => {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTH_EVENTS,
   AuthError,
   MissingIdentityError,
   acceptInvite,