cypress-mailisk 3.0.3 → 3.1.0

package/README.md

@@ -212,6 +212,46 @@ 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',
+  sharedSecret: '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({
+  base32SecretKey: 'JBSWY3DPEHPK3PXP',
+  issuer: 'GitHub',
+});
+
+cy.mailiskDeviceCreateFromOtpAuthUrl({
+  otpAuthUrl: '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');
+```
+
 ## Common test cases
 
 ### Working with email attachments

package/package.json

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

package/src/mailiskCommands.d.ts

@@ -219,6 +219,129 @@ 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 */
+  expiresAt?: 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. */
+  sharedSecret: string;
+  /** Optional device display name. */
+  name?: string;
+  /** Optional future ISO expiration timestamp. */
+  expiresAt?: 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. */
+  expiresAt?: string;
+}
+
+export interface CreateBase32SecretKeyTotpDeviceParams {
+  /** Base32 secret key. */
+  base32SecretKey: 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. */
+  expiresAt?: string;
+}
+
+export interface CreateOtpAuthUrlTotpDeviceParams {
+  /** otpauth://totp URL with a secret query parameter. */
+  otpAuthUrl: 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. */
+  expiresAt?: string;
+}
+
+export interface TotpOtpResponse {
+  /** Generated one-time password code. */
+  code: string;
+  /** ISO timestamp when the code expires. */
+  expires: string;
+}
+
 declare global {
   namespace Cypress {
     interface Chainable {
@@ -292,6 +415,110 @@ 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>;
+
+      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>;
+
+      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,65 @@ 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();
+  }
+
+  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, options = {}) {
+    const encodedDeviceId = encodeURIComponent(this._requireNonEmptyString(deviceId, 'deviceId'));
+    return this._withRequest((request) => request.get(`api/devices/${encodedDeviceId}/otp`, options));
+  }
+
+  mailiskDeviceOtpBySharedSecret(sharedSecret, options = {}) {
+    const normalizedSharedSecret = this._requireNonEmptyString(sharedSecret, 'sharedSecret');
+    return this._withRequest((request) => request.post('api/devices/otp', { sharedSecret: normalizedSharedSecret }, options));
+  }
+
+  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'],
       },