@netlify/identity 0.3.0-alpha.0 → 0.3.0-alpha.2

package/dist/index.d.ts

@@ -14,6 +14,36 @@ interface Settings {
     disableSignup: boolean;
     providers: Record<AuthProvider, boolean>;
 }
+/**
+ * Fields accepted by {@link updateUser}. All fields are optional.
+ * Pass `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
+ */
+interface UserUpdates {
+    email?: string;
+    password?: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * User metadata passed during signup (e.g., `{ full_name: 'Jane Doe' }`).
+ * Stored in the user's `user_metadata` field.
+ */
+type SignupData = Record<string, unknown>;
+/**
+ * Fields accepted by {@link admin.updateUser}. All fields are optional.
+ *
+ * Unlike {@link UserUpdates} (used by the self-service `updateUser`), admin updates
+ * can set `role`, force-confirm a user, and write to `app_metadata`.
+ */
+interface AdminUserUpdates {
+    email?: string;
+    password?: string;
+    role?: string;
+    confirm?: boolean;
+    app_metadata?: Record<string, unknown>;
+    user_metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 
 interface User {
     id: string;
@@ -29,7 +59,16 @@ interface User {
 }
 /**
  * Returns the currently authenticated user, or `null` if not logged in.
- * Synchronous. Never throws.
+ * Synchronous.
+ *
+ * In the browser, checks gotrue-js localStorage first. If no localStorage
+ * session exists, falls back to decoding the `nf_jwt` cookie (set by
+ * server-side login) and kicks off background hydration of the gotrue-js
+ * session so that subsequent operations (updateUser, logout, etc.) work.
+ *
+ * On the server in a Next.js App Router context, calls `headers()` from
+ * `next/headers` to opt the route into dynamic rendering. Without this,
+ * Next.js may statically cache the page at build time.
  */
 declare const getUser: () => User | null;
 /**
@@ -45,27 +84,83 @@ declare const isAuthenticated: () => boolean;
  */
 declare const getIdentityConfig: () => IdentityConfig | null;
 /**
- * Fetches the GoTrue `/settings` endpoint.
- * Throws `MissingIdentityError` if Identity is 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.
+ * @throws {AuthError} If the endpoint is unreachable.
  */
 declare const getSettings: () => Promise<Settings>;
 
-type AuthEvent = 'login' | 'logout' | 'token_refresh' | 'user_updated';
-
+declare const AUTH_EVENTS: {
+    readonly LOGIN: "login";
+    readonly LOGOUT: "logout";
+    readonly TOKEN_REFRESH: "token_refresh";
+    readonly USER_UPDATED: "user_updated";
+    readonly RECOVERY: "recovery";
+};
+type AuthEvent = (typeof AUTH_EVENTS)[keyof typeof AUTH_EVENTS];
 type AuthCallback = (event: AuthEvent, user: User | null) => void;
 /**
- * Subscribes to auth state changes (login, logout, token refresh, user updates).
- * Returns an unsubscribe function. No-op on the server.
+ * Subscribes to auth state changes (login, logout, token refresh, user updates,
+ * and recovery). Returns an unsubscribe function. No-op on the server.
+ *
+ * The `'recovery'` event fires when {@link handleAuthCallback} processes a
+ * password recovery token. The user is logged in but has not yet set a new
+ * password. Redirect them to a password reset form and call
+ * `updateUser({ password })` to complete the flow.
  */
 declare const onAuthChange: (callback: AuthCallback) => (() => void);
-/** Logs in with email and password. Works in both browser and server contexts. */
+
+/**
+ * Logs in with email and password. Works in both browser and server contexts.
+ *
+ * On success, sets `nf_jwt` and `nf_refresh` cookies and returns the authenticated {@link User}.
+ * In the browser, also emits a `'login'` event via {@link onAuthChange}.
+ *
+ * @throws {AuthError} On invalid credentials, network failure, or missing Netlify runtime.
+ *
+ * @remarks
+ * In Next.js server actions, call `redirect()` **after** `login()` returns, not inside a
+ * try/catch. Next.js implements `redirect()` by throwing a special error; wrapping it in
+ * try/catch will swallow the redirect.
+ *
+ * @example
+ * ```ts
+ * // Next.js server action
+ * const user = await login(email, password)
+ * redirect('/dashboard') // after login, not inside try/catch
+ * ```
+ */
 declare const login: (email: string, password: string) => Promise<User>;
-/** Creates a new account. Emits 'login' if autoconfirm is enabled. Works in both browser and server contexts. */
-declare const signup: (email: string, password: string, data?: Record<string, unknown>) => Promise<User>;
-/** Logs out the current user and clears the session. Works in both browser and server contexts. */
+/**
+ * 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.
+ *
+ * @throws {AuthError} On duplicate email, validation failure, network error, or missing Netlify runtime.
+ */
+declare const signup: (email: string, password: string, data?: SignupData) => Promise<User>;
+/**
+ * Logs out the current user and clears the session. Works in both browser and server contexts.
+ *
+ * Always deletes `nf_jwt` and `nf_refresh` cookies, even if the server-side token
+ * invalidation request fails. In the browser, emits a `'logout'` event via {@link onAuthChange}.
+ *
+ * @throws {AuthError} On missing Netlify runtime (server) or logout failure (browser).
+ */
 declare const logout: () => Promise<void>;
-/** Redirects to an OAuth provider. Always throws (the page navigates away). Browser only. */
+/**
+ * Initiates an OAuth login by redirecting to the given provider (e.g., `'google'`, `'github'`).
+ * The page navigates away; this function never returns normally. Browser only.
+ *
+ * After the provider redirects back, call {@link handleAuthCallback} on page load
+ * to complete the login and obtain the {@link User}.
+ *
+ * @throws {AuthError} If called on the server.
+ */
 declare const oauthLogin: (provider: string) => never;
 interface CallbackResult {
     type: 'oauth' | 'confirmation' | 'recovery' | 'invite' | 'email_change';
@@ -76,8 +171,28 @@ interface CallbackResult {
  * Processes the URL hash after an OAuth redirect, email confirmation, password
  * recovery, invite acceptance, or email change. Call on page load. Browser only.
  * Returns `null` if the hash contains no auth parameters.
+ *
+ * Call this early in your app's initialization (e.g., in a layout component or
+ * root loader), **not** inside a route that requires authentication, because
+ * the callback URL must match the page where this function runs.
+ *
+ * For recovery callbacks (`result.type === 'recovery'`), the user is logged in
+ * but has **not** set a new password yet. Your app must check the result type
+ * and redirect to a password form that calls `updateUser({ password })`.
+ * A `'recovery'` event (not `'login'`) is emitted via {@link onAuthChange}.
+ *
+ * @throws {AuthError} If the callback token is invalid or the verification request fails.
  */
 declare const handleAuthCallback: () => Promise<CallbackResult | null>;
+/**
+ * Hydrates the browser-side gotrue-js session from server-set auth cookies.
+ * Call this on page load when using server-side login to enable browser
+ * account operations (updateUser, verifyEmailChange, etc.).
+ *
+ * No-op if a browser session already exists or no auth cookies are present.
+ * No-op on the server.
+ */
+declare const hydrateSession: () => Promise<User | null>;
 
 declare class AuthError extends Error {
     name: string;
@@ -92,32 +207,122 @@ declare class MissingIdentityError extends Error {
     constructor(message?: string);
 }
 
-/** Sends a password recovery email to the given address. */
+/**
+ * Sends a password recovery email to the given address.
+ *
+ * @throws {AuthError} On network failure or if the request is rejected.
+ */
 declare const requestPasswordRecovery: (email: string) => Promise<void>;
-/** Redeems a recovery token and sets a new password. Logs the user in on success. */
+/**
+ * Redeems a recovery token and sets a new password. Logs the user in on success.
+ *
+ * @throws {AuthError} If the token is invalid, expired, or the update fails.
+ */
 declare const recoverPassword: (token: string, newPassword: string) => Promise<User>;
-/** Confirms an email address using the token from a confirmation email. Logs the user in on success. */
+/**
+ * Confirms an email address using the token from a confirmation email. Logs the user in on success.
+ *
+ * @throws {AuthError} If the token is invalid or expired.
+ */
 declare const confirmEmail: (token: string) => Promise<User>;
-/** Accepts an invite token and sets a password for the new account. Logs the user in on success. */
+/**
+ * Accepts an invite token and sets a password for the new account. Logs the user in on success.
+ *
+ * @throws {AuthError} If the token is invalid or expired.
+ */
 declare const acceptInvite: (token: string, password: string) => Promise<User>;
-/** Verifies an email change using the token from a verification email. */
+/**
+ * Verifies an email change using the token from a verification email.
+ * Auto-hydrates from auth cookies if no browser session exists. Browser only.
+ *
+ * @throws {AuthError} If called on the server, no user is logged in, or the token is invalid.
+ */
 declare const verifyEmailChange: (token: string) => Promise<User>;
-/** Updates the current user's metadata or credentials. Requires an active session. */
-declare const updateUser: (updates: Record<string, unknown>) => Promise<User>;
+/**
+ * Updates the current user's email, password, or user metadata.
+ * Auto-hydrates from auth cookies if no browser session exists.
+ *
+ * @param updates - Fields to update. Pass `email` or `password` to change credentials,
+ *   or `data` to update user metadata (e.g., `{ data: { full_name: 'New Name' } }`).
+ * @throws {AuthError} If no user is logged in or the update fails.
+ */
+declare const updateUser: (updates: UserUpdates) => Promise<User>;
 
-declare const admin: {
+/** The admin namespace for user management operations. */
+interface Admin {
+    /**
+     * Lists all users. Works in both server and browser contexts.
+     *
+     * **Server:** calls GoTrue `GET /admin/users` with the operator token. Pagination
+     * options (`page`, `perPage`) are forwarded as query parameters.
+     *
+     * **Browser:** calls gotrue-js `user.admin.listUsers()`. The logged-in user must
+     * have an admin role. Pagination options are ignored (gotrue-js does not support them).
+     *
+     * @throws {AuthError} If the operator token is missing (server) or no admin user is logged in (browser).
+     */
     listUsers: (options?: {
         page?: number;
         perPage?: number;
     }) => Promise<User[]>;
+    /**
+     * Gets a single user by ID. Works in both server and browser contexts.
+     *
+     * **Server:** calls GoTrue `GET /admin/users/:id` with the operator token.
+     *
+     * **Browser:** calls gotrue-js `user.admin.getUser()`. The logged-in user must
+     * have an admin role.
+     *
+     * @throws {AuthError} If the user is not found, the operator token is missing (server),
+     *   or no admin user is logged in (browser).
+     */
     getUser: (userId: string) => Promise<User>;
+    /**
+     * Creates a new user. The user is auto-confirmed (no confirmation email is sent).
+     * Works in both server and browser contexts.
+     *
+     * The optional `data` fields are spread as **top-level attributes** in the GoTrue
+     * request body (not nested under `user_metadata`). Use this to set `app_metadata`,
+     * `user_metadata`, `role`, or any other GoTrue user field at creation time.
+     *
+     * **Server:** calls GoTrue `POST /admin/users` with the operator token.
+     *
+     * **Browser:** calls gotrue-js `user.admin.createUser()`. The logged-in user must
+     * have an admin role.
+     *
+     * @throws {AuthError} If the email already exists, the operator token is missing (server),
+     *   or no admin user is logged in (browser).
+     */
     createUser: (params: {
         email: string;
         password: string;
         data?: Record<string, unknown>;
     }) => Promise<User>;
-    updateUser: (userId: string, attributes: Record<string, unknown>) => Promise<User>;
+    /**
+     * Updates an existing user by ID. Works in both server and browser contexts.
+     *
+     * **Server:** calls GoTrue `PUT /admin/users/:id` with the operator token.
+     *
+     * **Browser:** calls gotrue-js `user.admin.updateUser()`. The logged-in user must
+     * have an admin role.
+     *
+     * @throws {AuthError} If the user is not found, the update fails, the operator token
+     *   is missing (server), or no admin user is logged in (browser).
+     */
+    updateUser: (userId: string, attributes: AdminUserUpdates) => Promise<User>;
+    /**
+     * Deletes a user by ID. Works in both server and browser contexts.
+     *
+     * **Server:** calls GoTrue `DELETE /admin/users/:id` with the operator token.
+     *
+     * **Browser:** calls gotrue-js `user.admin.deleteUser()`. The logged-in user must
+     * have an admin role.
+     *
+     * @throws {AuthError} If the user is not found, the deletion fails, the operator token
+     *   is missing (server), or no admin user is logged in (browser).
+     */
     deleteUser: (userId: string) => Promise<void>;
-};
+}
+declare const admin: Admin;
 
-export { type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type IdentityConfig, MissingIdentityError, type Settings, type User, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, requestPasswordRecovery, signup, updateUser, verifyEmailChange };
+export { AUTH_EVENTS, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type IdentityConfig, MissingIdentityError, type Settings, type SignupData, type User, type UserUpdates, acceptInvite, admin, confirmEmail, getIdentityConfig, getSettings, getUser, handleAuthCallback, hydrateSession, isAuthenticated, login, logout, oauthLogin, onAuthChange, recoverPassword, requestPasswordRecovery, signup, updateUser, verifyEmailChange };