@nauth-toolkit/client 0.1.111 → 0.1.114

package/dist/index.cjs

@@ -191,6 +191,7 @@ var defaultAdminEndpoints = {
   getUserSessions: "/users/:sub/sessions",
   logoutAll: "/users/:sub/logout-all",
   getMfaStatus: "/users/:sub/mfa/status",
+  getMfaDevices: "/users/:sub/mfa/devices",
   removeMfaDeviceById: "/mfa/devices/:deviceId",
   setPreferredMfaDevice: "/users/:sub/mfa/devices/:deviceId/preferred",
   setMfaExemption: "/mfa/exemption",
@@ -1151,21 +1152,25 @@ var AdminOperations = class {
     return this.get(path);
   }
   /**
-   * Set preferred MFA method for a user
+   * Get MFA devices for a user
    *
-   * @param sub - User UUID
-   * Remove MFA devices for a user
+   * Returns all active MFA devices for a user including device id, name, type, and isPreferred status.
    *
    * @param sub - User UUID
-   * @param method - MFA method to remove
-   * @returns Success message
+   * @returns Response containing array of MFA devices
    * @throws {NAuthClientError} If operation fails
    *
    * @example
    * ```typescript
-   * await client.admin.removeMfaDevices('user-uuid', 'sms');
+   * const result = await client.admin.getMfaDevices('user-uuid');
+   * console.log('Devices:', result.devices);
+   * // [{ id: 1, name: 'My Authenticator', type: 'totp', isPreferred: true, ... }]
    * ```
    */
+  async getMfaDevices(sub) {
+    const path = this.buildAdminUrl(this.adminEndpoints.getMfaDevices, { sub });
+    return this.get(path);
+  }
   /**
    * Remove a single MFA device by device ID (admin).
    *
@@ -1770,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;
@@ -2008,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(
@@ -2033,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.