@nauth-toolkit/client 0.1.18 → 0.1.22

package/dist/index.d.mts

@@ -85,6 +85,16 @@ interface AuthResponse {
     refreshToken?: string;
     accessTokenExpiresAt?: number;
     refreshTokenExpiresAt?: number;
+    /**
+     * Authentication method used to create the current session.
+     *
+     * Examples:
+     * - `password`
+     * - `google`
+     * - `apple`
+     * - `facebook`
+     */
+    authMethod?: string;
     trusted?: boolean;
     deviceToken?: string;
     challengeName?: AuthChallenge;
@@ -229,6 +239,13 @@ interface AuthUser {
     mfaEnabled?: boolean;
     socialProviders?: string[] | null;
     hasPasswordHash: boolean;
+    /**
+     * Authentication method used to create the current session.
+     *
+     * This is session-scoped (how the user logged in this time), not an account capability.
+     * Use `hasPasswordHash` and `socialProviders` to determine what login methods the account supports.
+     */
+    sessionAuthMethod?: string | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
 }
@@ -284,25 +301,28 @@ interface ConfirmForgotPasswordResponse {
  */
 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.
+ * 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';
 }
 /**
  * Linked social accounts response.
@@ -407,6 +427,10 @@ interface NAuthStorageAdapter {
      * Remove a stored value.
      */
     removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
 }
 
 /**
@@ -529,12 +553,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;
@@ -1180,69 +1204,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).
+     *
+     * This performs a browser navigation to:
+     * `GET {baseUrl}/social/:provider/redirect?returnTo=...&appState=...`
      *
-     * Generates a secure state token, stores OAuth context, and redirects to the OAuth provider.
-     * After OAuth callback, use `handleOAuthCallback()` to complete authentication.
+     * 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
+     * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
      *
-     * @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).
+     * 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.
-     */
-    getSocialAuthUrl(request: SocialAuthUrlRequest): Promise<{
-        url: string;
-    }>;
-    /**
-     * Handle social callback.
+     * @param exchangeToken - One-time exchange token from the callback URL
+     * @returns AuthResponse
      */
-    handleSocialCallback(request: SocialCallbackRequest): Promise<AuthResponse>;
+    exchangeSocialRedirect(exchangeToken: string): Promise<AuthResponse>;
     /**
      * Verify native social token (mobile).
      */
@@ -1548,6 +1539,7 @@ declare class BrowserStorage implements NAuthStorageAdapter {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
 }
 
 /**
@@ -1558,6 +1550,7 @@ declare class InMemoryStorage implements NAuthStorageAdapter {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
 }
 
 /**
@@ -1590,4 +1583,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 SocialAuthUrlRequest, type SocialAuthUrlResponse, type SocialCallbackRequest, 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 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 };

package/dist/index.d.ts

@@ -85,6 +85,16 @@ interface AuthResponse {
     refreshToken?: string;
     accessTokenExpiresAt?: number;
     refreshTokenExpiresAt?: number;
+    /**
+     * Authentication method used to create the current session.
+     *
+     * Examples:
+     * - `password`
+     * - `google`
+     * - `apple`
+     * - `facebook`
+     */
+    authMethod?: string;
     trusted?: boolean;
     deviceToken?: string;
     challengeName?: AuthChallenge;
@@ -229,6 +239,13 @@ interface AuthUser {
     mfaEnabled?: boolean;
     socialProviders?: string[] | null;
     hasPasswordHash: boolean;
+    /**
+     * Authentication method used to create the current session.
+     *
+     * This is session-scoped (how the user logged in this time), not an account capability.
+     * Use `hasPasswordHash` and `socialProviders` to determine what login methods the account supports.
+     */
+    sessionAuthMethod?: string | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
 }
@@ -284,25 +301,28 @@ interface ConfirmForgotPasswordResponse {
  */
 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.
+ * 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';
 }
 /**
  * Linked social accounts response.
@@ -407,6 +427,10 @@ interface NAuthStorageAdapter {
      * Remove a stored value.
      */
     removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
 }
 
 /**
@@ -529,12 +553,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;
@@ -1180,69 +1204,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).
+     *
+     * This performs a browser navigation to:
+     * `GET {baseUrl}/social/:provider/redirect?returnTo=...&appState=...`
      *
-     * Generates a secure state token, stores OAuth context, and redirects to the OAuth provider.
-     * After OAuth callback, use `handleOAuthCallback()` to complete authentication.
+     * 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
+     * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
      *
-     * @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).
+     * 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.
-     */
-    getSocialAuthUrl(request: SocialAuthUrlRequest): Promise<{
-        url: string;
-    }>;
-    /**
-     * Handle social callback.
+     * @param exchangeToken - One-time exchange token from the callback URL
+     * @returns AuthResponse
      */
-    handleSocialCallback(request: SocialCallbackRequest): Promise<AuthResponse>;
+    exchangeSocialRedirect(exchangeToken: string): Promise<AuthResponse>;
     /**
      * Verify native social token (mobile).
      */
@@ -1548,6 +1539,7 @@ declare class BrowserStorage implements NAuthStorageAdapter {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
 }
 
 /**
@@ -1558,6 +1550,7 @@ declare class InMemoryStorage implements NAuthStorageAdapter {
     getItem(key: string): Promise<string | null>;
     setItem(key: string, value: string): Promise<void>;
     removeItem(key: string): Promise<void>;
+    clear(): Promise<void>;
 }
 
 /**
@@ -1590,4 +1583,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 SocialAuthUrlRequest, type SocialAuthUrlResponse, type SocialCallbackRequest, 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 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 };