@nauth-toolkit/client 0.1.14 → 0.1.18

package/dist/angular/index.d.mts

@@ -5,6 +5,9 @@ import * as _angular_common_http from '@angular/common/http';
 import { HttpInterceptorFn, HttpRequest as HttpRequest$1, HttpHandlerFn } from '@angular/common/http';
 import { CanActivateFn, Router, UrlTree } from '@angular/router';
 
+/**
+ * Full user profile returned from profile endpoints.
+ */
 interface AuthUser {
     sub: string;
     email: string;
@@ -21,23 +24,35 @@ interface AuthUser {
     createdAt?: string | Date;
     updatedAt?: string | Date;
 }
+/**
+ * Profile update request.
+ */
 interface UpdateProfileRequest {
     firstName?: string;
     lastName?: string;
     email?: string;
     phone?: string;
 }
+/**
+ * Forgot password response payload.
+ */
 interface ForgotPasswordResponse {
     success: boolean;
     destination?: string;
     deliveryMedium?: 'email' | 'sms';
     expiresIn?: number;
 }
+/**
+ * Confirm forgot password response payload.
+ */
 interface ConfirmForgotPasswordResponse {
     success: boolean;
     mustChangePassword: boolean;
 }
 
+/**
+ * Standardized error codes mirroring backend AuthErrorCode.
+ */
 declare enum NAuthErrorCode {
     AUTH_INVALID_CREDENTIALS = "AUTH_INVALID_CREDENTIALS",
     AUTH_ACCOUNT_LOCKED = "AUTH_ACCOUNT_LOCKED",
@@ -95,6 +110,9 @@ declare enum NAuthErrorCode {
     INTERNAL_ERROR = "INTERNAL_ERROR",
     SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
 }
+/**
+ * Structured client error.
+ */
 interface NAuthError {
     code: NAuthErrorCode;
     message: string;
@@ -103,30 +121,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;
@@ -161,40 +270,134 @@ 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;
 }
 
+/**
+ * Injection token for providing NAuthClientConfig in Angular apps.
+ */
 declare const NAUTH_CLIENT_CONFIG: InjectionToken<NAuthClientConfig>;
 
+/**
+ * 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;
@@ -206,13 +409,24 @@ interface MFAStatus {
     mfaExemptReason: string | null;
     mfaExemptGrantedAt: string | Date | null;
 }
+/**
+ * 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>;
 }
 
+/**
+ * Authentication challenge types returned by the backend.
+ */
 declare enum AuthChallenge {
     VERIFY_EMAIL = "VERIFY_EMAIL",
     VERIFY_PHONE = "VERIFY_PHONE",
@@ -234,6 +448,9 @@ interface AuthResponse {
     challengeParameters?: Record<string, unknown>;
     userSub?: string;
 }
+/**
+ * Minimal user information returned inside auth responses.
+ */
 interface AuthUserSummary {
     sub: string;
     email: string;
@@ -245,12 +462,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;
@@ -259,15 +482,27 @@ interface SignupRequest {
     phone?: string;
     metadata?: Record<string, unknown>;
 }
+/**
+ * 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;
 }
@@ -303,21 +538,94 @@ interface ForceChangePasswordResponse extends BaseChallengeResponse {
     newPassword: string;
 }
 
+/**
+ * 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;
@@ -327,8 +635,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: {
@@ -336,6 +658,9 @@ interface AuthLoginEvent {
     };
     timestamp: number;
 }
+/**
+ * Signup initiated event
+ */
 interface AuthSignupEvent {
     type: 'auth:signup';
     data: {
@@ -343,21 +668,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: {
@@ -366,6 +703,9 @@ interface AuthLogoutEvent {
     };
     timestamp: number;
 }
+/**
+ * Token refreshed event
+ */
 interface AuthRefreshEvent {
     type: 'auth:refresh';
     data: {
@@ -373,6 +713,9 @@ interface AuthRefreshEvent {
     };
     timestamp: number;
 }
+/**
+ * OAuth flow started event
+ */
 interface OAuthStartedEvent {
     type: 'oauth:started';
     data: {
@@ -380,6 +723,9 @@ interface OAuthStartedEvent {
     };
     timestamp: number;
 }
+/**
+ * OAuth callback received event
+ */
 interface OAuthCallbackEvent {
     type: 'oauth:callback';
     data: {
@@ -387,31 +733,55 @@ 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;
 
+/**
+ * Social provider identifiers.
+ */
 type SocialProvider = 'google' | 'apple' | 'facebook';
+/**
+ * Request to obtain social auth URL.
+ */
 interface SocialAuthUrlRequest {
     provider: SocialProvider;
     state?: 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;
@@ -419,6 +789,9 @@ interface SocialVerifyRequest {
     authorizationCode?: string;
 }
 
+/**
+ * Audit event types.
+ */
 declare enum AuthAuditEventType {
     LOGIN_SUCCESS = "LOGIN_SUCCESS",
     LOGIN_FAILED = "LOGIN_FAILED",
@@ -446,7 +819,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;
@@ -475,6 +854,9 @@ interface AuthAuditEvent {
     metadata?: Record<string, unknown> | null;
     createdAt: string | Date;
 }
+/**
+ * Paginated audit history response.
+ */
 interface AuditHistoryResponse {
     data: AuthAuditEvent[];
     total: number;
@@ -483,95 +865,460 @@ interface AuditHistoryResponse {
     totalPages: number;
 }
 
+/**
+ * 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;
 }
 
+/**
+ * Angular wrapper around NAuthClient that exposes Observables for auth state.
+ *
+ * Design philosophy: Keep lean, use getClient() for full API access.
+ * This service provides:
+ * - Reactive state (currentUser$, isAuthenticated$, challenge$)
+ * - Core auth methods as Observables (login, signup, logout, refresh)
+ * - Challenge flow methods (respondToChallenge, resendCode)
+ * - Escape hatch via getClient() for all other operations
+ *
+ * @example
+ * ```typescript
+ * constructor(private auth: AuthService) {}
+ *
+ * // Reactive state
+ * this.auth.currentUser$.subscribe(user => ...);
+ * this.auth.isAuthenticated$.subscribe(isAuth => ...);
+ *
+ * // Auth operations
+ * this.auth.login(email, password).subscribe(response => ...);
+ *
+ * // Advanced operations via client
+ * this.auth.getClient().getMfaStatus().then(status => ...);
+ * ```
+ */
 declare class AuthService {
     private readonly client;
     private readonly config;
@@ -580,65 +1327,341 @@ declare class AuthService {
     private readonly challengeSubject;
     private readonly authEventsSubject;
     private initialized;
+    /**
+     * @param config - Injected client configuration
+     *
+     * Note: AngularHttpAdapter is automatically injected via Angular DI.
+     * This ensures all requests go through Angular's HttpClient and interceptors.
+     */
     constructor(config?: NAuthClientConfig);
+    /**
+     * Current user observable.
+     */
     get currentUser$(): Observable<AuthUser | null>;
+    /**
+     * Authenticated state observable.
+     */
     get isAuthenticated$(): Observable<boolean>;
+    /**
+     * Current challenge observable (for reactive challenge navigation).
+     */
     get challenge$(): Observable<AuthResponse | null>;
+    /**
+     * Authentication events stream.
+     * Emits all auth lifecycle events for custom logic, analytics, or UI updates.
+     */
     get authEvents$(): Observable<AuthEvent>;
+    /**
+     * Successful authentication events stream.
+     * Emits when user successfully authenticates (login, signup, social auth).
+     */
     get authSuccess$(): Observable<AuthEvent>;
+    /**
+     * Authentication error events stream.
+     * Emits when authentication fails (login error, OAuth error, etc.).
+     */
     get authError$(): Observable<AuthEvent>;
+    /**
+     * Check if authenticated (sync, uses cached state).
+     */
     isAuthenticated(): boolean;
+    /**
+     * Get current user (sync, uses cached state).
+     */
     getCurrentUser(): AuthUser | null;
+    /**
+     * Get current challenge (sync).
+     */
     getCurrentChallenge(): AuthResponse | null;
+    /**
+     * Login with identifier and password.
+     */
     login(identifier: string, password: string): Observable<AuthResponse>;
+    /**
+     * Signup with credentials.
+     */
     signup(payload: Parameters<NAuthClient['signup']>[0]): Observable<AuthResponse>;
+    /**
+     * Logout current session.
+     */
     logout(forgetDevice?: boolean): Observable<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 Observable with number of sessions revoked
+     */
     logoutAll(forgetDevices?: boolean): Observable<{
         revokedCount: number;
     }>;
+    /**
+     * Refresh tokens.
+     */
     refresh(): Observable<TokenResponse>;
+    /**
+     * Request a password reset code (forgot password).
+     */
     forgotPassword(identifier: string): Observable<ForgotPasswordResponse>;
+    /**
+     * Confirm a password reset code and set a new password.
+     */
     confirmForgotPassword(identifier: string, code: string, newPassword: string): Observable<ConfirmForgotPasswordResponse>;
+    /**
+     * Respond to a challenge (VERIFY_EMAIL, VERIFY_PHONE, MFA_REQUIRED, etc.).
+     */
     respondToChallenge(response: ChallengeResponse): Observable<AuthResponse>;
+    /**
+     * Resend challenge code.
+     */
     resendCode(session: string): Observable<{
         destination: string;
     }>;
+    /**
+     * Get MFA setup data (for MFA_SETUP_REQUIRED challenge).
+     *
+     * 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 Observable of setup data response
+     */
     getSetupData(session: string, method: string): Observable<GetSetupDataResponse>;
+    /**
+     * Get MFA challenge data (for MFA_REQUIRED challenge - e.g., passkey options).
+     *
+     * @param session - Challenge session token
+     * @param method - Challenge method
+     * @returns Observable of challenge data response
+     */
     getChallengeData(session: string, method: string): Observable<GetChallengeDataResponse>;
+    /**
+     * Clear stored challenge (when navigating away from challenge flow).
+     */
     clearChallenge(): Observable<void>;
+    /**
+     * Initiate social OAuth login flow.
+     * Redirects to OAuth provider with automatic state management.
+     */
     loginWithSocial(provider: SocialProvider, options?: {
         redirectUri?: string;
     }): Promise<void>;
+    /**
+     * Get social auth URL to redirect user for OAuth (low-level API).
+     */
     getSocialAuthUrl(provider: string, redirectUri?: string): Observable<{
         url: string;
     }>;
+    /**
+     * Handle social auth callback (low-level API).
+     */
     handleSocialCallback(provider: string, code: string, state: string): Observable<AuthResponse>;
+    /**
+     * Expose underlying NAuthClient for advanced scenarios.
+     *
+     * Use this for operations not directly exposed by this service:
+     * - Profile management (getProfile, updateProfile)
+     * - MFA management (getMfaStatus, setupMfaDevice, etc.)
+     * - Social account linking (linkSocialAccount, unlinkSocialAccount)
+     * - Audit history (getAuditHistory)
+     * - Device trust (trustDevice)
+     *
+     * @example
+     * ```typescript
+     * // Get MFA status
+     * const status = await this.auth.getClient().getMfaStatus();
+     *
+     * // Update profile
+     * const user = await this.auth.getClient().updateProfile({ firstName: 'John' });
+     * ```
+     */
     getClient(): NAuthClient;
+    /**
+     * Initialize by hydrating state from storage.
+     * Called automatically on construction.
+     */
     private initialize;
+    /**
+     * Update challenge state after auth response.
+     */
     private updateChallengeState;
 }
 
+/**
+ * Angular HTTP interceptor for nauth-toolkit.
+ *
+ * Handles:
+ * - Cookies mode: withCredentials + CSRF tokens + refresh via POST
+ * - JSON mode: refresh via SDK, retry with new token
+ */
 declare const authInterceptor: HttpInterceptorFn;
+/**
+ * Class-based interceptor for NgModule compatibility.
+ */
 declare class AuthInterceptor {
     intercept(req: HttpRequest$1<unknown>, next: HttpHandlerFn): rxjs.Observable<_angular_common_http.HttpEvent<unknown>>;
 }
 
+/**
+ * Functional route guard for authentication (Angular 17+).
+ *
+ * Protects routes by checking if user is authenticated.
+ * Redirects to login page if not authenticated.
+ *
+ * @param redirectTo - Path to redirect to if not authenticated (default: '/login')
+ * @returns CanActivateFn guard function
+ *
+ * @example
+ * ```typescript
+ * // In route configuration
+ * const routes: Routes = [
+ *   {
+ *     path: 'home',
+ *     component: HomeComponent,
+ *     canActivate: [authGuard()]
+ *   },
+ *   {
+ *     path: 'admin',
+ *     component: AdminComponent,
+ *     canActivate: [authGuard('/admin/login')]
+ *   }
+ * ];
+ * ```
+ */
 declare function authGuard(redirectTo?: string): CanActivateFn;
+/**
+ * Class-based authentication guard for NgModule compatibility.
+ *
+ * @example
+ * ```typescript
+ * // In route configuration (NgModule)
+ * const routes: Routes = [
+ *   {
+ *     path: 'home',
+ *     component: HomeComponent,
+ *     canActivate: [AuthGuard]
+ *   }
+ * ];
+ *
+ * // In module providers
+ * @NgModule({
+ *   providers: [AuthGuard]
+ * })
+ * ```
+ */
 declare class AuthGuard {
     private auth;
     private router;
+    /**
+     * @param auth - Authentication service
+     * @param router - Angular router
+     */
     constructor(auth: AuthService, router: Router);
+    /**
+     * Check if route can be activated.
+     *
+     * @returns True if authenticated, otherwise redirects to login
+     */
     canActivate(): boolean | UrlTree;
 }
 
+/**
+ * OAuth callback route guard.
+ *
+ * Drop-in guard that automatically processes OAuth callbacks and redirects appropriately.
+ * Place this guard on your `/auth/callback` route to handle social authentication.
+ *
+ * The guard:
+ * - Auto-detects OAuth callback parameters (provider, code, state)
+ * - Completes authentication via backend
+ * - Redirects using window.location (works in browser, Capacitor, SSR-safe)
+ *
+ * Configure redirect URLs in `NAUTH_CLIENT_CONFIG.redirects`.
+ *
+ * @example
+ * ```typescript
+ * // app.routes.ts
+ * import { oauthCallbackGuard } from '@nauth-toolkit/client/angular';
+ *
+ * export const routes: Routes = [
+ *   {
+ *     path: 'auth/callback',
+ *     canActivate: [oauthCallbackGuard],
+ *     redirectTo: '/', // Fallback - guard handles redirect
+ *   },
+ * ];
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts - Configure redirect URLs
+ * import { NAUTH_CLIENT_CONFIG } from '@nauth-toolkit/client/angular';
+ *
+ * providers: [
+ *   {
+ *     provide: NAUTH_CLIENT_CONFIG,
+ *     useValue: {
+ *       baseUrl: 'https://api.example.com/auth',
+ *       tokenDelivery: 'cookies',
+ *       redirects: {
+ *         success: '/home', // Common redirect for all successful auth
+ *         oauthError: '/login',
+ *         challengeBase: '/auth/challenge',
+ *       },
+ *     },
+ *   }
+ * ]
+ * ```
+ */
 declare const oauthCallbackGuard: CanActivateFn;
 
+/**
+ * NgModule wrapper to provide configuration and interceptor.
+ */
 declare class NAuthModule {
+    /**
+     * Configure the module with client settings.
+     *
+     * @param config - Client configuration
+     */
     static forRoot(config: NAuthClientConfig): ModuleWithProviders<NAuthModule>;
 }
 
+/**
+ * HTTP adapter for Angular using HttpClient.
+ *
+ * This adapter:
+ * - Uses Angular's HttpClient for all requests
+ * - Works with Angular's HTTP interceptors (including authInterceptor)
+ * - Auto-provided via Angular DI (providedIn: 'root')
+ * - Converts HttpClient responses to HttpResponse format
+ * - Converts HttpErrorResponse to NAuthClientError
+ *
+ * Users don't need to configure this manually - it's automatically
+ * injected when using AuthService in Angular apps.
+ *
+ * @example
+ * ```typescript
+ * // Automatic usage (no manual setup needed)
+ * // AuthService automatically injects AngularHttpAdapter
+ * constructor(private auth: AuthService) {}
+ * ```
+ */
 declare class AngularHttpAdapter implements HttpAdapter {
     private readonly http;
+    /**
+     * Execute HTTP request using Angular's HttpClient.
+     *
+     * @param config - Request configuration
+     * @returns Response with parsed data
+     * @throws NAuthClientError if request fails
+     */
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }