@nauth-toolkit/client 0.1.18 → 0.1.21

package/dist/angular/index.d.ts

@@ -137,6 +137,10 @@ interface NAuthStorageAdapter {
      * Remove a stored value.
      */
     removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
 }
 
 /**
@@ -259,12 +263,12 @@ interface NAuthEndpoints {
     mfaPreferred: string;
     mfaBackupCodes: string;
     mfaExemption: string;
-    socialAuthUrl: string;
-    socialCallback: string;
     socialLinked: string;
     socialLink: string;
     socialUnlink: string;
     socialVerify: string;
+    socialRedirectStart: string;
+    socialExchange: string;
     trustDevice: string;
     isTrustedDevice: string;
     auditHistory: string;
@@ -409,6 +413,17 @@ interface MFAStatus {
     mfaExemptReason: string | null;
     mfaExemptGrantedAt: string | Date | null;
 }
+/**
+ * MFA device information.
+ */
+interface MFADevice {
+    id: number;
+    type: MFADeviceMethod;
+    name: string;
+    isPrimary: boolean;
+    isActive: boolean;
+    createdAt: string | Date;
+}
 /**
  * Response from getSetupData API call.
  * Contains provider-specific MFA setup information.
@@ -759,19 +774,34 @@ type AuthEventListener = (event: AuthEvent) => void;
  */
 type SocialProvider = 'google' | 'apple' | 'facebook';
 /**
- * Request to obtain social auth URL.
- */
-interface SocialAuthUrlRequest {
-    provider: SocialProvider;
-    state?: string;
-}
-/**
- * Social callback parameters.
+ * Options for starting a redirect-first social login flow.
+ *
+ * This is a web-first API:
+ * - Browser navigates to backend `/auth/social/:provider/redirect`
+ * - Backend completes OAuth, sets cookies (or returns exchange token), and redirects back
  */
-interface SocialCallbackRequest {
-    provider: SocialProvider;
-    code: string;
-    state: string;
+interface SocialLoginOptions {
+    /**
+     * Frontend route (recommended) or URL to redirect to after the backend callback completes.
+     * Default: config.redirects.success || '/'
+     */
+    returnTo?: string;
+    /**
+     * Optional application state to round-trip back to the frontend.
+     * Must be treated as non-secret.
+     */
+    appState?: string;
+    /**
+     * Optional flow action.
+     * Default: 'login'
+     */
+    action?: 'login' | 'link';
+    /**
+     * Optional delivery preference for redirect-first flows.
+     *
+     * Useful for hybrid deployments where provider callbacks do not contain a reliable `Origin`.
+     */
+    delivery?: 'cookies' | 'json';
 }
 /**
  * Linked social accounts response.
@@ -1056,69 +1086,36 @@ declare class NAuthClient {
      */
     off(event: AuthEventType | '*', listener: AuthEventListener): void;
     /**
-     * Start social OAuth flow with automatic state management.
+     * Start redirect-first social OAuth flow (web).
      *
-     * Generates a secure state token, stores OAuth context, and redirects to the OAuth provider.
-     * After OAuth callback, use `handleOAuthCallback()` to complete authentication.
+     * This performs a browser navigation to:
+     * `GET {baseUrl}/social/:provider/redirect?returnTo=...&appState=...`
+     *
+     * The backend:
+     * - generates and stores CSRF state (cluster-safe)
+     * - redirects the user to the provider
+     * - completes OAuth on callback and sets cookies (or issues an exchange token)
+     * - redirects back to `returnTo` with `appState` (and `exchangeToken` for json/hybrid)
      *
      * @param provider - OAuth provider ('google', 'apple', 'facebook')
-     * @param options - Optional configuration
+     * @param options - Optional redirect options
      *
      * @example
      * ```typescript
-     * // Simple usage
-     * await client.loginWithSocial('google');
-     *
-     * // With custom redirect URI
-     * await client.loginWithSocial('apple', {
-     *   redirectUri: 'https://example.com/auth/callback'
-     * });
+     * await client.loginWithSocial('google', { returnTo: '/auth/callback', appState: '12345' });
      * ```
      */
-    loginWithSocial(provider: SocialProvider, _options?: {
-        redirectUri?: string;
-    }): Promise<void>;
+    loginWithSocial(provider: SocialProvider, options?: SocialLoginOptions): 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
-     *   }
-     * }
+     * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
      *
-     * // 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).
+     * Used for `tokenDelivery: 'json'` or hybrid flows where the backend redirects back
+     * with `exchangeToken` instead of setting cookies.
      *
-     * For most cases, use `loginWithSocial()` which handles state management automatically.
+     * @param exchangeToken - One-time exchange token from the callback URL
+     * @returns AuthResponse
      */
-    getSocialAuthUrl(request: SocialAuthUrlRequest): Promise<{
-        url: string;
-    }>;
-    /**
-     * Handle social callback.
-     */
-    handleSocialCallback(request: SocialCallbackRequest): Promise<AuthResponse>;
+    exchangeSocialRedirect(exchangeToken: string): Promise<AuthResponse>;
     /**
      * Verify native social token (mobile).
      */
@@ -1297,12 +1294,15 @@ declare class NAuthClient {
 /**
  * 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)
+ * - All core auth methods as Observables (login, signup, logout, refresh)
+ * - Profile management (getProfile, updateProfile, changePassword)
  * - Challenge flow methods (respondToChallenge, resendCode)
- * - Escape hatch via getClient() for all other operations
+ * - MFA management (getMfaStatus, setupMfaDevice, etc.)
+ * - Social authentication and account linking
+ * - Device trust management
+ * - Audit history
  *
  * @example
  * ```typescript
@@ -1315,8 +1315,12 @@ declare class NAuthClient {
  * // Auth operations
  * this.auth.login(email, password).subscribe(response => ...);
  *
- * // Advanced operations via client
- * this.auth.getClient().getMfaStatus().then(status => ...);
+ * // Profile management
+ * this.auth.changePassword(oldPassword, newPassword).subscribe(() => ...);
+ * this.auth.updateProfile({ firstName: 'John' }).subscribe(user => ...);
+ *
+ * // MFA operations
+ * this.auth.getMfaStatus().subscribe(status => ...);
  * ```
  */
 declare class AuthService {
@@ -1409,6 +1413,55 @@ declare class AuthService {
      * Confirm a password reset code and set a new password.
      */
     confirmForgotPassword(identifier: string, code: string, newPassword: string): Observable<ConfirmForgotPasswordResponse>;
+    /**
+     * Change user password (requires current password).
+     *
+     * @param oldPassword - Current password
+     * @param newPassword - New password (must meet requirements)
+     * @returns Observable that completes when password is changed
+     *
+     * @example
+     * ```typescript
+     * this.auth.changePassword('oldPassword123', 'newSecurePassword456!').subscribe({
+     *   next: () => console.log('Password changed successfully'),
+     *   error: (err) => console.error('Failed to change password:', err)
+     * });
+     * ```
+     */
+    changePassword(oldPassword: string, newPassword: string): Observable<void>;
+    /**
+     * Request password change (must change on next login).
+     *
+     * @returns Observable that completes when request is sent
+     */
+    requestPasswordChange(): Observable<void>;
+    /**
+     * Get current user profile.
+     *
+     * @returns Observable of current user profile
+     *
+     * @example
+     * ```typescript
+     * this.auth.getProfile().subscribe(user => {
+     *   console.log('User profile:', user);
+     * });
+     * ```
+     */
+    getProfile(): Observable<AuthUser>;
+    /**
+     * Update user profile.
+     *
+     * @param updates - Profile fields to update
+     * @returns Observable of updated user profile
+     *
+     * @example
+     * ```typescript
+     * this.auth.updateProfile({ firstName: 'John', lastName: 'Doe' }).subscribe(user => {
+     *   console.log('Profile updated:', user);
+     * });
+     * ```
+     */
+    updateProfile(updates: UpdateProfileRequest): Observable<AuthUser>;
     /**
      * Respond to a challenge (VERIFY_EMAIL, VERIFY_PHONE, MFA_REQUIRED, etc.).
      */
@@ -1447,38 +1500,160 @@ declare class AuthService {
     clearChallenge(): Observable<void>;
     /**
      * Initiate social OAuth login flow.
-     * Redirects to OAuth provider with automatic state management.
+     * Redirects the browser to backend `/auth/social/:provider/redirect`.
      */
-    loginWithSocial(provider: SocialProvider, options?: {
-        redirectUri?: string;
-    }): Promise<void>;
+    loginWithSocial(provider: SocialProvider, options?: SocialLoginOptions): Promise<void>;
     /**
-     * Get social auth URL to redirect user for OAuth (low-level API).
+     * Exchange an exchangeToken (from redirect callback URL) into an AuthResponse.
+     *
+     * Used for `tokenDelivery: 'json'` or hybrid flows where the backend redirects back
+     * with `exchangeToken` instead of setting cookies.
+     *
+     * @param exchangeToken - One-time exchange token from the callback URL
+     * @returns Observable of AuthResponse
+     */
+    exchangeSocialRedirect(exchangeToken: string): Observable<AuthResponse>;
+    /**
+     * Verify native social token (mobile).
+     *
+     * @param request - Social verification request with provider and token
+     * @returns Observable of AuthResponse
+     */
+    verifyNativeSocial(request: SocialVerifyRequest): Observable<AuthResponse>;
+    /**
+     * Get linked social accounts.
+     *
+     * @returns Observable of linked accounts response
      */
-    getSocialAuthUrl(provider: string, redirectUri?: string): Observable<{
-        url: string;
+    getLinkedAccounts(): Observable<LinkedAccountsResponse>;
+    /**
+     * Link social account.
+     *
+     * @param provider - Social provider to link
+     * @param code - OAuth authorization code
+     * @param state - OAuth state parameter
+     * @returns Observable with success message
+     */
+    linkSocialAccount(provider: string, code: string, state: string): Observable<{
+        message: string;
+    }>;
+    /**
+     * Unlink social account.
+     *
+     * @param provider - Social provider to unlink
+     * @returns Observable with success message
+     */
+    unlinkSocialAccount(provider: string): Observable<{
+        message: string;
+    }>;
+    /**
+     * Get MFA status for the current user.
+     *
+     * @returns Observable of MFA status
+     */
+    getMfaStatus(): Observable<MFAStatus>;
+    /**
+     * Get MFA devices for the current user.
+     *
+     * @returns Observable of MFA devices array
+     */
+    getMfaDevices(): Observable<MFADevice[]>;
+    /**
+     * Setup MFA device (authenticated user).
+     *
+     * @param method - MFA method to set up
+     * @returns Observable of setup data
+     */
+    setupMfaDevice(method: string): Observable<unknown>;
+    /**
+     * Verify MFA setup (authenticated user).
+     *
+     * @param method - MFA method
+     * @param setupData - Setup data from setupMfaDevice
+     * @param deviceName - Optional device name
+     * @returns Observable with device ID
+     */
+    verifyMfaSetup(method: string, setupData: Record<string, unknown>, deviceName?: string): Observable<{
+        deviceId: number;
+    }>;
+    /**
+     * Remove MFA device.
+     *
+     * @param method - MFA method to remove
+     * @returns Observable with success message
+     */
+    removeMfaDevice(method: string): Observable<{
+        message: string;
+    }>;
+    /**
+     * Set preferred MFA method.
+     *
+     * @param method - Device method to set as preferred ('totp', 'sms', 'email', or 'passkey')
+     * @returns Observable with success message
+     */
+    setPreferredMfaMethod(method: 'totp' | 'sms' | 'email' | 'passkey'): Observable<{
+        message: string;
     }>;
     /**
-     * Handle social auth callback (low-level API).
+     * Generate backup codes.
+     *
+     * @returns Observable of backup codes array
+     */
+    generateBackupCodes(): Observable<string[]>;
+    /**
+     * Set MFA exemption (admin/test scenarios).
+     *
+     * @param exempt - Whether to exempt user from MFA
+     * @param reason - Optional reason for exemption
+     * @returns Observable that completes when exemption is set
+     */
+    setMfaExemption(exempt: boolean, reason?: string): Observable<void>;
+    /**
+     * Trust current device.
+     *
+     * @returns Observable with device token
      */
-    handleSocialCallback(provider: string, code: string, state: string): Observable<AuthResponse>;
+    trustDevice(): Observable<{
+        deviceToken: string;
+    }>;
+    /**
+     * Check if the current device is trusted.
+     *
+     * @returns Observable with trusted status
+     */
+    isTrustedDevice(): Observable<{
+        trusted: boolean;
+    }>;
+    /**
+     * Get paginated audit history for the current user.
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Observable of audit history response
+     *
+     * @example
+     * ```typescript
+     * this.auth.getAuditHistory({ page: 1, limit: 20, eventType: 'LOGIN_SUCCESS' }).subscribe(history => {
+     *   console.log('Audit history:', history);
+     * });
+     * ```
+     */
+    getAuditHistory(params?: Record<string, string | number | boolean>): Observable<AuditHistoryResponse>;
     /**
      * 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)
+     * @deprecated All core functionality is now exposed directly on AuthService as Observables.
+     * Use the direct methods on AuthService instead (e.g., `auth.changePassword()` instead of `auth.getClient().changePassword()`).
+     * This method is kept for backward compatibility only and may be removed in a future version.
+     *
+     * @returns The underlying NAuthClient instance
      *
      * @example
      * ```typescript
-     * // Get MFA status
+     * // Deprecated - use direct methods instead
      * const status = await this.auth.getClient().getMfaStatus();
      *
-     * // Update profile
-     * const user = await this.auth.getClient().updateProfile({ firstName: 'John' });
+     * // Preferred - use Observable-based methods
+     * this.auth.getMfaStatus().subscribe(status => ...);
      * ```
      */
     getClient(): NAuthClient;
@@ -1572,54 +1747,29 @@ declare class AuthGuard {
 }
 
 /**
- * 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.
+ * Social redirect callback route guard.
  *
- * The guard:
- * - Auto-detects OAuth callback parameters (provider, code, state)
- * - Completes authentication via backend
- * - Redirects using window.location (works in browser, Capacitor, SSR-safe)
+ * This guard supports the redirect-first social flow where the backend redirects
+ * back to the frontend with:
+ * - `appState` (always optional)
+ * - `exchangeToken` (present for json/hybrid flows, and for cookie flows that return a challenge)
+ * - `error` / `error_description` (provider errors)
  *
- * Configure redirect URLs in `NAUTH_CLIENT_CONFIG.redirects`.
+ * Behavior:
+ * - If `exchangeToken` exists: exchanges it via backend and redirects to success or challenge routes.
+ * - If no `exchangeToken`: allow the route to activate so the app can display `appState`.
+ * - If `error` exists: redirects to oauthError route.
  *
  * @example
  * ```typescript
- * // app.routes.ts
- * import { oauthCallbackGuard } from '@nauth-toolkit/client/angular';
+ * import { socialRedirectCallbackGuard } from '@nauth-toolkit/client/angular';
  *
  * export const routes: Routes = [
- *   {
- *     path: 'auth/callback',
- *     canActivate: [oauthCallbackGuard],
- *     redirectTo: '/', // Fallback - guard handles redirect
- *   },
+ *   { path: 'auth/callback', canActivate: [socialRedirectCallbackGuard], component: CallbackComponent },
  * ];
  * ```
- *
- * @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;
+declare const socialRedirectCallbackGuard: CanActivateFn;
 
 /**
  * NgModule wrapper to provide configuration and interceptor.
@@ -1665,4 +1815,4 @@ declare class AngularHttpAdapter implements HttpAdapter {
     request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
 }
 
-export { AngularHttpAdapter, AuthChallenge, type AuthEvent, type AuthEventListener, type AuthEventType, AuthGuard, AuthInterceptor, type AuthResponse, AuthService, type AuthUser, type ChallengeResponse, type HttpAdapter, type MFADeviceMethod, type MFAMethod, type MFAStatus, NAUTH_CLIENT_CONFIG, type NAuthClientConfig, NAuthModule, type SocialProvider, type TokenDeliveryMode, type TokenResponse, authGuard, authInterceptor, oauthCallbackGuard };
+export { AngularHttpAdapter, AuthChallenge, type AuthEvent, type AuthEventListener, type AuthEventType, AuthGuard, AuthInterceptor, type AuthResponse, AuthService, type AuthUser, type ChallengeResponse, type HttpAdapter, type MFADeviceMethod, type MFAMethod, type MFAStatus, NAUTH_CLIENT_CONFIG, type NAuthClientConfig, NAuthModule, type SocialProvider, type TokenDeliveryMode, type TokenResponse, authGuard, authInterceptor, socialRedirectCallbackGuard };