@nauth-toolkit/client 0.1.58 → 0.1.59

package/dist/index.d.mts

@@ -564,6 +564,92 @@ interface NAuthEndpoints {
     auditHistory: string;
     updateProfile: string;
 }
+/**
+ * Context provided to onAuthResponse callback.
+ */
+interface AuthResponseContext {
+    /** Source of the auth operation */
+    source: 'login' | 'signup' | 'social' | 'challenge' | 'refresh';
+    /** OAuth provider (if source is 'social') */
+    provider?: string;
+    /** Whether this was triggered from a guard */
+    fromGuard?: boolean;
+}
+/**
+ * MFA-specific route configuration.
+ * Only applies when challenge type is MFA_REQUIRED.
+ */
+interface MfaRoutesConfig {
+    /** Route for passkey verification (when preferredMethod is 'passkey') */
+    passkey?: string;
+    /** Route for MFA method selector (when multiple methods available) */
+    selector?: string;
+    /** Default route for other MFA methods (sms, email, totp) */
+    default?: string;
+}
+/**
+ * Redirect URLs configuration for authentication flows.
+ * Provides platform-agnostic routing configuration for all authentication scenarios.
+ */
+interface NAuthRedirectsConfig {
+    /**
+     * 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;
+    /**
+     * Custom route for each challenge type.
+     * When specified, overrides default route construction.
+     *
+     * @example
+     * ```typescript
+     * challengeRoutes: {
+     *   [AuthChallenge.MFA_REQUIRED]: '/auth/mfa',
+     *   [AuthChallenge.VERIFY_EMAIL]: '/verify',
+     * }
+     * ```
+     */
+    challengeRoutes?: Partial<Record<AuthChallenge, string>>;
+    /**
+     * Custom routes for MFA-specific flows.
+     * Allows fine-grained control over MFA navigation.
+     * Only applies when challenge type is MFA_REQUIRED.
+     *
+     * @example
+     * ```typescript
+     * mfaRoutes: {
+     *   passkey: '/auth/passkey',
+     *   selector: '/auth/choose-method',
+     *   default: '/auth/verify-code',
+     * }
+     * ```
+     */
+    mfaRoutes?: MfaRoutesConfig;
+    /**
+     * Use single route with query parameter.
+     * When true: /auth/challenge?challenge=VERIFY_EMAIL
+     * When false: /auth/challenge/verify-email
+     *
+     * @default false
+     */
+    useSingleChallengeRoute?: boolean;
+}
 /**
  * Client configuration.
  */
@@ -606,33 +692,44 @@ interface NAuthClientConfig {
     headers?: Record<string, string>;
     /** Request timeout in milliseconds. Default: 30000 */
     timeout?: number;
+    /**
+     * Custom handler called after auth operations complete.
+     *
+     * If provided, SDK will NOT auto-navigate. Instead, it calls this
+     * function with the auth response, allowing apps to handle navigation
+     * or show dialogs.
+     *
+     * @example Dialog-based app
+     * ```typescript
+     * onAuthResponse: (response, context) => {
+     *   if (response.challengeName) {
+     *     this.dialog.open(ChallengeDialogComponent, { data: response });
+     *   } else {
+     *     this.router.navigate(['/dashboard']);
+     *   }
+     * }
+     * ```
+     */
+    onAuthResponse?: (response: AuthResponse, context: AuthResponseContext) => void | Promise<void>;
+    /**
+     * Custom navigation function.
+     * Only used when onAuthResponse is NOT provided.
+     *
+     * @example Angular Router
+     * ```typescript
+     * navigationHandler: (url) => inject(Router).navigateByUrl(url)
+     * ```
+     *
+     * @default Uses window.location.replace (works in guards)
+     */
+    navigationHandler?: (url: string) => void | Promise<void>;
     /**
      * Redirect URLs for various authentication scenarios.
      * Used by guards and interceptors to handle routing in a platform-agnostic way.
+     *
+     * @see {@link NAuthRedirectsConfig} for complete configuration options
      */
-    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;
-    };
+    redirects?: NAuthRedirectsConfig;
     /**
      * Called when session expires (refresh fails with 401).
      */
@@ -1013,6 +1110,147 @@ declare class EventEmitter {
     clear(): void;
 }
 
+/**
+ * Fully resolved configuration with all defaults applied.
+ */
+type ResolvedNAuthClientConfig = Omit<NAuthClientConfig, 'endpoints' | 'storage' | 'tokenDelivery' | 'httpAdapter'> & {
+    tokenDelivery: TokenDeliveryMode;
+    endpoints: NAuthEndpoints;
+    storage: NAuthStorageAdapter;
+    httpAdapter: HttpAdapter;
+    csrf: {
+        cookieName: string;
+        headerName: string;
+    };
+    deviceTrust: {
+        headerName: string;
+        storageKey: string;
+    };
+    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;
+
+/**
+ * Challenge router - handles automatic navigation after auth operations.
+ *
+ * This is internal to the SDK. Consumer apps interact via config options:
+ * - `onAuthResponse` callback for full control (dialogs, etc.)
+ * - `navigationHandler` for custom navigation
+ * - `redirects.challengeRoutes` for custom route mapping
+ * - `redirects.useSingleChallengeRoute` for query param mode
+ *
+ * @example Dialog-based app
+ * ```typescript
+ * {
+ *   onAuthResponse: (response, context) => {
+ *     if (response.challengeName) {
+ *       dialog.open(ChallengeComponent, { data: response });
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Custom routes
+ * ```typescript
+ * {
+ *   redirects: {
+ *     challengeRoutes: {
+ *       [AuthChallenge.MFA_REQUIRED]: '/auth/mfa',
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Single route with query param
+ * ```typescript
+ * {
+ *   redirects: {
+ *     useSingleChallengeRoute: true
+ *   }
+ * }
+ * ```
+ */
+declare class ChallengeRouter {
+    private config;
+    constructor(config: ResolvedNAuthClientConfig);
+    /**
+     * Handle auth response - either call callback or auto-navigate.
+     *
+     * @param response - Auth response from backend
+     * @param context - Context about the auth operation
+     */
+    handleAuthResponse(response: AuthResponse, context: AuthResponseContext): Promise<void>;
+    /**
+     * Navigate to appropriate challenge route.
+     *
+     * @param response - Auth response containing challenge info
+     */
+    navigateToChallenge(response: AuthResponse): Promise<void>;
+    /**
+     * Navigate to success URL.
+     */
+    navigateToSuccess(): Promise<void>;
+    /**
+     * Navigate to error URL.
+     *
+     * @param type - Type of error (oauth or session)
+     */
+    navigateToError(type: 'oauth' | 'session'): Promise<void>;
+    /**
+     * Build challenge URL based on configuration.
+     *
+     * Priority:
+     * 1. Custom route mapping (challengeRoutes)
+     * 2. Single route with query param (useSingleChallengeRoute)
+     * 3. MFA-specific routes (mfaRoutes) - for MFA_REQUIRED challenge only
+     * 4. Default separate routes (challengeBase + kebab-case)
+     *
+     * @param response - Auth response containing challenge info
+     * @returns URL to navigate to
+     */
+    buildChallengeUrl(response: AuthResponse): string;
+    /**
+     * Build MFA-specific URL if custom mfaRoutes are configured.
+     *
+     * @param response - Auth response with MFA challenge parameters
+     * @returns Custom MFA URL if configured, null otherwise
+     */
+    private buildMFAUrl;
+    /**
+     * Build default route segment for a challenge.
+     *
+     * @param challengeName - Challenge type
+     * @param response - Auth response for extracting challenge parameters (needed for MFA)
+     * @returns Route segment (e.g., 'mfa-required/passkey', 'verify-email')
+     */
+    private buildDefaultRouteSegment;
+    /**
+     * Execute navigation using configured handler or default.
+     *
+     * @param url - URL to navigate to
+     */
+    private navigate;
+    /**
+     * Expose URL builder for guards/components that need it.
+     *
+     * @param response - Auth response containing challenge info
+     * @returns URL for the challenge
+     */
+    getChallengeUrl(response: AuthResponse): string;
+}
+
 /**
  * Primary client for interacting with nauth-toolkit backend.
  */
@@ -1020,6 +1258,7 @@ declare class NAuthClient {
     private readonly config;
     private readonly tokenManager;
     private readonly eventEmitter;
+    private readonly challengeRouter;
     private currentUser;
     /**
      * Create a new client instance.
@@ -1407,40 +1646,21 @@ declare class NAuthClient {
      * Handle cross-tab storage updates.
      */
     private readonly handleStorageEvent;
+    /**
+     * Get challenge router for manual navigation control.
+     * Useful for guards that need to handle errors or build custom URLs.
+     *
+     * @returns ChallengeRouter instance
+     *
+     * @example
+     * ```typescript
+     * const router = client.getChallengeRouter();
+     * await router.navigateToError('oauth');
+     * ```
+     */
+    getChallengeRouter(): ChallengeRouter;
 }
 
-/**
- * Fully resolved configuration with all defaults applied.
- */
-type ResolvedNAuthClientConfig = Omit<NAuthClientConfig, 'endpoints' | 'storage' | 'tokenDelivery' | 'httpAdapter'> & {
-    tokenDelivery: TokenDeliveryMode;
-    endpoints: NAuthEndpoints;
-    storage: NAuthStorageAdapter;
-    httpAdapter: HttpAdapter;
-    csrf: {
-        cookieName: string;
-        headerName: string;
-    };
-    deviceTrust: {
-        headerName: string;
-        storageKey: string;
-    };
-    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.
  *
@@ -1583,4 +1803,4 @@ declare class FetchAdapter implements HttpAdapter {
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }
 
-export { type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetSetupDataRequest, type GetSetupDataResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type ResendCodeRequest, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateProfileRequest, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };
+export { type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetSetupDataRequest, type GetSetupDataResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type ResendCodeRequest, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateProfileRequest, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };