@nauth-toolkit/client 0.1.14 → 0.1.17

package/dist/index.d.ts

@@ -1,6 +1,19 @@
+/**
+ * MFA device method type (methods that require device setup).
+ * Excludes 'backup' as it's not a device method.
+ */
 type MFADeviceMethod = 'sms' | 'email' | 'totp' | 'passkey';
+/**
+ * All MFA methods including backup codes (for verification).
+ */
 type MFAMethod = MFADeviceMethod | 'backup';
+/**
+ * MFA challenge method subset (for challenge-data retrieval).
+ */
 type MFAChallengeMethod = 'passkey' | 'sms' | 'email' | 'totp' | 'backup';
+/**
+ * MFA status for authenticated user.
+ */
 interface MFAStatus {
     enabled: boolean;
     required: boolean;
@@ -12,6 +25,9 @@ interface MFAStatus {
     mfaExemptReason: string | null;
     mfaExemptGrantedAt: string | Date | null;
 }
+/**
+ * MFA device information.
+ */
 interface MFADevice {
     id: number;
     type: MFADeviceMethod;
@@ -20,6 +36,9 @@ interface MFADevice {
     isActive: boolean;
     createdAt: string | Date;
 }
+/**
+ * MFA setup data returned by providers.
+ */
 interface MFASetupData {
     secret?: string;
     qrCode?: string;
@@ -28,16 +47,30 @@ interface MFASetupData {
     challenge?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/**
+ * Response from getSetupData API call.
+ * Contains provider-specific MFA setup information.
+ */
 interface GetSetupDataResponse {
     setupData: Record<string, unknown>;
 }
+/**
+ * Response from getChallengeData API call.
+ * Contains challenge-specific data (e.g., passkey options).
+ */
 interface GetChallengeDataResponse {
     challengeData: Record<string, unknown>;
 }
+/**
+ * Backup codes response.
+ */
 interface BackupCodesResponse {
     codes: string[];
 }
 
+/**
+ * Authentication challenge types returned by the backend.
+ */
 declare enum AuthChallenge {
     VERIFY_EMAIL = "VERIFY_EMAIL",
     VERIFY_PHONE = "VERIFY_PHONE",
@@ -59,6 +92,9 @@ interface AuthResponse {
     challengeParameters?: Record<string, unknown>;
     userSub?: string;
 }
+/**
+ * Minimal user information returned inside auth responses.
+ */
 interface AuthUserSummary {
     sub: string;
     email: string;
@@ -70,12 +106,18 @@ interface AuthUserSummary {
     socialProviders?: string[] | null;
     hasPasswordHash?: boolean;
 }
+/**
+ * Token response returned by refresh endpoint.
+ */
 interface TokenResponse {
     accessToken: string;
     refreshToken: string;
     accessTokenExpiresAt: number;
     refreshTokenExpiresAt: number;
 }
+/**
+ * Signup request payload.
+ */
 interface SignupRequest {
     email: string;
     password: string;
@@ -84,30 +126,58 @@ interface SignupRequest {
     phone?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Login request payload.
+ */
 interface LoginRequest {
     identifier: string;
     password: string;
 }
+/**
+ * Logout request payload.
+ */
 interface LogoutRequest {
     sub?: string;
     forgetMe?: boolean;
 }
+/**
+ * Logout all sessions request payload.
+ */
 interface LogoutAllRequest {
+    /**
+     * Whether to also revoke all trusted devices
+     * Default: false (devices remain trusted)
+     */
     forgetDevices?: boolean;
     sub?: string;
 }
+/**
+ * Resend code request payload.
+ */
 interface ResendCodeRequest {
     session: string;
 }
+/**
+ * MFA setup data request payload during challenge flows.
+ */
 interface GetSetupDataRequest {
     session: string;
     method: MFAMethod;
 }
+/**
+ * Challenge data request payload (e.g., passkey options).
+ */
 interface GetChallengeDataRequest {
     session: string;
     method: MFAChallengeMethod;
 }
+/**
+ * Unified challenge response discriminated union.
+ */
 type ChallengeResponse = VerifyEmailResponse | VerifyPhoneCollectResponse | VerifyPhoneCodeResponse | MFACodeResponse | MFAPasskeyResponse | MFASetupResponse | ForceChangePasswordResponse;
+/**
+ * Base challenge response shape.
+ */
 interface BaseChallengeResponse {
     session: string;
 }
@@ -143,6 +213,9 @@ interface ForceChangePasswordResponse extends BaseChallengeResponse {
     newPassword: string;
 }
 
+/**
+ * Full user profile returned from profile endpoints.
+ */
 interface AuthUser {
     sub: string;
     email: string;
@@ -159,51 +232,87 @@ interface AuthUser {
     createdAt?: string | Date;
     updatedAt?: string | Date;
 }
+/**
+ * Profile update request.
+ */
 interface UpdateProfileRequest {
     firstName?: string;
     lastName?: string;
     email?: string;
     phone?: string;
 }
+/**
+ * Change password request.
+ */
 interface ChangePasswordRequest {
     currentPassword: string;
     newPassword: string;
 }
+/**
+ * Forgot password request payload.
+ */
 interface ForgotPasswordRequest {
     identifier: string;
 }
+/**
+ * Forgot password response payload.
+ */
 interface ForgotPasswordResponse {
     success: boolean;
     destination?: string;
     deliveryMedium?: 'email' | 'sms';
     expiresIn?: number;
 }
+/**
+ * Confirm forgot password request payload.
+ */
 interface ConfirmForgotPasswordRequest {
     identifier: string;
     code: string;
     newPassword: string;
 }
+/**
+ * Confirm forgot password response payload.
+ */
 interface ConfirmForgotPasswordResponse {
     success: boolean;
     mustChangePassword: boolean;
 }
 
+/**
+ * Social provider identifiers.
+ */
 type SocialProvider = 'google' | 'apple' | 'facebook';
+/**
+ * Request to obtain social auth URL.
+ */
 interface SocialAuthUrlRequest {
     provider: SocialProvider;
     state?: string;
 }
+/**
+ * Response containing social auth URL.
+ */
 interface SocialAuthUrlResponse {
     url: string;
 }
+/**
+ * Social callback parameters.
+ */
 interface SocialCallbackRequest {
     provider: SocialProvider;
     code: string;
     state: string;
 }
+/**
+ * Linked social accounts response.
+ */
 interface LinkedAccountsResponse {
     providers: SocialProvider[];
 }
+/**
+ * Native social verification request (mobile).
+ */
 interface SocialVerifyRequest {
     provider: SocialProvider;
     idToken?: string;
@@ -211,6 +320,9 @@ interface SocialVerifyRequest {
     authorizationCode?: string;
 }
 
+/**
+ * Standardized error codes mirroring backend AuthErrorCode.
+ */
 declare enum NAuthErrorCode {
     AUTH_INVALID_CREDENTIALS = "AUTH_INVALID_CREDENTIALS",
     AUTH_ACCOUNT_LOCKED = "AUTH_ACCOUNT_LOCKED",
@@ -268,6 +380,9 @@ declare enum NAuthErrorCode {
     INTERNAL_ERROR = "INTERNAL_ERROR",
     SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
 }
+/**
+ * Structured client error.
+ */
 interface NAuthError {
     code: NAuthErrorCode;
     message: string;
@@ -276,30 +391,121 @@ interface NAuthError {
     statusCode?: number;
 }
 
+/**
+ * Storage adapter interface used by the client SDK.
+ */
 interface NAuthStorageAdapter {
+    /**
+     * Retrieve a value by key.
+     */
     getItem(key: string): Promise<string | null>;
+    /**
+     * Persist a value.
+     */
     setItem(key: string, value: string): Promise<void>;
+    /**
+     * Remove a stored value.
+     */
     removeItem(key: string): Promise<void>;
 }
 
+/**
+ * HTTP request configuration.
+ *
+ * Platform-agnostic request format that can be implemented by any HTTP client.
+ */
 interface HttpRequest {
+    /**
+     * HTTP method
+     */
     method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /**
+     * Full URL (already resolved with baseUrl)
+     */
     url: string;
+    /**
+     * Request headers
+     */
     headers?: Record<string, string>;
+    /**
+     * Request body (will be JSON stringified by adapter)
+     */
     body?: unknown;
+    /**
+     * Credentials mode for cookies
+     * - 'include': Send cookies (for cookies mode)
+     * - 'omit': Don't send cookies (for JSON mode)
+     */
     credentials?: 'include' | 'omit' | 'same-origin';
+    /**
+     * Abort signal for request cancellation
+     */
     signal?: AbortSignal;
 }
+/**
+ * HTTP response returned by adapter.
+ */
 interface HttpResponse<T> {
+    /**
+     * Response data (already parsed)
+     */
     data: T;
+    /**
+     * HTTP status code
+     */
     status: number;
+    /**
+     * Response headers
+     */
     headers: Record<string, string>;
 }
+/**
+ * Platform-agnostic HTTP adapter interface.
+ *
+ * Implementations:
+ * - FetchAdapter: For vanilla JS, Node.js (uses native fetch)
+ * - AngularHttpAdapter: For Angular (uses HttpClient)
+ * - AxiosAdapter: For React/Vue (uses Axios)
+ *
+ * @example
+ * ```typescript
+ * class MyAdapter implements HttpAdapter {
+ *   async request<T>(config: HttpRequest): Promise<HttpResponse<T>> {
+ *     // Use any HTTP client
+ *     const response = await myHttpClient.request(config);
+ *     return { data: response.data, status: response.status, headers: {} };
+ *   }
+ * }
+ * ```
+ */
 interface HttpAdapter {
+    /**
+     * Execute an HTTP request.
+     *
+     * @param config - Request configuration
+     * @returns Response with data, status, and headers
+     * @throws Error if request fails (adapter should throw descriptive errors)
+     */
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }
 
+/**
+ * Token delivery mode for the frontend SDK.
+ *
+ * - `'cookies'` - For web applications. Tokens sent as httpOnly cookies by backend.
+ *   Uses `withCredentials`, CSRF tokens, no Authorization header.
+ *
+ * - `'json'` - For mobile/native apps (Capacitor, React Native). Tokens returned
+ *   in response body, stored locally, sent via Authorization header.
+ *
+ * Note: "Hybrid" is a backend deployment pattern (supporting both web and mobile
+ * via separate endpoints), not a frontend mode. The frontend chooses ONE mode
+ * based on whether it's a web or mobile build.
+ */
 type TokenDeliveryMode = 'json' | 'cookies';
+/**
+ * Endpoint paths for the client SDK.
+ */
 interface NAuthEndpoints {
     login: string;
     signup: string;
@@ -334,35 +540,116 @@ interface NAuthEndpoints {
     auditHistory: string;
     updateProfile: string;
 }
+/**
+ * Client configuration.
+ */
 interface NAuthClientConfig {
+    /**
+     * Base URL for authentication API.
+     *
+     * For web apps using cookies: `'https://api.example.com/auth'`
+     * For mobile apps using JSON: `'https://api.example.com/mobile/auth'`
+     *
+     * When backend uses hybrid deployment, mobile apps should use a different
+     * base URL that points to the JSON-based mobile auth endpoints.
+     */
     baseUrl: string;
+    /**
+     * How tokens are delivered between client and server.
+     *
+     * - `'cookies'` - For web apps. Backend sets httpOnly cookies.
+     * - `'json'` - For mobile apps. Tokens in response body, stored locally.
+     */
     tokenDelivery: TokenDeliveryMode;
+    /** Custom storage adapter. Defaults to localStorage (web) or memory (SSR). */
     storage?: NAuthStorageAdapter;
+    /**
+     * CSRF configuration (required for cookies mode).
+     * Default cookie name: 'csrf_token', header name: 'x-csrf-token'
+     */
     csrf?: {
         cookieName?: string;
         headerName?: string;
     };
+    /** Custom endpoint paths (merged with defaults). */
     endpoints?: Partial<NAuthEndpoints>;
+    /** Device trust configuration for "remember this device" feature. */
     deviceTrust?: {
         headerName?: string;
         storageKey?: string;
     };
+    /** Additional headers to include in all requests. */
     headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Default: 30000 */
     timeout?: number;
+    /**
+     * Redirect URLs for various authentication scenarios.
+     * Used by guards and interceptors to handle routing in a platform-agnostic way.
+     */
     redirects?: {
+        /**
+         * URL to redirect to after successful authentication (login, signup, or OAuth).
+         * @default '/'
+         */
         success?: string;
+        /**
+         * URL to redirect to when session expires (refresh fails with 401).
+         * @default '/login'
+         */
         sessionExpired?: string;
+        /**
+         * URL to redirect to when OAuth authentication fails.
+         * @default '/login'
+         */
         oauthError?: string;
+        /**
+         * Base URL for challenge routes (email verification, MFA, etc.).
+         * The challenge type will be appended (e.g., '/auth/challenge/verify-email').
+         * @default '/auth/challenge'
+         */
         challengeBase?: string;
     };
+    /**
+     * Called when session expires (refresh fails with 401).
+     */
     onSessionExpired?: () => void;
+    /** Called after successful token refresh. */
     onTokenRefresh?: () => void;
+    /** Called when authentication state changes (login/logout). */
     onAuthStateChange?: (user: AuthUser | null) => void;
+    /** Called on authentication errors. */
     onError?: (error: NAuthError) => void;
+    /** Enable debug logging. */
     debug?: boolean;
+    /**
+     * HTTP adapter for making requests.
+     *
+     * - **Auto-provided in Angular**: Uses HttpClient (works with interceptors)
+     * - **Manual setup in React/Vue**: Provide AxiosAdapter or custom adapter
+     * - **Defaults to FetchAdapter**: If not provided, uses native fetch
+     *
+     * @example
+     * ```typescript
+     * // Angular (automatic)
+     * // AuthService auto-injects AngularHttpAdapter
+     *
+     * // React with Axios
+     * const client = new NAuthClient({
+     *   httpAdapter: new AxiosAdapter(axiosInstance),
+     * });
+     *
+     * // Vanilla JS (auto-defaults to fetch)
+     * const client = new NAuthClient({
+     *   // httpAdapter auto-defaults to FetchAdapter
+     * });
+     * ```
+     */
     httpAdapter?: HttpAdapter;
 }
 
+/**
+ * Audit event types.
+ */
 declare enum AuthAuditEventType {
     LOGIN_SUCCESS = "LOGIN_SUCCESS",
     LOGIN_FAILED = "LOGIN_FAILED",
@@ -390,7 +677,13 @@ declare enum AuthAuditEventType {
     SOCIAL_LINK_FAILED = "SOCIAL_LINK_FAILED",
     SOCIAL_UNLINK = "SOCIAL_UNLINK"
 }
+/**
+ * Audit event status.
+ */
 type AuthAuditEventStatus = 'SUCCESS' | 'FAILURE' | 'INFO' | 'SUSPICIOUS';
+/**
+ * Individual audit event record.
+ */
 interface AuthAuditEvent {
     id: number;
     userId: number;
@@ -419,6 +712,9 @@ interface AuthAuditEvent {
     metadata?: Record<string, unknown> | null;
     createdAt: string | Date;
 }
+/**
+ * Paginated audit history response.
+ */
 interface AuditHistoryResponse {
     data: AuthAuditEvent[];
     total: number;
@@ -427,21 +723,94 @@ interface AuditHistoryResponse {
     totalPages: number;
 }
 
+/**
+ * Client-side error wrapper for SDK operations.
+ *
+ * Mirrors the backend NAuthException structure for consistent error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.login({ identifier: 'user@example.com', password: 'wrong' });
+ * } catch (error) {
+ *   if (error instanceof NAuthClientError) {
+ *     console.log(error.code); // 'AUTH_INVALID_CREDENTIALS'
+ *     console.log(error.message); // 'Invalid credentials'
+ *     console.log(error.timestamp); // '2025-12-06T...'
+ *
+ *     // Check specific error code
+ *     if (error.isCode(NAuthErrorCode.RATE_LIMIT_LOGIN)) {
+ *       const retryAfter = error.details?.retryAfter as number;
+ *       console.log(`Rate limited. Retry in ${retryAfter}s`);
+ *     }
+ *   }
+ * }
+ * ```
+ */
 declare class NAuthClientError extends Error implements NAuthError {
     readonly code: NAuthErrorCode;
     readonly details?: Record<string, unknown>;
     readonly statusCode?: number;
     readonly timestamp: string;
     readonly isNetworkError: boolean;
+    /**
+     * Create a new client error.
+     *
+     * @param code - Error code from NAuthErrorCode enum
+     * @param message - Human-readable error message
+     * @param options - Optional metadata including details, statusCode, timestamp, and network error flag
+     */
     constructor(code: NAuthErrorCode, message: string, options?: {
         details?: Record<string, unknown>;
         statusCode?: number;
         timestamp?: string;
         isNetworkError?: boolean;
     });
+    /**
+     * Check if error matches a specific error code.
+     *
+     * @param code - Error code to check against
+     * @returns True if the error code matches
+     *
+     * @example
+     * ```typescript
+     * if (error.isCode(NAuthErrorCode.RATE_LIMIT_SMS)) {
+     *   // Handle SMS rate limit
+     * }
+     * ```
+     */
     isCode(code: NAuthErrorCode): boolean;
+    /**
+     * Get error details/metadata.
+     *
+     * @returns Error details object or undefined
+     *
+     * @example
+     * ```typescript
+     * const details = error.getDetails();
+     * if (details?.retryAfter) {
+     *   console.log(`Retry after ${details.retryAfter} seconds`);
+     * }
+     * ```
+     */
     getDetails(): Record<string, unknown> | undefined;
+    /**
+     * Get the error code.
+     *
+     * @returns The error code enum value
+     */
     getCode(): NAuthErrorCode;
+    /**
+     * Serialize error to JSON object.
+     *
+     * @returns Plain object representation
+     *
+     * @example
+     * ```typescript
+     * const errorJson = error.toJSON();
+     * // { code: 'AUTH_INVALID_CREDENTIALS', message: '...', timestamp: '...', details: {...} }
+     * ```
+     */
     toJSON(): {
         code: string;
         message: string;
@@ -451,8 +820,22 @@ declare class NAuthClientError extends Error implements NAuthError {
     };
 }
 
+/**
+ * Authentication event types emitted by NAuthClient
+ *
+ * Events are emitted throughout the authentication lifecycle,
+ * allowing applications to react to auth state changes.
+ */
 type AuthEventType = 'auth:login' | 'auth:signup' | 'auth:success' | 'auth:challenge' | 'auth:error' | 'auth:logout' | 'auth:refresh' | 'oauth:started' | 'oauth:callback' | 'oauth:completed' | 'oauth:error';
+/**
+ * Discriminated union of all authentication events with type-safe payloads
+ *
+ * Each event has a specific payload type for better type safety.
+ */
 type AuthEvent = AuthLoginEvent | AuthSignupEvent | AuthSuccessEvent | AuthChallengeEvent | AuthErrorEvent | AuthLogoutEvent | AuthRefreshEvent | OAuthStartedEvent | OAuthCallbackEvent | OAuthCompletedEvent | OAuthErrorEvent;
+/**
+ * Login initiated event
+ */
 interface AuthLoginEvent {
     type: 'auth:login';
     data: {
@@ -460,6 +843,9 @@ interface AuthLoginEvent {
     };
     timestamp: number;
 }
+/**
+ * Signup initiated event
+ */
 interface AuthSignupEvent {
     type: 'auth:signup';
     data: {
@@ -467,21 +853,33 @@ interface AuthSignupEvent {
     };
     timestamp: number;
 }
+/**
+ * Successful authentication event
+ */
 interface AuthSuccessEvent {
     type: 'auth:success';
     data: AuthResponse;
     timestamp: number;
 }
+/**
+ * Challenge required event
+ */
 interface AuthChallengeEvent {
     type: 'auth:challenge';
     data: AuthResponse;
     timestamp: number;
 }
+/**
+ * Authentication error event
+ */
 interface AuthErrorEvent {
     type: 'auth:error';
     data: NAuthClientError;
     timestamp: number;
 }
+/**
+ * User logged out event
+ */
 interface AuthLogoutEvent {
     type: 'auth:logout';
     data: {
@@ -490,6 +888,9 @@ interface AuthLogoutEvent {
     };
     timestamp: number;
 }
+/**
+ * Token refreshed event
+ */
 interface AuthRefreshEvent {
     type: 'auth:refresh';
     data: {
@@ -497,6 +898,9 @@ interface AuthRefreshEvent {
     };
     timestamp: number;
 }
+/**
+ * OAuth flow started event
+ */
 interface OAuthStartedEvent {
     type: 'oauth:started';
     data: {
@@ -504,6 +908,9 @@ interface OAuthStartedEvent {
     };
     timestamp: number;
 }
+/**
+ * OAuth callback received event
+ */
 interface OAuthCallbackEvent {
     type: 'oauth:callback';
     data: {
@@ -511,114 +918,509 @@ interface OAuthCallbackEvent {
     };
     timestamp: number;
 }
+/**
+ * OAuth flow completed event
+ */
 interface OAuthCompletedEvent {
     type: 'oauth:completed';
     data: AuthResponse;
     timestamp: number;
 }
+/**
+ * OAuth error event
+ */
 interface OAuthErrorEvent {
     type: 'oauth:error';
     data: NAuthClientError;
     timestamp: number;
 }
+/**
+ * Event listener callback function
+ */
 type AuthEventListener = (event: AuthEvent) => void;
+/**
+ * Internal event emitter for authentication events
+ *
+ * Provides pub/sub functionality for auth lifecycle events.
+ *
+ * @internal
+ */
 declare class EventEmitter {
     private listeners;
+    /**
+     * Subscribe to an authentication event
+     *
+     * @param event - Event type or '*' for all events
+     * @param listener - Callback function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = emitter.on('auth:success', (event) => {
+     *   console.log('User logged in:', event.data);
+     * });
+     *
+     * // Later
+     * unsubscribe();
+     * ```
+     */
     on(event: AuthEventType | '*', listener: AuthEventListener): () => void;
+    /**
+     * Unsubscribe from an authentication event
+     *
+     * @param event - Event type or '*'
+     * @param listener - Callback function to remove
+     */
     off(event: AuthEventType | '*', listener: AuthEventListener): void;
+    /**
+     * Emit an authentication event
+     *
+     * Notifies all listeners for the specific event type and wildcard listeners.
+     *
+     * @param event - Event to emit
+     * @internal
+     */
     emit(event: AuthEvent): void;
+    /**
+     * Remove all listeners
+     *
+     * @internal
+     */
     clear(): void;
 }
 
+/**
+ * Primary client for interacting with nauth-toolkit backend.
+ */
 declare class NAuthClient {
     private readonly config;
     private readonly tokenManager;
     private readonly eventEmitter;
     private currentUser;
+    /**
+     * Create a new client instance.
+     *
+     * @param userConfig - Client configuration
+     */
     constructor(userConfig: NAuthClientConfig);
+    /**
+     * Clean up resources.
+     */
     dispose(): void;
+    /**
+     * Login with identifier and password.
+     */
     login(identifier: string, password: string): Promise<AuthResponse>;
+    /**
+     * Signup with credentials.
+     */
     signup(payload: SignupRequest): Promise<AuthResponse>;
+    /**
+     * Refresh tokens manually.
+     */
     refreshTokens(): Promise<TokenResponse>;
+    /**
+     * Logout current session.
+     *
+     * Uses GET request to avoid CSRF token issues.
+     *
+     * @param forgetDevice - If true, also untrust the device (require MFA on next login)
+     */
     logout(forgetDevice?: boolean): Promise<void>;
+    /**
+     * Logout all sessions.
+     *
+     * Revokes all active sessions for the current user across all devices.
+     * Optionally revokes all trusted devices if forgetDevices is true.
+     *
+     * @param forgetDevices - If true, also revokes all trusted devices (default: false)
+     * @returns Number of sessions revoked
+     */
     logoutAll(forgetDevices?: boolean): Promise<{
         revokedCount: number;
     }>;
+    /**
+     * Respond to a challenge.
+     *
+     * Validates challenge response data before sending to backend.
+     * Provides helpful error messages for common validation issues.
+     *
+     * @param response - Challenge response data
+     * @returns Auth response from backend
+     * @throws {NAuthClientError} If validation fails
+     */
     respondToChallenge(response: ChallengeResponse): Promise<AuthResponse>;
+    /**
+     * Resend a challenge code.
+     */
     resendCode(session: string): Promise<{
         destination: string;
     }>;
+    /**
+     * Get setup data for MFA.
+     *
+     * Returns method-specific setup information:
+     * - TOTP: { secret, qrCode, manualEntryKey }
+     * - SMS: { maskedPhone }
+     * - Email: { maskedEmail }
+     * - Passkey: WebAuthn registration options
+     *
+     * @param session - Challenge session token
+     * @param method - MFA method to set up
+     * @returns Setup data wrapped in GetSetupDataResponse
+     */
     getSetupData(session: string, method: GetSetupDataRequest['method']): Promise<GetSetupDataResponse>;
+    /**
+     * Get challenge data (e.g., WebAuthn options).
+     *
+     * Returns challenge-specific data for verification flows.
+     *
+     * @param session - Challenge session token
+     * @param method - Challenge method to get data for
+     * @returns Challenge data wrapped in GetChallengeDataResponse
+     */
     getChallengeData(session: string, method: GetChallengeDataRequest['method']): Promise<GetChallengeDataResponse>;
+    /**
+     * Get current user profile.
+     */
     getProfile(): Promise<AuthUser>;
+    /**
+     * Update user profile.
+     */
     updateProfile(updates: UpdateProfileRequest): Promise<AuthUser>;
+    /**
+     * Change user password.
+     */
     changePassword(oldPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Request a password reset code (forgot password).
+     */
     forgotPassword(identifier: string): Promise<ForgotPasswordResponse>;
+    /**
+     * Confirm a password reset code and set a new password.
+     */
     confirmForgotPassword(identifier: string, code: string, newPassword: string): Promise<ConfirmForgotPasswordResponse>;
+    /**
+     * Request password change (must change on next login).
+     */
     requestPasswordChange(): Promise<void>;
+    /**
+     * Get MFA status.
+     */
     getMfaStatus(): Promise<MFAStatus>;
+    /**
+     * Get MFA devices.
+     */
     getMfaDevices(): Promise<unknown[]>;
+    /**
+     * Setup MFA device (authenticated user).
+     */
     setupMfaDevice(method: string): Promise<unknown>;
+    /**
+     * Verify MFA setup (authenticated user).
+     */
     verifyMfaSetup(method: string, setupData: Record<string, unknown>, deviceName?: string): Promise<{
         deviceId: number;
     }>;
+    /**
+     * Remove MFA method.
+     */
     removeMfaDevice(method: string): Promise<{
         message: string;
     }>;
+    /**
+     * Set preferred MFA method.
+     *
+     * @param method - Device method to set as preferred ('totp', 'sms', 'email', or 'passkey'). Cannot be 'backup'.
+     * @returns Success message
+     */
     setPreferredMfaMethod(method: 'totp' | 'sms' | 'email' | 'passkey'): Promise<{
         message: string;
     }>;
+    /**
+     * Generate backup codes.
+     */
     generateBackupCodes(): Promise<string[]>;
+    /**
+     * Set MFA exemption (admin/test scenarios).
+     */
     setMfaExemption(exempt: boolean, reason?: string): Promise<void>;
+    /**
+     * Subscribe to authentication events.
+     *
+     * Emits events throughout the auth lifecycle for custom logic, analytics, or UI updates.
+     *
+     * @param event - Event type to listen for, or '*' for all events
+     * @param listener - Callback function to handle the event
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * // Listen to successful authentication
+     * const unsubscribe = client.on('auth:success', (event) => {
+     *   console.log('User logged in:', event.data.user);
+     *   analytics.track('login_success');
+     * });
+     *
+     * // Listen to all events
+     * client.on('*', (event) => {
+     *   console.log('Auth event:', event.type, event.data);
+     * });
+     *
+     * // Unsubscribe when done
+     * unsubscribe();
+     * ```
+     */
     on(event: AuthEventType | '*', listener: AuthEventListener): () => void;
+    /**
+     * Unsubscribe from authentication events.
+     *
+     * @param event - Event type
+     * @param listener - Callback function to remove
+     */
     off(event: AuthEventType | '*', listener: AuthEventListener): void;
+    /**
+     * Start social OAuth flow with automatic state management.
+     *
+     * Generates a secure state token, stores OAuth context, and redirects to the OAuth provider.
+     * After OAuth callback, use `handleOAuthCallback()` to complete authentication.
+     *
+     * @param provider - OAuth provider ('google', 'apple', 'facebook')
+     * @param options - Optional configuration
+     *
+     * @example
+     * ```typescript
+     * // Simple usage
+     * await client.loginWithSocial('google');
+     *
+     * // With custom redirect URI
+     * await client.loginWithSocial('apple', {
+     *   redirectUri: 'https://example.com/auth/callback'
+     * });
+     * ```
+     */
     loginWithSocial(provider: SocialProvider, _options?: {
         redirectUri?: string;
     }): Promise<void>;
+    /**
+     * Auto-detect and handle OAuth callback.
+     *
+     * Call this on app initialization or in callback route.
+     * Returns null if not an OAuth callback (no provider/code params).
+     *
+     * The SDK validates the state token, completes authentication via backend,
+     * and emits appropriate events.
+     *
+     * @param urlOrParams - Optional URL string or URLSearchParams (auto-detects from window.location if not provided)
+     * @returns AuthResponse if OAuth callback detected, null otherwise
+     *
+     * @example
+     * ```typescript
+     * // Auto-detect on app init
+     * const response = await client.handleOAuthCallback();
+     * if (response) {
+     *   if (response.challengeName) {
+     *     router.navigate(['/challenge', response.challengeName]);
+     *   } else {
+     *     router.navigate(['/']); // Navigate to your app's home route
+     *   }
+     * }
+     *
+     * // In callback route
+     * const response = await client.handleOAuthCallback(window.location.search);
+     * ```
+     */
     handleOAuthCallback(urlOrParams?: string | URLSearchParams): Promise<AuthResponse | null>;
+    /**
+     * Get social auth URL (low-level API).
+     *
+     * For most cases, use `loginWithSocial()` which handles state management automatically.
+     */
     getSocialAuthUrl(request: SocialAuthUrlRequest): Promise<{
         url: string;
     }>;
+    /**
+     * Handle social callback.
+     */
     handleSocialCallback(request: SocialCallbackRequest): Promise<AuthResponse>;
+    /**
+     * Verify native social token (mobile).
+     */
     verifyNativeSocial(request: SocialVerifyRequest): Promise<AuthResponse>;
+    /**
+     * Get linked accounts.
+     */
     getLinkedAccounts(): Promise<LinkedAccountsResponse>;
+    /**
+     * Link social account.
+     */
     linkSocialAccount(provider: string, code: string, state: string): Promise<{
         message: string;
     }>;
+    /**
+     * Unlink social account.
+     */
     unlinkSocialAccount(provider: string): Promise<{
         message: string;
     }>;
+    /**
+     * Trust current device.
+     */
     trustDevice(): Promise<{
         deviceToken: string;
     }>;
+    /**
+     * Check if the current device is trusted.
+     *
+     * Returns whether the current device is trusted based on the device token
+     * (from cookie in cookies mode, or header in JSON mode).
+     *
+     * This performs a server-side validation of the device token and checks:
+     * - Device token exists and is valid
+     * - Device token matches a trusted device record in the database
+     * - Trust has not expired
+     *
+     * @returns Object with trusted status
+     *
+     * @example
+     * ```typescript
+     * const result = await client.isTrustedDevice();
+     * if (result.trusted) {
+     *   console.log('This device is trusted');
+     * }
+     * ```
+     */
     isTrustedDevice(): Promise<{
         trusted: boolean;
     }>;
+    /**
+     * Get paginated audit history for the current user.
+     *
+     * Returns authentication and security events with full audit details including:
+     * - Event type (login, logout, MFA, etc.)
+     * - Event status (success, failure, suspicious)
+     * - Device information, location, risk factors
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated audit history response
+     *
+     * @example
+     * ```typescript
+     * const history = await client.getAuditHistory({
+     *   page: 1,
+     *   limit: 20,
+     *   eventType: 'LOGIN_SUCCESS'
+     * });
+     * ```
+     */
     getAuditHistory(params?: Record<string, string | number | boolean>): Promise<AuditHistoryResponse>;
+    /**
+     * Initialize client by hydrating state from storage.
+     * Call this on app startup to restore auth state.
+     */
     initialize(): Promise<void>;
+    /**
+     * Determine if user is authenticated (async - checks tokens).
+     */
     isAuthenticated(): Promise<boolean>;
+    /**
+     * Determine if user is authenticated (sync - checks cached user).
+     * Use this for guards and sync checks. Use `isAuthenticated()` for definitive check.
+     */
     isAuthenticatedSync(): boolean;
+    /**
+     * Get current access token (may be null).
+     */
     getAccessToken(): Promise<string | null>;
+    /**
+     * Get current user (cached, sync).
+     */
     getCurrentUser(): AuthUser | null;
+    /**
+     * Get stored challenge session (for resuming challenge flows).
+     */
     getStoredChallenge(): Promise<AuthResponse | null>;
+    /**
+     * Clear stored challenge session.
+     */
     clearStoredChallenge(): Promise<void>;
+    /**
+     * Internal: handle auth response (tokens or challenge).
+     *
+     * In cookies mode: Tokens are set as httpOnly cookies by backend, not stored in client storage.
+     * In JSON mode: Tokens are stored in tokenManager for Authorization header.
+     */
     private handleAuthResponse;
+    /**
+     * Persist challenge state.
+     */
     private persistChallenge;
+    /**
+     * Clear challenge state.
+     */
     private clearChallenge;
+    /**
+     * Persist user.
+     */
     private setUser;
+    /**
+     * Clear all auth state.
+     *
+     * @param forgetDevice - If true, also clear device token (for JSON mode)
+     */
     private clearAuthState;
+    /**
+     * Persist device token (json mode mobile).
+     */
     private setDeviceToken;
+    /**
+     * Determine token delivery mode for this environment.
+     */
     private getTokenDeliveryMode;
+    /**
+     * Build request URL by combining baseUrl with path.
+     * @private
+     */
     private buildUrl;
+    /**
+     * Build request headers for authentication.
+     * @private
+     */
     private buildHeaders;
+    /**
+     * Get CSRF token from cookie (browser only).
+     * @private
+     */
     private getCsrfToken;
+    /**
+     * Execute GET request.
+     * Note: 401 refresh is handled by framework interceptors (Angular) or manually.
+     */
     private get;
+    /**
+     * Execute POST request.
+     * Note: 401 refresh is handled by framework interceptors (Angular) or manually.
+     */
     private post;
+    /**
+     * Execute PUT request.
+     * Note: 401 refresh is handled by framework interceptors (Angular) or manually.
+     */
     private put;
+    /**
+     * Execute DELETE request.
+     * Note: 401 refresh is handled by framework interceptors (Angular) or manually.
+     */
     private delete;
+    /**
+     * Handle cross-tab storage updates.
+     */
     private readonly handleStorageEvent;
 }
 
+/**
+ * Fully resolved configuration with all defaults applied.
+ */
 type ResolvedNAuthClientConfig = Omit<NAuthClientConfig, 'endpoints' | 'storage' | 'tokenDelivery' | 'httpAdapter'> & {
     tokenDelivery: TokenDeliveryMode;
     endpoints: NAuthEndpoints;
@@ -635,23 +1437,122 @@ type ResolvedNAuthClientConfig = Omit<NAuthClientConfig, 'endpoints' | 'storage'
     headers: Record<string, string>;
     timeout: number;
 };
+/**
+ * Default endpoint paths matching backend controller.
+ */
 declare const defaultEndpoints: NAuthEndpoints;
+/**
+ * Normalize user config with defaults.
+ *
+ * @param config - User supplied config
+ * @param defaultAdapter - Default HTTP adapter (FetchAdapter for vanilla, AngularHttpAdapter for Angular)
+ * @returns Resolved config with defaults applied
+ */
 declare const resolveConfig: (config: NAuthClientConfig, defaultAdapter: HttpAdapter) => ResolvedNAuthClientConfig;
 
+/**
+ * Helper utilities for working with authentication challenges.
+ *
+ * These utilities reduce boilerplate in consumer applications by providing
+ * type-safe access to challenge parameters and state detection.
+ */
+/**
+ * Check if a challenge requires phone collection (user has no phone number).
+ *
+ * @param challenge - Auth response with challenge
+ * @returns True if phone collection is required
+ *
+ * @example
+ * ```typescript
+ * const challenge = auth.getCurrentChallenge();
+ * if (challenge && requiresPhoneCollection(challenge)) {
+ *   // Show phone input form
+ * }
+ * ```
+ */
 declare function requiresPhoneCollection(challenge: AuthResponse): boolean;
+/**
+ * Get masked destination (email or phone) from challenge parameters.
+ *
+ * For VERIFY_EMAIL/VERIFY_PHONE challenges, returns `codeDeliveryDestination`.
+ * For MFA_REQUIRED challenges, returns `maskedEmail` or `maskedPhone` based on method.
+ *
+ * @param challenge - Auth response with challenge
+ * @returns Masked destination string or null if not available
+ *
+ * @example
+ * ```typescript
+ * const destination = getMaskedDestination(challenge);
+ * if (destination) {
+ *   console.log(`Code sent to ${destination}`);
+ * }
+ * ```
+ */
 declare function getMaskedDestination(challenge: AuthResponse): string | null;
+/**
+ * Get preferred MFA method from challenge parameters.
+ *
+ * @param challenge - Auth response with MFA_REQUIRED challenge
+ * @returns MFA method or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const method = getMFAMethod(challenge);
+ * if (method === 'totp') {
+ *   // Show TOTP input
+ * }
+ * ```
+ */
 declare function getMFAMethod(challenge: AuthResponse): MFAMethod | undefined;
+/**
+ * Get challenge instructions from challenge parameters.
+ *
+ * @param challenge - Auth response with challenge
+ * @returns Instructions string or undefined if not available
+ *
+ * @example
+ * ```typescript
+ * const instructions = getChallengeInstructions(challenge);
+ * if (instructions) {
+ *   console.log(instructions);
+ * }
+ * ```
+ */
 declare function getChallengeInstructions(challenge: AuthResponse): string | undefined;
+/**
+ * Check if challenge is OTP-based (requires code input).
+ *
+ * @param challenge - Auth response with challenge
+ * @returns True if challenge requires OTP code
+ *
+ * @example
+ * ```typescript
+ * if (isOTPChallenge(challenge)) {
+ *   // Show OTP input component
+ * }
+ * ```
+ */
 declare function isOTPChallenge(challenge: AuthResponse): boolean;
 
+/**
+ * Browser storage adapter wrapping localStorage or sessionStorage.
+ */
 declare class BrowserStorage implements NAuthStorageAdapter {
     private readonly storage;
+    /**
+     * Create a browser storage adapter.
+     *
+     * @param storage - Storage implementation (localStorage by default)
+     */
     constructor(storage?: Storage);
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
 }
 
+/**
+ * In-memory storage adapter for SSR, tests, or environments without Web Storage.
+ */
 declare class InMemoryStorage implements NAuthStorageAdapter {
     private readonly store;
     getItem(key: string): Promise<string | null>;
@@ -659,7 +1560,33 @@ declare class InMemoryStorage implements NAuthStorageAdapter {
     removeItem(key: string): Promise<void>;
 }
 
+/**
+ * HTTP adapter using native fetch API.
+ *
+ * Suitable for:
+ * - Vanilla JavaScript/TypeScript
+ * - Node.js (with fetch polyfill or Node 18+)
+ * - Environments without framework-specific HTTP clients
+ *
+ * @example
+ * ```typescript
+ * import { NAuthClient } from '@nauth-toolkit/client';
+ * import { FetchAdapter } from '@nauth-toolkit/client/adapters/fetch';
+ *
+ * const client = new NAuthClient({
+ *   baseUrl: 'https://api.example.com/auth',
+ *   httpAdapter: new FetchAdapter(),
+ * });
+ * ```
+ */
 declare class FetchAdapter implements HttpAdapter {
+    /**
+     * Execute HTTP request using native fetch.
+     *
+     * @param config - Request configuration
+     * @returns Response with parsed data
+     * @throws NAuthClientError if request fails
+     */
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }