cypress-mailisk 3.1.0 → 3.2.0

package/README.md

@@ -223,7 +223,7 @@ cy.mailiskDeviceList({ issuer: 'GitHub', username: 'qa@example.com' }).then((res
 
 cy.mailiskDeviceCreate({
   name: 'GitHub staging',
-  sharedSecret: 'JBSWY3DPEHPK3PXP',
+  shared_secret: 'JBSWY3DPEHPK3PXP',
 }).then((device) => {
   cy.mailiskDeviceOtpByDeviceId(device.id).then((otp) => {
     expect(otp.code).to.match(/^\d{6}$/);
@@ -240,18 +240,28 @@ cy.mailiskDeviceCreateCustom({
 });
 
 cy.mailiskDeviceCreateFromBase32SecretKey({
-  base32SecretKey: 'JBSWY3DPEHPK3PXP',
+  base32_secret_key: 'JBSWY3DPEHPK3PXP',
   issuer: 'GitHub',
 });
 
 cy.mailiskDeviceCreateFromOtpAuthUrl({
-  otpAuthUrl: 'otpauth://totp/GitHub:qa@example.com?secret=JBSWY3DPEHPK3PXP&issuer=GitHub',
+  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.1.0",
+  "version": "3.2.0",
   "description": "Mailisk library for Cypress",
   "keywords": [
     "mailisk",

package/src/mailiskCommands.d.ts

@@ -245,7 +245,7 @@ export interface TotpDevice {
   /** Source used to create the saved device */
   source: TotpDeviceSource;
   /** Optional expiration timestamp */
-  expiresAt?: string | null;
+  expires_at?: string | null;
   /** Date and time the device was created */
   created_at: string;
   /** Date and time the device was updated */
@@ -271,11 +271,11 @@ export interface TotpDeviceListResponse {
 
 export interface CreateTotpDeviceParams {
   /** Base32 shared secret. */
-  sharedSecret: string;
+  shared_secret: string;
   /** Optional device display name. */
   name?: string;
   /** Optional future ISO expiration timestamp. */
-  expiresAt?: string;
+  expires_at?: string;
 }
 
 export interface CreateCustomTotpDeviceParams {
@@ -294,12 +294,12 @@ export interface CreateCustomTotpDeviceParams {
   /** TOTP hash algorithm. */
   algorithm?: TotpAlgorithm;
   /** Optional future ISO expiration timestamp. */
-  expiresAt?: string;
+  expires_at?: string;
 }
 
 export interface CreateBase32SecretKeyTotpDeviceParams {
   /** Base32 secret key. */
-  base32SecretKey: string;
+  base32_secret_key: string;
   /** Optional device display name. */
   name?: string;
   /** Optional account label. */
@@ -313,12 +313,12 @@ export interface CreateBase32SecretKeyTotpDeviceParams {
   /** TOTP hash algorithm. */
   algorithm?: TotpAlgorithm;
   /** Optional future ISO expiration timestamp. */
-  expiresAt?: string;
+  expires_at?: string;
 }
 
 export interface CreateOtpAuthUrlTotpDeviceParams {
   /** otpauth://totp URL with a secret query parameter. */
-  otpAuthUrl: string;
+  otp_auth_url: string;
   /** Optional device display name override. */
   name?: string;
   /** Optional account label fallback. */
@@ -332,7 +332,7 @@ export interface CreateOtpAuthUrlTotpDeviceParams {
   /** TOTP hash algorithm, used only if missing from the URL. */
   algorithm?: TotpAlgorithm;
   /** Optional future ISO expiration timestamp. */
-  expiresAt?: string;
+  expires_at?: string;
 }
 
 export interface TotpOtpResponse {
@@ -342,6 +342,16 @@ export interface TotpOtpResponse {
   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 {
@@ -494,6 +504,23 @@ declare global {
         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.
@@ -507,6 +534,23 @@ declare global {
         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.

package/src/mailiskCommands.js

@@ -216,6 +216,33 @@ class MailiskCommands {
     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();
@@ -239,14 +266,20 @@ class MailiskCommands {
     return this._withRequest((request) => request.post('api/devices/otpauth-url', input, options));
   }
 
-  mailiskDeviceOtpByDeviceId(deviceId, options = {}) {
+  mailiskDeviceOtpByDeviceId(deviceId, paramsOrOptions = {}, options = {}) {
+    const [params, requestOptions] = this._getTotpOtpArgs(paramsOrOptions, options, arguments.length >= 3);
     const encodedDeviceId = encodeURIComponent(this._requireNonEmptyString(deviceId, 'deviceId'));
-    return this._withRequest((request) => request.get(`api/devices/${encodedDeviceId}/otp`, options));
+    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, options = {}) {
+  mailiskDeviceOtpBySharedSecret(sharedSecret, paramsOrOptions = {}, options = {}) {
+    const [params, requestOptions] = this._getTotpOtpArgs(paramsOrOptions, options, arguments.length >= 3);
     const normalizedSharedSecret = this._requireNonEmptyString(sharedSecret, 'sharedSecret');
-    return this._withRequest((request) => request.post('api/devices/otp', { sharedSecret: normalizedSharedSecret }, options));
+    const body = { shared_secret: normalizedSharedSecret, ...this._buildTotpOtpBody(params) };
+    return this._withRequest((request) => request.post('api/devices/otp', body, requestOptions));
   }
 
   mailiskDeviceDelete(deviceId, options = {}) {