@nauth-toolkit/client 0.1.112 → 0.1.114

package/dist/index.cjs

@@ -1775,7 +1775,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;
@@ -2013,18 +2014,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(
@@ -2038,7 +2121,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.