OTP Device Sync Library Documentation (NPM)

The otp-device-sync library provides functions to retrieve OTP codes from SMS, email, and time-based sources, facilitating multi-factor authentication (MFA) management in automated testing environments. This documentation explains the installation, usage, and available functions in the otp-device-sync package.

Installation

Install the library from NPM:

npm install otp-device-sync

Importing Functions

The library exports three primary functions for retrieving OTPs from different sources:

import { getTimeBasedCode, getMailComponents, getSMSCode } from 'otp-device-sync'

Each function targets a specific OTP source (time-based, email, or SMS), allowing you to retrieve OTP codes dynamically for 2FA in automated tests.

Function Reference

1. getTimeBasedCode

Retrieves a Time-Based One-Time Password (TOTP) for a specified user and service.

const otpCode = await getTimeBasedCode(user, service, {
  verbose: true,
  registeredKey: 'YOUR_REGISTERED_KEY'
});

• Parameters:

  • user: The TOTP user label (e.g., account or email).
  • service: The TOTP issuer name.
  • options: { verbose?: boolean, registeredKey: string }

• Returns: Promise<string> - The OTP code.

2. getMailComponents

Retrieves OTP from an email, returning both the OTP code and email content.

const emailData = await getMailComponents(user, service, {
  verbose: true,
  timeout: 300000,
  registeredKey: 'YOUR_REGISTERED_KEY'
});

• Parameters:

  • user: The test user's email.
  • service: Identifier for the service sending the OTP.
  • options: { verbose?: boolean, timeout?: number, registeredKey: string }

• Returns: Promise<{ code: string, text: string, html: string }> - The OTP code, plain text, and HTML content of the email.

3. getSMSCode

Retrieves OTP sent by SMS, for MFA workflows based on text messages.

const smsOTP = await getSMSCode(user, service, {
  verbose: true,
  timeout: 300000,
  registeredKey: 'YOUR_REGISTERED_KEY'
});

• Parameters:

  • user: The test user's phone number.
  • service: SMS sender identifier.
  • options: { verbose?: boolean, timeout?: number, registeredKey: string }

• Returns: Promise<{ code: string }> - The OTP code.

Example Usage

Each function can be called in test scripts or any automated setup to handle OTP-based MFA. Here’s a sample using all three functions:

import { getTimeBasedCode, getMailComponents, getSMSCode } from 'otp-device-sync';

// Fetch TOTP
const otpCode = await getTimeBasedCode('[email protected]', 'ServiceName', {
  verbose: true,
  registeredKey: 'YOUR_REGISTERED_KEY'
});
console.log(`TOTP Code: ${otpCode}`);

// Fetch Email OTP
const emailData = await getMailComponents('[email protected]', 'ServiceName', {
  verbose: true,
  timeout: 300000,
  registeredKey: 'YOUR_REGISTERED_KEY'
});
console.log(`Email OTP: ${emailData.code}, Content: ${emailData.text}`);

// Fetch SMS OTP
const smsData = await getSMSCode('1234567890', 'ServiceName', {
  verbose: true,
  timeout: 300000,
  registeredKey: 'YOUR_REGISTERED_KEY'
});
console.log(`SMS OTP: ${smsData.code}`);

Notes

• Environment Configuration: Ensure API_BASE_URL is configured in your environment to connect to the backend OTP retrieval service.
• Error Handling: Each function provides verbose logging for error handling. Enable verbose: true in options to see detailed output for troubleshooting.
• Timeout: Adjust the timeout in getMailComponents and getSMSCode as needed.

This setup enables efficient MFA management in tests by automating OTP retrieval, making it ideal for end-to-end testing with OTP Device Sync.