@nauth-toolkit/client 0.1.112 → 0.1.115

package/dist/index.d.mts

@@ -2979,14 +2979,96 @@ declare class NAuthClient {
     getMfaStatus(): Promise<MFAStatus>;
     /**
      * Get MFA devices.
+     *
+     * @returns Promise of MFA devices response
+     *
+     * @example
+     * ```typescript
+     * const result = await client.getMfaDevices();
+     * console.log('Devices:', result.devices);
+     * ```
      */
-    getMfaDevices(): Promise<unknown[]>;
+    getMfaDevices(): Promise<GetMFADevicesResponse>;
     /**
      * Setup MFA device (authenticated user).
+     *
+     * Returns method-specific setup information:
+     * - TOTP: { secret, qrCode, manualEntryKey }
+     * - SMS: { maskedPhone } or { deviceId, autoCompleted: true }
+     * - Email: { maskedEmail } or { deviceId, autoCompleted: true }
+     * - Passkey: WebAuthn registration options
+     *
+     * @param method - MFA method to set up
+     * @returns Promise of setup data response
+     *
+     * @example
+     * ```typescript
+     * const result = await client.setupMfaDevice('totp');
+     * console.log('QR Code:', result.setupData.qrCode);
+     * ```
      */
-    setupMfaDevice(method: string): Promise<unknown>;
+    setupMfaDevice(method: string): Promise<GetSetupDataResponse>;
     /**
      * Verify MFA setup (authenticated user).
+     *
+     * Completes MFA device setup by verifying the setup data. The structure of `setupData` varies by method:
+     *
+     * **TOTP:**
+     * - Requires both `secret` (from `getSetupData()` response) and `code` (from authenticator app)
+     * - Example: `{ secret: 'JBSWY3DPEHPK3PXP', code: '123456' }`
+     *
+     * **SMS:**
+     * - Requires `phoneNumber` and `code` (verification code sent to phone)
+     * - Example: `{ phoneNumber: '+1234567890', code: '123456' }`
+     *
+     * **Email:**
+     * - Requires `code` (verification code sent to email)
+     * - Example: `{ code: '123456' }`
+     *
+     * **Passkey:**
+     * - Requires `credential` (WebAuthn credential from registration) and `expectedChallenge`
+     * - Example: `{ credential: {...}, expectedChallenge: '...' }`
+     *
+     * @param method - MFA method ('totp', 'sms', 'email', 'passkey')
+     * @param setupData - Method-specific setup verification data
+     * @param deviceName - Optional device name (can also be included in setupData for some methods)
+     * @returns Promise with device ID of the created MFA device
+     *
+     * @example TOTP Setup
+     * ```typescript
+     * // Step 1: Get setup data
+     * const setupData = await client.setupMfaDevice('totp');
+     * // Returns: { setupData: { secret: 'JBSWY3DPEHPK3PXP', qrCode: '...', ... } }
+     *
+     * // Step 2: User scans QR code and enters code from authenticator app
+     * const code = '123456'; // From authenticator app
+     *
+     * // Step 3: Verify setup (requires both secret and code)
+     * const result = await client.verifyMfaSetup('totp', {
+     *   secret: setupData.setupData.secret,
+     *   code: code,
+     * }, 'Google Authenticator');
+     * // Returns: { deviceId: 123 }
+     * ```
+     *
+     * @example SMS Setup
+     * ```typescript
+     * const result = await client.verifyMfaSetup('sms', {
+     *   phoneNumber: '+1234567890', // Phone number receiving the code
+     *   code: '123456', // Code sent to phone
+     * }, 'My iPhone');
+     * ```
+     *
+     * @example Passkey Setup
+     * ```typescript
+     * const credential = await navigator.credentials.create({
+     *   publicKey: setupData.setupData.options
+     * });
+     * const result = await client.verifyMfaSetup('passkey', {
+     *   credential: credential,
+     *   expectedChallenge: setupData.setupData.challenge,
+     * }, 'MacBook Pro');
+     * ```
      */
     verifyMfaSetup(method: string, setupData: Record<string, unknown>, deviceName?: string): Promise<{
         deviceId: number;
@@ -2994,7 +3076,7 @@ declare class NAuthClient {
     /**
      * Remove ALL MFA devices for a specific method type.
      *
-     * ⚠️ **Warning**: This removes ALL devices of the specified method.
+     * WARNING: This removes ALL devices of the specified method.
      * For example, if you have 3 TOTP devices, this will remove all 3.
      *
      * **Prefer `removeMfaDeviceById()`** to remove individual devices.

package/dist/index.d.ts

@@ -2979,14 +2979,96 @@ declare class NAuthClient {
     getMfaStatus(): Promise<MFAStatus>;
     /**
      * Get MFA devices.
+     *
+     * @returns Promise of MFA devices response
+     *
+     * @example
+     * ```typescript
+     * const result = await client.getMfaDevices();
+     * console.log('Devices:', result.devices);
+     * ```
      */
-    getMfaDevices(): Promise<unknown[]>;
+    getMfaDevices(): Promise<GetMFADevicesResponse>;
     /**
      * Setup MFA device (authenticated user).
+     *
+     * Returns method-specific setup information:
+     * - TOTP: { secret, qrCode, manualEntryKey }
+     * - SMS: { maskedPhone } or { deviceId, autoCompleted: true }
+     * - Email: { maskedEmail } or { deviceId, autoCompleted: true }
+     * - Passkey: WebAuthn registration options
+     *
+     * @param method - MFA method to set up
+     * @returns Promise of setup data response
+     *
+     * @example
+     * ```typescript
+     * const result = await client.setupMfaDevice('totp');
+     * console.log('QR Code:', result.setupData.qrCode);
+     * ```
      */
-    setupMfaDevice(method: string): Promise<unknown>;
+    setupMfaDevice(method: string): Promise<GetSetupDataResponse>;
     /**
      * Verify MFA setup (authenticated user).
+     *
+     * Completes MFA device setup by verifying the setup data. The structure of `setupData` varies by method:
+     *
+     * **TOTP:**
+     * - Requires both `secret` (from `getSetupData()` response) and `code` (from authenticator app)
+     * - Example: `{ secret: 'JBSWY3DPEHPK3PXP', code: '123456' }`
+     *
+     * **SMS:**
+     * - Requires `phoneNumber` and `code` (verification code sent to phone)
+     * - Example: `{ phoneNumber: '+1234567890', code: '123456' }`
+     *
+     * **Email:**
+     * - Requires `code` (verification code sent to email)
+     * - Example: `{ code: '123456' }`
+     *
+     * **Passkey:**
+     * - Requires `credential` (WebAuthn credential from registration) and `expectedChallenge`
+     * - Example: `{ credential: {...}, expectedChallenge: '...' }`
+     *
+     * @param method - MFA method ('totp', 'sms', 'email', 'passkey')
+     * @param setupData - Method-specific setup verification data
+     * @param deviceName - Optional device name (can also be included in setupData for some methods)
+     * @returns Promise with device ID of the created MFA device
+     *
+     * @example TOTP Setup
+     * ```typescript
+     * // Step 1: Get setup data
+     * const setupData = await client.setupMfaDevice('totp');
+     * // Returns: { setupData: { secret: 'JBSWY3DPEHPK3PXP', qrCode: '...', ... } }
+     *
+     * // Step 2: User scans QR code and enters code from authenticator app
+     * const code = '123456'; // From authenticator app
+     *
+     * // Step 3: Verify setup (requires both secret and code)
+     * const result = await client.verifyMfaSetup('totp', {
+     *   secret: setupData.setupData.secret,
+     *   code: code,
+     * }, 'Google Authenticator');
+     * // Returns: { deviceId: 123 }
+     * ```
+     *
+     * @example SMS Setup
+     * ```typescript
+     * const result = await client.verifyMfaSetup('sms', {
+     *   phoneNumber: '+1234567890', // Phone number receiving the code
+     *   code: '123456', // Code sent to phone
+     * }, 'My iPhone');
+     * ```
+     *
+     * @example Passkey Setup
+     * ```typescript
+     * const credential = await navigator.credentials.create({
+     *   publicKey: setupData.setupData.options
+     * });
+     * const result = await client.verifyMfaSetup('passkey', {
+     *   credential: credential,
+     *   expectedChallenge: setupData.setupData.challenge,
+     * }, 'MacBook Pro');
+     * ```
      */
     verifyMfaSetup(method: string, setupData: Record<string, unknown>, deviceName?: string): Promise<{
         deviceId: number;
@@ -2994,7 +3076,7 @@ declare class NAuthClient {
     /**
      * Remove ALL MFA devices for a specific method type.
      *
-     * ⚠️ **Warning**: This removes ALL devices of the specified method.
+     * WARNING: This removes ALL devices of the specified method.
      * For example, if you have 3 TOTP devices, this will remove all 3.
      *
      * **Prefer `removeMfaDeviceById()`** to remove individual devices.

package/dist/index.mjs

@@ -1733,7 +1733,8 @@ var NAuthClient = class {
    */
   async respondToChallenge(response) {
     if (this.selectedDeviceId !== void 0 && response.type === "MFA_REQUIRED" /* MFA_REQUIRED */ && (response.method === "totp" || response.method === "passkey")) {
-      response.deviceId = this.selectedDeviceId;
+      const mfaResponse = response;
+      mfaResponse.deviceId = this.selectedDeviceId;
     }
     if (response.type === "MFA_SETUP_REQUIRED" /* MFA_SETUP_REQUIRED */ && response.method === "totp") {
       const setupData = response.setupData;
@@ -1971,18 +1972,100 @@ var NAuthClient = class {
   }
   /**
    * Get MFA devices.
+   *
+   * @returns Promise of MFA devices response
+   *
+   * @example
+   * ```typescript
+   * const result = await client.getMfaDevices();
+   * console.log('Devices:', result.devices);
+   * ```
    */
   async getMfaDevices() {
     return this.get(this.config.endpoints.mfaDevices, true);
   }
   /**
    * Setup MFA device (authenticated user).
+   *
+   * Returns method-specific setup information:
+   * - TOTP: { secret, qrCode, manualEntryKey }
+   * - SMS: { maskedPhone } or { deviceId, autoCompleted: true }
+   * - Email: { maskedEmail } or { deviceId, autoCompleted: true }
+   * - Passkey: WebAuthn registration options
+   *
+   * @param method - MFA method to set up
+   * @returns Promise of setup data response
+   *
+   * @example
+   * ```typescript
+   * const result = await client.setupMfaDevice('totp');
+   * console.log('QR Code:', result.setupData.qrCode);
+   * ```
    */
   async setupMfaDevice(method) {
     return this.post(this.config.endpoints.mfaSetupData, { methodName: method }, true);
   }
   /**
    * Verify MFA setup (authenticated user).
+   *
+   * Completes MFA device setup by verifying the setup data. The structure of `setupData` varies by method:
+   *
+   * **TOTP:**
+   * - Requires both `secret` (from `getSetupData()` response) and `code` (from authenticator app)
+   * - Example: `{ secret: 'JBSWY3DPEHPK3PXP', code: '123456' }`
+   *
+   * **SMS:**
+   * - Requires `phoneNumber` and `code` (verification code sent to phone)
+   * - Example: `{ phoneNumber: '+1234567890', code: '123456' }`
+   *
+   * **Email:**
+   * - Requires `code` (verification code sent to email)
+   * - Example: `{ code: '123456' }`
+   *
+   * **Passkey:**
+   * - Requires `credential` (WebAuthn credential from registration) and `expectedChallenge`
+   * - Example: `{ credential: {...}, expectedChallenge: '...' }`
+   *
+   * @param method - MFA method ('totp', 'sms', 'email', 'passkey')
+   * @param setupData - Method-specific setup verification data
+   * @param deviceName - Optional device name (can also be included in setupData for some methods)
+   * @returns Promise with device ID of the created MFA device
+   *
+   * @example TOTP Setup
+   * ```typescript
+   * // Step 1: Get setup data
+   * const setupData = await client.setupMfaDevice('totp');
+   * // Returns: { setupData: { secret: 'JBSWY3DPEHPK3PXP', qrCode: '...', ... } }
+   *
+   * // Step 2: User scans QR code and enters code from authenticator app
+   * const code = '123456'; // From authenticator app
+   *
+   * // Step 3: Verify setup (requires both secret and code)
+   * const result = await client.verifyMfaSetup('totp', {
+   *   secret: setupData.setupData.secret,
+   *   code: code,
+   * }, 'Google Authenticator');
+   * // Returns: { deviceId: 123 }
+   * ```
+   *
+   * @example SMS Setup
+   * ```typescript
+   * const result = await client.verifyMfaSetup('sms', {
+   *   phoneNumber: '+1234567890', // Phone number receiving the code
+   *   code: '123456', // Code sent to phone
+   * }, 'My iPhone');
+   * ```
+   *
+   * @example Passkey Setup
+   * ```typescript
+   * const credential = await navigator.credentials.create({
+   *   publicKey: setupData.setupData.options
+   * });
+   * const result = await client.verifyMfaSetup('passkey', {
+   *   credential: credential,
+   *   expectedChallenge: setupData.setupData.challenge,
+   * }, 'MacBook Pro');
+   * ```
    */
   async verifyMfaSetup(method, setupData, deviceName) {
     return this.post(
@@ -1996,7 +2079,7 @@ var NAuthClient = class {
   /**
    * Remove ALL MFA devices for a specific method type.
    *
-   * ⚠️ **Warning**: This removes ALL devices of the specified method.
+   * WARNING: This removes ALL devices of the specified method.
    * For example, if you have 3 TOTP devices, this will remove all 3.
    *
    * **Prefer `removeMfaDeviceById()`** to remove individual devices.