cypress-mailisk 3.0.3 → 3.2.0

package/README.md

@@ -212,6 +212,56 @@ cy.mailiskListSmsNumbers().then((response) => {
 });
 ```
 
+### TOTP authenticator devices
+
+These commands manage saved Mailisk Authenticator devices and generate OTP codes through the Mailisk API. Use an organisation API key for these endpoints.
+
+```js
+cy.mailiskDeviceList({ issuer: 'GitHub', username: 'qa@example.com' }).then((response) => {
+  const devices = response.items;
+});
+
+cy.mailiskDeviceCreate({
+  name: 'GitHub staging',
+  shared_secret: 'JBSWY3DPEHPK3PXP',
+}).then((device) => {
+  cy.mailiskDeviceOtpByDeviceId(device.id).then((otp) => {
+    expect(otp.code).to.match(/^\d{6}$/);
+  });
+});
+
+cy.mailiskDeviceCreateCustom({
+  secret: 'JBSWY3DPEHPK3PXP',
+  username: 'qa@example.com',
+  issuer: 'GitHub',
+  digits: 6,
+  period: 30,
+  algorithm: 'SHA1',
+});
+
+cy.mailiskDeviceCreateFromBase32SecretKey({
+  base32_secret_key: 'JBSWY3DPEHPK3PXP',
+  issuer: 'GitHub',
+});
+
+cy.mailiskDeviceCreateFromOtpAuthUrl({
+  otp_auth_url: 'otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub',
+});
+
+cy.mailiskDeviceOtpBySharedSecret('JBSWY3DPEHPK3PXP'); // one-off code without saving a device
+cy.mailiskDeviceDelete('9b1f6ec0-b90d-4bd8-8dd0-f6b2d5138273');
+```
+
+To avoid receiving a TOTP code right before it expires, pass min_seconds_until_expire. If the current code has fewer seconds remaining, Mailisk waits for the next code before returning.
+
+```js
+cy.mailiskDeviceOtpByDeviceId(device.id, { min_seconds_until_expire: 10 }).then((otp) => {
+  cy.get('#code').type(otp.code);
+});
+
+cy.mailiskDeviceOtpBySharedSecret('JBSWY3DPEHPK3PXP', { min_seconds_until_expire: 10 });
+```
+
 ## Common test cases
 
 ### Working with email attachments

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress-mailisk",
-  "version": "3.0.3",
+  "version": "3.2.0",
   "description": "Mailisk library for Cypress",
   "keywords": [
     "mailisk",

package/src/mailiskCommands.d.ts

@@ -219,6 +219,139 @@ export interface SendVirtualSmsParams {
   body: string;
 }
 
+export type TotpAlgorithm = 'SHA1' | 'SHA256' | 'SHA512';
+
+export type KnownTotpDeviceSource = 'shared_secret' | 'custom' | 'base32_secret_key' | 'otpauth_url';
+
+export type TotpDeviceSource = KnownTotpDeviceSource | (string & {});
+
+export interface TotpDevice {
+  /** Unique identifier for the saved authenticator device */
+  id: string;
+  /** Unique identifier for the organisation */
+  organisation_id: string;
+  /** Device display name */
+  name: string;
+  /** Account label, if one is specified */
+  username?: string | null;
+  /** Issuer/app label, if one is specified */
+  issuer?: string | null;
+  /** Number of digits in generated OTP codes */
+  digits: number;
+  /** OTP validity period in seconds */
+  period: number;
+  /** TOTP hash algorithm */
+  algorithm: TotpAlgorithm;
+  /** Source used to create the saved device */
+  source: TotpDeviceSource;
+  /** Optional expiration timestamp */
+  expires_at?: string | null;
+  /** Date and time the device was created */
+  created_at: string;
+  /** Date and time the device was updated */
+  updated_at: string;
+}
+
+export interface TotpDeviceListParams {
+  /** Maximum number of devices returned. */
+  limit?: number;
+  /** Number of devices to skip. */
+  offset?: number;
+  /** Case-insensitive partial username match. */
+  username?: string;
+  /** Case-insensitive partial issuer match. */
+  issuer?: string;
+}
+
+export interface TotpDeviceListResponse {
+  total_count: number;
+  options: TotpDeviceListParams;
+  items: TotpDevice[];
+}
+
+export interface CreateTotpDeviceParams {
+  /** Base32 shared secret. */
+  shared_secret: string;
+  /** Optional device display name. */
+  name?: string;
+  /** Optional future ISO expiration timestamp. */
+  expires_at?: string;
+}
+
+export interface CreateCustomTotpDeviceParams {
+  /** Base32 shared secret. */
+  secret: string;
+  /** Optional device display name. */
+  name?: string;
+  /** Optional account label. */
+  username?: string;
+  /** Optional issuer/app label. */
+  issuer?: string;
+  /** Number of digits in generated OTP codes. */
+  digits?: 6 | 8;
+  /** OTP validity period in seconds. */
+  period?: number;
+  /** TOTP hash algorithm. */
+  algorithm?: TotpAlgorithm;
+  /** Optional future ISO expiration timestamp. */
+  expires_at?: string;
+}
+
+export interface CreateBase32SecretKeyTotpDeviceParams {
+  /** Base32 secret key. */
+  base32_secret_key: string;
+  /** Optional device display name. */
+  name?: string;
+  /** Optional account label. */
+  username?: string;
+  /** Optional issuer/app label. */
+  issuer?: string;
+  /** Number of digits in generated OTP codes. */
+  digits?: 6 | 8;
+  /** OTP validity period in seconds. */
+  period?: number;
+  /** TOTP hash algorithm. */
+  algorithm?: TotpAlgorithm;
+  /** Optional future ISO expiration timestamp. */
+  expires_at?: string;
+}
+
+export interface CreateOtpAuthUrlTotpDeviceParams {
+  /** otpauth://totp URL with a secret query parameter. */
+  otp_auth_url: string;
+  /** Optional device display name override. */
+  name?: string;
+  /** Optional account label fallback. */
+  username?: string;
+  /** Optional issuer/app label fallback. */
+  issuer?: string;
+  /** Number of digits in generated OTP codes, used only if missing from the URL. */
+  digits?: 6 | 8;
+  /** OTP validity period in seconds, used only if missing from the URL. */
+  period?: number;
+  /** TOTP hash algorithm, used only if missing from the URL. */
+  algorithm?: TotpAlgorithm;
+  /** Optional future ISO expiration timestamp. */
+  expires_at?: string;
+}
+
+export interface TotpOtpResponse {
+  /** Generated one-time password code. */
+  code: string;
+  /** ISO timestamp when the code expires. */
+  expires: string;
+}
+
+export interface TotpOtpParams {
+  /**
+   * Minimum number of seconds the generated code must remain valid.
+   *
+   * When the current TOTP code expires sooner than this value, the API waits
+   * for the next code before responding.
+   */
+  min_seconds_until_expire?: number;
+}
+
 declare global {
   namespace Cypress {
     interface Chainable {
@@ -292,6 +425,144 @@ declare global {
          */
         options?: Partial<Cypress.RequestOptions>,
       ): Cypress.Chainable<ListSmsNumbersResponse>;
+
+      mailiskDeviceList(
+        /**
+         * List filters and pagination options.
+         */
+        params?: TotpDeviceListParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpDeviceListResponse>;
+
+      mailiskDeviceCreate(
+        /**
+         * Saved device input using default TOTP settings.
+         */
+        input: CreateTotpDeviceParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpDevice>;
+
+      mailiskDeviceCreateCustom(
+        /**
+         * Saved device input using custom TOTP settings.
+         */
+        input: CreateCustomTotpDeviceParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpDevice>;
+
+      mailiskDeviceCreateFromBase32SecretKey(
+        /**
+         * Saved device input using a Base32 secret key.
+         */
+        input: CreateBase32SecretKeyTotpDeviceParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpDevice>;
+
+      mailiskDeviceCreateFromOtpAuthUrl(
+        /**
+         * Saved device input using an otpauth URL.
+         */
+        input: CreateOtpAuthUrlTotpDeviceParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpDevice>;
+
+      mailiskDeviceOtpByDeviceId(
+        /**
+         * Saved device ID.
+         */
+        deviceId: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpOtpResponse>;
+
+      mailiskDeviceOtpByDeviceId(
+        /**
+         * Saved device ID.
+         */
+        deviceId: string,
+        /**
+         * OTP generation parameters.
+         */
+        params?: TotpOtpParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpOtpResponse>;
+
+      mailiskDeviceOtpBySharedSecret(
+        /**
+         * Shared secret for one-off OTP generation.
+         */
+        sharedSecret: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpOtpResponse>;
+
+      mailiskDeviceOtpBySharedSecret(
+        /**
+         * Shared secret for one-off OTP generation.
+         */
+        sharedSecret: string,
+        /**
+         * OTP generation parameters.
+         */
+        params?: TotpOtpParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<TotpOtpResponse>;
+
+      mailiskDeviceDelete(
+        /**
+         * Saved device ID.
+         */
+        deviceId: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<void>;
     }
   }
 }

package/src/mailiskCommands.js

@@ -10,6 +10,14 @@ class MailiskCommands {
       'mailiskDownloadAttachment',
       'mailiskSearchSms',
       'mailiskListSmsNumbers',
+      'mailiskDeviceList',
+      'mailiskDeviceCreate',
+      'mailiskDeviceCreateCustom',
+      'mailiskDeviceCreateFromBase32SecretKey',
+      'mailiskDeviceCreateFromOtpAuthUrl',
+      'mailiskDeviceOtpByDeviceId',
+      'mailiskDeviceOtpBySharedSecret',
+      'mailiskDeviceDelete',
     ];
   }
 
@@ -186,6 +194,98 @@ class MailiskCommands {
   mailiskListSmsNumbers(options = {}) {
     return this._withRequest((request) => request.get(`api/sms/numbers`, options));
   }
+
+  _buildUrlParams(params = {}) {
+    const urlParams = new URLSearchParams();
+    for (const key in params) {
+      let value = params[key];
+      if (typeof value === 'string') {
+        value = value.trim();
+      }
+      if (value !== undefined && value !== null && value !== '') {
+        urlParams.set(key, value.toString());
+      }
+    }
+    return urlParams;
+  }
+
+  _requireNonEmptyString(value, label) {
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`${label} must be a non-empty string.`);
+    }
+    return value.trim();
+  }
+
+  _hasTotpOtpParam(value) {
+    return (
+      value &&
+      typeof value === 'object' &&
+      Object.prototype.hasOwnProperty.call(value, 'min_seconds_until_expire')
+    );
+  }
+
+  _getTotpOtpArgs(paramsOrOptions = {}, options = {}, hasRequestOptions = false) {
+    if (hasRequestOptions || this._hasTotpOtpParam(paramsOrOptions)) {
+      return [{ ...(paramsOrOptions || {}) }, options];
+    }
+    return [{}, paramsOrOptions];
+  }
+
+  _buildTotpOtpUrlParams(params = {}) {
+    return this._buildUrlParams(params);
+  }
+
+  _buildTotpOtpBody(params = {}) {
+    const body = {};
+    if (params.min_seconds_until_expire != null) {
+      body.min_seconds_until_expire = params.min_seconds_until_expire;
+    }
+    return body;
+  }
+
+  mailiskDeviceList(params = {}, options = {}) {
+    const urlParams = this._buildUrlParams(params);
+    const query = urlParams.toString();
+    const path = query ? `api/devices?${query}` : 'api/devices';
+    return this._withRequest((request) => request.get(path, options));
+  }
+
+  mailiskDeviceCreate(input, options = {}) {
+    return this._withRequest((request) => request.post('api/devices', input, options));
+  }
+
+  mailiskDeviceCreateCustom(input, options = {}) {
+    return this._withRequest((request) => request.post('api/devices/custom', input, options));
+  }
+
+  mailiskDeviceCreateFromBase32SecretKey(input, options = {}) {
+    return this._withRequest((request) => request.post('api/devices/base32-secret-key', input, options));
+  }
+
+  mailiskDeviceCreateFromOtpAuthUrl(input, options = {}) {
+    return this._withRequest((request) => request.post('api/devices/otpauth-url', input, options));
+  }
+
+  mailiskDeviceOtpByDeviceId(deviceId, paramsOrOptions = {}, options = {}) {
+    const [params, requestOptions] = this._getTotpOtpArgs(paramsOrOptions, options, arguments.length >= 3);
+    const encodedDeviceId = encodeURIComponent(this._requireNonEmptyString(deviceId, 'deviceId'));
+    const urlParams = this._buildTotpOtpUrlParams(params);
+    const query = urlParams.toString();
+    const path = query ? `api/devices/${encodedDeviceId}/otp?${query}` : `api/devices/${encodedDeviceId}/otp`;
+    return this._withRequest((request) => request.get(path, requestOptions));
+  }
+
+  mailiskDeviceOtpBySharedSecret(sharedSecret, paramsOrOptions = {}, options = {}) {
+    const [params, requestOptions] = this._getTotpOtpArgs(paramsOrOptions, options, arguments.length >= 3);
+    const normalizedSharedSecret = this._requireNonEmptyString(sharedSecret, 'sharedSecret');
+    const body = { shared_secret: normalizedSharedSecret, ...this._buildTotpOtpBody(params) };
+    return this._withRequest((request) => request.post('api/devices/otp', body, requestOptions));
+  }
+
+  mailiskDeviceDelete(deviceId, options = {}) {
+    const encodedDeviceId = encodeURIComponent(this._requireNonEmptyString(deviceId, 'deviceId'));
+    return this._withRequest((request) => request.del(`api/devices/${encodedDeviceId}`, options).then(() => undefined));
+  }
 }
 
 module.exports = MailiskCommands;

package/src/request.js

@@ -6,6 +6,7 @@ class Request {
     this.apiKey = options.apiKey;
     this.headers = {
       Accept: 'application/json',
+      'Content-Type': 'application/json',
       'X-Api-Key': `${this.apiKey}`,
       'User-Agent': `cypress-mailisk/${pkg.version}`,
     };
@@ -22,6 +23,7 @@ class Request {
       url: `${this.apiUrl}${path}`,
       headers: {
         Accept: this.headers.Accept,
+        'Content-Type': this.headers['Content-Type'],
         'X-Api-Key': this.headers['X-Api-Key'],
         'User-Agent': this.headers['User-Agent'],
       },