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

package/dist/index.d.cts

@@ -1,22 +1,59 @@
+/** The supported OAuth and authentication providers. */
 declare const AUTH_PROVIDERS: readonly ["google", "github", "gitlab", "bitbucket", "facebook", "saml", "email"];
+/** A supported authentication provider name (e.g., `'google'`, `'github'`, `'email'`). */
 type AuthProvider = (typeof AUTH_PROVIDERS)[number];
+/**
+ * Provider and role metadata stored in a user's `app_metadata` field.
+ * GoTrue sets `provider` automatically on signup; `roles` controls authorization.
+ * Additional keys may be present depending on your Identity configuration.
+ *
+ * @example
+ * ```ts
+ * const meta: AppMetadata = {
+ *   provider: 'github',
+ *   roles: ['admin'],
+ *   custom_claim: 'value',
+ * }
+ * ```
+ */
 interface AppMetadata {
     provider: AuthProvider;
     roles?: string[];
     [key: string]: unknown;
 }
+/**
+ * Identity endpoint configuration for the current environment.
+ * In the browser, `url` is derived from `window.location.origin`.
+ * On the server, `token` is the operator token for admin operations.
+ */
 interface IdentityConfig {
+    /** The GoTrue API endpoint URL (e.g., `https://example.com/.netlify/identity`). */
     url: string;
+    /** Operator token for server-side admin requests. Only available in Netlify Functions. */
     token?: string;
 }
+/**
+ * Project-level Identity settings returned by {@link getSettings}.
+ * Reflects the configuration in your Netlify dashboard.
+ */
 interface Settings {
+    /** Whether new signups are auto-confirmed (no confirmation email sent). */
     autoconfirm: boolean;
+    /** Whether new signups are disabled entirely. */
     disableSignup: boolean;
+    /** Map of provider names to whether they are enabled. */
     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' } }`).
+ *
+ * @example
+ * ```ts
+ * await updateUser({ data: { full_name: 'Jane Doe' } })
+ * await updateUser({ email: 'new@example.com' })
+ * await updateUser({ password: 'new-password' })
+ * ```
  */
 interface UserUpdates {
     email?: string;
@@ -34,27 +71,95 @@ type SignupData = Record<string, unknown>;
  *
  * Unlike {@link UserUpdates} (used by the self-service `updateUser`), admin updates
  * can set `role`, force-confirm a user, and write to `app_metadata`.
+ *
+ * @example
+ * ```ts
+ * await admin.updateUser(userId, {
+ *   role: 'editor',
+ *   confirm: true,
+ *   app_metadata: { plan: 'pro' },
+ * })
+ * ```
  */
 interface AdminUserUpdates {
     email?: string;
     password?: string;
+    /** The user's role (e.g., `'admin'`, `'editor'`). */
     role?: string;
+    /** Set to `true` to force-confirm the user's email without sending a confirmation email. */
     confirm?: boolean;
+    /** Server-managed metadata. Only writable via admin operations. */
     app_metadata?: Record<string, unknown>;
+    /** User-managed metadata (display name, avatar, preferences, etc.). */
     user_metadata?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * Options for {@link admin.listUsers}. Only used on the server;
+ * pagination is ignored in the browser (gotrue-js limitation).
+ */
+interface ListUsersOptions {
+    /** 1-based page number. */
+    page?: number;
+    /** Number of users per page. */
+    perPage?: number;
+}
+/**
+ * Parameters for {@link admin.createUser}.
+ *
+ * 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 other GoTrue user fields at creation time.
+ *
+ * @example
+ * ```ts
+ * await admin.createUser({
+ *   email: 'jane@example.com',
+ *   password: 'secret',
+ *   data: { role: 'editor', user_metadata: { full_name: 'Jane Doe' } },
+ * })
+ * ```
+ */
+interface CreateUserParams {
+    email: string;
+    password: string;
+    /** Additional GoTrue user fields spread into the request body. */
+    data?: Record<string, unknown>;
+}
 
+/**
+ * A normalized user object returned by all auth and admin functions.
+ * Provides a consistent shape regardless of whether the user was loaded
+ * from gotrue-js, a JWT cookie, or the server-side identity context.
+ *
+ * @example
+ * ```ts
+ * const user = getUser()
+ * if (user) {
+ *   console.log(user.email, user.name, user.provider)
+ * }
+ * ```
+ */
 interface User {
+    /** The user's unique identifier (GoTrue UUID). */
     id: string;
+    /** The user's email address. */
     email?: string;
+    /** `true` if the user's email has been confirmed. */
     emailVerified?: boolean;
+    /** ISO 8601 timestamp of when the account was created. */
     createdAt?: string;
+    /** ISO 8601 timestamp of the last account update. */
     updatedAt?: string;
+    /** The authentication provider used to create the account. */
     provider?: AuthProvider;
+    /** Display name from `user_metadata.full_name` or `user_metadata.name`. */
     name?: string;
+    /** Avatar URL from `user_metadata.avatar_url`. */
     pictureUrl?: string;
+    /** The full `user_metadata` object. */
     metadata?: Record<string, unknown>;
+    /** The raw GoTrue user data, for accessing fields not mapped to this interface. */
     rawGoTrueData?: Record<string, unknown>;
 }
 /**
@@ -91,6 +196,18 @@ declare const getIdentityConfig: () => IdentityConfig | null;
  */
 declare const getSettings: () => Promise<Settings>;
 
+/**
+ * Constants for the auth events emitted by the library.
+ * Use these instead of string literals when comparing event types.
+ *
+ * @example
+ * ```ts
+ * onAuthChange((event, user) => {
+ *   if (event === AUTH_EVENTS.LOGIN) console.log('Logged in:', user)
+ *   if (event === AUTH_EVENTS.RECOVERY) redirect('/reset-password')
+ * })
+ * ```
+ */
 declare const AUTH_EVENTS: {
     readonly LOGIN: "login";
     readonly LOGOUT: "logout";
@@ -98,7 +215,15 @@ declare const AUTH_EVENTS: {
     readonly USER_UPDATED: "user_updated";
     readonly RECOVERY: "recovery";
 };
+/**
+ * Union of all auth event names: `'login' | 'logout' | 'token_refresh' | 'user_updated' | 'recovery'`.
+ * Passed as the first argument to {@link AuthCallback} subscribers.
+ */
 type AuthEvent = (typeof AUTH_EVENTS)[keyof typeof AUTH_EVENTS];
+/**
+ * Callback function signature for {@link onAuthChange} subscribers.
+ * `user` is `null` on logout events.
+ */
 type AuthCallback = (event: AuthEvent, user: User | null) => void;
 /**
  * Subscribes to auth state changes (login, logout, token refresh, user updates,
@@ -162,9 +287,31 @@ declare const logout: () => Promise<void>;
  * @throws {AuthError} If called on the server.
  */
 declare const oauthLogin: (provider: string) => never;
+/**
+ * Result returned by {@link handleAuthCallback} after processing a URL hash.
+ *
+ * - `'oauth'`: OAuth provider redirect completed. `user` is the authenticated user.
+ * - `'confirmation'`: Email confirmed via token. `user` is the confirmed user.
+ * - `'recovery'`: Password recovery token redeemed. `user` is logged in but must set a new password.
+ * - `'invite'`: Invite token found. `user` is `null`; `token` contains the invite token for {@link acceptInvite}.
+ * - `'email_change'`: Email change verified. `user` reflects the updated email.
+ *
+ * @example
+ * ```ts
+ * const result = await handleAuthCallback()
+ * if (result?.type === 'recovery') {
+ *   redirect('/reset-password')
+ * } else if (result?.type === 'invite') {
+ *   redirect(`/join?token=${result.token}`)
+ * }
+ * ```
+ */
 interface CallbackResult {
+    /** The type of auth callback that was processed. */
     type: 'oauth' | 'confirmation' | 'recovery' | 'invite' | 'email_change';
+    /** The authenticated user, or `null` for invite callbacks. */
     user: User | null;
+    /** The invite token, only present when `type` is `'invite'`. */
     token?: string;
 }
 /**
@@ -194,61 +341,53 @@ declare const handleAuthCallback: () => Promise<CallbackResult | null>;
  */
 declare const hydrateSession: () => Promise<User | null>;
 
+/**
+ * Thrown by auth operations when something goes wrong: invalid credentials,
+ * network failures, missing runtime context, etc.
+ *
+ * The `status` field contains the HTTP status code from GoTrue when available
+ * (e.g., 401 for bad credentials, 422 for validation errors).
+ * The `cause` field preserves the original error for debugging.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await login(email, password)
+ * } catch (error) {
+ *   if (error instanceof AuthError) {
+ *     console.error(error.message, error.status)
+ *   }
+ * }
+ * ```
+ */
 declare class AuthError extends Error {
     name: string;
+    /** HTTP status code from GoTrue, if the error originated from an API response. */
     status?: number;
     cause?: unknown;
     constructor(message: string, status?: number, options?: {
         cause?: unknown;
     });
 }
+/**
+ * Thrown when a function requires a gotrue-js client but Netlify Identity
+ * is not configured (no endpoint URL could be discovered).
+ *
+ * This typically means the site does not have Identity enabled, or the app
+ * is not running via `netlify dev` / deployed on Netlify.
+ */
 declare class MissingIdentityError extends Error {
     name: string;
     constructor(message?: string);
 }
 
 /**
- * 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.
- *
- * @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.
- *
- * @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.
- *
- * @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.
- * 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 email, password, or user metadata.
- * Auto-hydrates from auth cookies if no browser session exists.
+ * The admin namespace for privileged user management operations.
+ * All methods work in both server and browser contexts.
  *
- * @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.
+ * **Server:** uses the operator token (automatically available in Netlify Functions).
+ * **Browser:** requires a logged-in user with an admin role.
  */
-declare const updateUser: (updates: UserUpdates) => Promise<User>;
-
-/** The admin namespace for user management operations. */
 interface Admin {
     /**
      * Lists all users. Works in both server and browser contexts.
@@ -261,10 +400,7 @@ interface Admin {
      *
      * @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[]>;
+    listUsers: (options?: ListUsersOptions) => Promise<User[]>;
     /**
      * Gets a single user by ID. Works in both server and browser contexts.
      *
@@ -293,11 +429,7 @@ interface Admin {
      * @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>;
+    createUser: (params: CreateUserParams) => Promise<User>;
     /**
      * Updates an existing user by ID. Works in both server and browser contexts.
      *
@@ -325,4 +457,45 @@ interface Admin {
 }
 declare const admin: Admin;
 
-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 };
+/**
+ * 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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ * 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 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>;
+
+export { AUTH_EVENTS, type Admin, type AdminUserUpdates, type AppMetadata, type AuthCallback, AuthError, type AuthEvent, type AuthProvider, type CallbackResult, type CreateUserParams, type IdentityConfig, type ListUsersOptions, 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 };