@nauth-toolkit/client 0.1.18 → 0.1.21

package/dist/index.d.mts

@@ -284,25 +284,34 @@ 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';
+    /**
+     * 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.
@@ -407,6 +416,10 @@ interface NAuthStorageAdapter {
      * Remove a stored value.
      */
     removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
 }
 
 /**
@@ -529,12 +542,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 +1193,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.
+     * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
      *
-     * @param urlOrParams - Optional URL string or URLSearchParams (auto-detects from window.location if not provided)
-     * @returns AuthResponse if OAuth callback detected, null otherwise
+     * Used for `tokenDelivery: 'json'` or hybrid flows where the backend redirects back
+     * with `exchangeToken` instead of setting cookies.
      *
-     * @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.
+     * @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 +1528,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 +1539,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 +1572,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

@@ -284,25 +284,34 @@ 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';
+    /**
+     * 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.
@@ -407,6 +416,10 @@ interface NAuthStorageAdapter {
      * Remove a stored value.
      */
     removeItem(key: string): Promise<void>;
+    /**
+     * Clear all stored values.
+     */
+    clear(): Promise<void>;
 }
 
 /**
@@ -529,12 +542,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 +1193,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.
+     * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
      *
-     * @param urlOrParams - Optional URL string or URLSearchParams (auto-detects from window.location if not provided)
-     * @returns AuthResponse if OAuth callback detected, null otherwise
+     * Used for `tokenDelivery: 'json'` or hybrid flows where the backend redirects back
+     * with `exchangeToken` instead of setting cookies.
      *
-     * @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.
+     * @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 +1528,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 +1539,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 +1572,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.mjs

@@ -126,12 +126,12 @@ var defaultEndpoints = {
   mfaPreferred: "/mfa/preferred-method",
   mfaBackupCodes: "/mfa/backup-codes/generate",
   mfaExemption: "/mfa/exemption",
-  socialAuthUrl: "/social/auth-url",
-  socialCallback: "/social/callback",
   socialLinked: "/social/linked",
   socialLink: "/social/link",
   socialUnlink: "/social/unlink",
   socialVerify: "/social/:provider/verify",
+  socialRedirectStart: "/social/:provider/redirect",
+  socialExchange: "/social/exchange",
   trustDevice: "/trust-device",
   isTrustedDevice: "/is-trusted-device",
   auditHistory: "/audit/history",
@@ -367,6 +367,9 @@ var BrowserStorage = class {
   async removeItem(key) {
     this.storage.removeItem(key);
   }
+  async clear() {
+    this.storage.clear();
+  }
 };
 
 // src/storage/memory.ts
@@ -383,6 +386,9 @@ var InMemoryStorage = class {
   async removeItem(key) {
     this.store.delete(key);
   }
+  async clear() {
+    this.store.clear();
+  }
 };
 
 // src/core/events.ts
@@ -503,9 +509,9 @@ var FetchAdapter = class {
     });
     if (!response.ok) {
       const errorData = typeof data === "object" && data !== null ? data : {};
-      const code = typeof errorData["code"] === "string" ? errorData.code : "INTERNAL_ERROR" /* INTERNAL_ERROR */;
-      const message = typeof errorData["message"] === "string" ? errorData.message : `Request failed with status ${status}`;
-      const timestamp = typeof errorData["timestamp"] === "string" ? errorData.timestamp : void 0;
+      const code = typeof errorData["code"] === "string" ? errorData["code"] : "INTERNAL_ERROR" /* INTERNAL_ERROR */;
+      const message = typeof errorData["message"] === "string" ? errorData["message"] : `Request failed with status ${status}`;
+      const timestamp = typeof errorData["timestamp"] === "string" ? errorData["timestamp"] : void 0;
       const details = errorData["details"];
       throw new NAuthClientError(code, message, {
         statusCode: status,
@@ -927,126 +933,59 @@ var NAuthClient = class {
   // Social Authentication
   // ============================================================================
   /**
-   * 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' });
    * ```
    */
-  async loginWithSocial(provider, _options) {
+  async loginWithSocial(provider, options) {
     this.eventEmitter.emit({ type: "oauth:started", data: { provider }, timestamp: Date.now() });
-    const { url } = await this.getSocialAuthUrl({ provider });
     if (hasWindow()) {
-      window.location.href = url;
-    }
-  }
-  /**
-   * 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);
-   * ```
-   */
-  async handleOAuthCallback(urlOrParams) {
-    let params;
-    if (urlOrParams instanceof URLSearchParams) {
-      params = urlOrParams;
-    } else if (typeof urlOrParams === "string") {
-      params = new URLSearchParams(urlOrParams);
-    } else if (hasWindow()) {
-      params = new URLSearchParams(window.location.search);
-    } else {
-      return null;
-    }
-    const provider = params.get("provider");
-    const code = params.get("code");
-    const state = params.get("state");
-    const error = params.get("error");
-    if (!provider || !code && !error) {
-      return null;
-    }
-    this.eventEmitter.emit({ type: "oauth:callback", data: { provider }, timestamp: Date.now() });
-    try {
-      if (error) {
-        const authError = new NAuthClientError(
-          "SOCIAL_TOKEN_INVALID" /* SOCIAL_TOKEN_INVALID */,
-          params.get("error_description") || error,
-          { details: { error, provider } }
-        );
-        this.eventEmitter.emit({ type: "oauth:error", data: authError, timestamp: Date.now() });
-        throw authError;
-      }
-      if (!state) {
-        throw new NAuthClientError("CHALLENGE_INVALID" /* CHALLENGE_INVALID */, "Missing OAuth state parameter");
+      const startPath = this.config.endpoints.socialRedirectStart.replace(":provider", provider);
+      const base = this.config.baseUrl.replace(/\/$/, "");
+      const startUrl = new URL(`${base}${startPath}`);
+      const returnTo = options?.returnTo ?? this.config.redirects?.success ?? "/";
+      const action = options?.action ?? "login";
+      startUrl.searchParams.set("returnTo", returnTo);
+      startUrl.searchParams.set("action", action);
+      if (options?.delivery === "cookies" || options?.delivery === "json") {
+        startUrl.searchParams.set("delivery", options.delivery);
       }
-      const response = await this.handleSocialCallback({
-        provider,
-        code,
-        state
-      });
-      if (response.challengeName) {
-        this.eventEmitter.emit({ type: "auth:challenge", data: response, timestamp: Date.now() });
-      } else {
-        this.eventEmitter.emit({ type: "auth:success", data: response, timestamp: Date.now() });
+      if (typeof options?.appState === "string" && options.appState.trim() !== "") {
+        startUrl.searchParams.set("appState", options.appState);
       }
-      this.eventEmitter.emit({ type: "oauth:completed", data: response, timestamp: Date.now() });
-      return response;
-    } catch (error2) {
-      const authError = error2 instanceof NAuthClientError ? error2 : new NAuthClientError(
-        "SOCIAL_TOKEN_INVALID" /* SOCIAL_TOKEN_INVALID */,
-        error2.message || "OAuth callback failed"
-      );
-      this.eventEmitter.emit({ type: "oauth:error", data: authError, timestamp: Date.now() });
-      throw authError;
+      window.location.href = startUrl.toString();
     }
   }
   /**
-   * Get social auth URL (low-level API).
+   * Exchange an `exchangeToken` (from redirect callback URL) into an AuthResponse.
    *
-   * For most cases, use `loginWithSocial()` which handles state management automatically.
-   */
-  async getSocialAuthUrl(request) {
-    return this.post(this.config.endpoints.socialAuthUrl, request);
-  }
-  /**
-   * Handle social callback.
+   * 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 AuthResponse
    */
-  async handleSocialCallback(request) {
-    const result = await this.post(this.config.endpoints.socialCallback, request);
+  async exchangeSocialRedirect(exchangeToken) {
+    const token = exchangeToken?.trim();
+    if (!token) {
+      throw new NAuthClientError("CHALLENGE_INVALID" /* CHALLENGE_INVALID */, "Missing exchangeToken");
+    }
+    const result = await this.post(this.config.endpoints.socialExchange, { exchangeToken: token });
     await this.handleAuthResponse(result);
     return result;
   }