cypress-mailisk 2.0.1 → 2.2.1

package/README.md

@@ -1,17 +1,32 @@
 # cypress-mailisk
 
-## Install with npm
+Mailisk is an end-to-end email and SMS testing platform. It allows you to receive emails and SMS messages with code to automate tests.
+
+- Get a unique subdomain and unlimited email addresses for free.
+- Easily automate E2E password reset and account verification by catching emails.
+- Receive SMS messages and automate SMS tests.
+- Virtual SMTP and SMS support to test without 3rd party clients.
+
+## Get started
+
+For a more step-by-step walkthrough see the [Cypress Guide](https://docs.mailisk.com/guides/cypress.html).
+
+### Installation
+
+#### Install with npm
 
 ```shell
 npm install --save-dev cypress-mailisk
 ```
 
-## Install with Yarn
+#### Install with Yarn
 
 ```shell
 yarn add cypress-mailisk --dev
 ```
 
+#### Add to Cypress
+
 After installing the package add the following in your project's `cypress/support/e2e.js`:
 
 ```js
@@ -36,78 +51,205 @@ The cypress-mailisk plugin provides additional commands which can be accessed on
 
 ### cy.mailiskSearchInbox
 
-This is the main command to interact with Mailisk, it wraps the [Search Inbox](/api-reference/search-inbox) endpoint.
+This is the main command to interact with Mailisk, it wraps the [Search Inbox](/api-reference/search-inbox) endpoint. See the reference documentation for the full list of filters and their description.
 
 ```js
-cy.mailiskSearchInbox('yournamespace', { to_addr_prefix: 'test.user@' }).then((response) => {
-  const emails = response.data;
-  // ...
-});
+cy.mailiskSearchInbox('yournamespace', { to_addr_prefix: 'test.user@', subject_includes: 'register' }).then(
+  (response) => {
+    const emails = response.data;
+    expect(emails).to.not.be.empty;
+  },
+);
 ```
 
-This Cypress command does a few extra things out of the box compared to calling the raw API directly:
+This command does a few extra things out of the box:
 
-- By default it uses the `wait` flag. This means the call won't return until at least one email is received. Disabling this flag via `wait: false` can cause it to return an empty response immediately.
-- The request timeout is adjustable by passing `timeout` in the request options. By default it uses a timeout of 5 minutes.
-- By default it returns emails in the last 15 minutes. This ensures that only new emails are returned. This can be overriden by passing the `from_timestamp` parameter (`from_timestamp: 0` will disable filtering by email age).
+- Waits until at least one new email arrives (override with `wait: false`).
+- Times out after 5 minutes if nothing shows up (adjust via `requestOptions.timeout`).
+- Ignores messages older than 15 minutes to avoid picking up leftovers from previous tests (change via `from_timestamp`).
+
+#### Quick examples
 
 ```js
-// timeout of 5 minute
+// wait up to the default 5 min for *any* new mail
 cy.mailiskSearchInbox(namespace);
-// timeout of 1 minute
+// custom 60-second timeout
 cy.mailiskSearchInbox(namespace, {}, { timeout: 1000 * 60 });
-// returns immediately, even if the result would be empty
+// polling pattern — return immediately, even if inbox is empty
 cy.mailiskSearchInbox(namespace, { wait: false });
+// returns the last 20 emails in the namespace immediately
+cy.mailiskSearchInbox(namespace, { wait: false, from_timestamp: 0, limit: 20 });
 ```
 
-For the full list of filters and their description see the [Search Inbox](/api-reference/search-inbox#request-1) endpoint reference.
-
-### Filter by TO address
-
-The `to_addr_prefix` option allows filtering by the email's TO address. Specifically the TO address has to start with this.
+#### Filter by destination address
 
-For example, if someone sends an email to `my-user-1@yournamespace.mailisk.net`, you can filter it by using `my-user-1@`:
+A common pattern is to wait for the email your UI just triggered (e.g. password-reset).
+Pass `to_addr_prefix` so you don’t pick up stale messages:
 
 ```js
 cy.mailiskSearchInbox(namespace, {
-  to_addr_prefix: 'my-user-1@',
+  to_addr_prefix: `test.user@${namespace}.mailisk.net`,
+}).then((response) => {
+  const emails = response.data;
+  expect(emails).to.not.be.empty;
 });
 ```
 
-### Filter by FROM address
-
-The `from_addr_includes` option allows filtering by the email's FROM address. Specifically the TO address has to include this. Note that this is different from the to address as it is _includes_ not _prefix_.
+#### Filter by sender address
 
-For example, if someone sends an email from the `example.com` domain we could filter like so:
+Use `from_addr_includes` to narrow results to a sender or domain. This is useful when multiple systems write to the same namespace but only one sender matters for the test.
 
 ```js
 cy.mailiskSearchInbox(namespace, {
   from_addr_includes: '@example.com',
+}).then((response) => {
+  const emails = response.data;
+  expect(emails).to.not.be.empty;
 });
 ```
 
-If we know a specific email address we want to listen to we can do this:
+#### Filter by subject contents
+
+The `subject_includes` filter helps when the UI sends different notification types from the same sender. Matching is case-insensitive and only requires the provided string to be present.
 
 ```js
 cy.mailiskSearchInbox(namespace, {
-  from_addr_includes: 'no-reply@example.com',
+  to_addr_prefix: `test.user@${namespace}.mailisk.net`,
+  subject_includes: 'password reset',
+}).then((response) => {
+  const emails = response.data;
+  expect(emails).to.not.be.empty;
 });
 ```
 
-### Filter by Subject
+### cy.mailiskGetAttachment
 
-The `subject_includes` option allows filtering by the email's Subject. Specifically the Subject has to include this (case-insensitive).
+This command retrieves attachment metadata including download URL, filename, content type, and size.
 
-If we're testing password reset that sends an email with the subject `Password reset request`. We could filter by something like this:
+```js
+cy.mailiskGetAttachment('attachment-id').then((attachment) => {
+  console.log(attachment.data.filename);
+  console.log(attachment.data.content_type);
+  console.log(attachment.data.size);
+});
+```
+
+### cy.mailiskDownloadAttachment
+
+This command downloads the actual attachment content as a Buffer. It first retrieves the attachment metadata, then downloads the file from the provided download URL.
 
 ```js
-cy.mailiskSearchInbox(namespace, {
-  subject_includes: 'password reset request',
+cy.mailiskDownloadAttachment('attachment-id').then((buffer) => {
+  cy.writeFile('downloads/attachment.pdf', buffer);
+});
+```
+
+### cy.mailiskSearchSms
+
+This is the main command to interact with Mailisk SMS, it wraps the [Search SMS](/api-reference/search-sms) endpoint. Use a phone number that is registered to your account.
+
+```js
+cy.mailiskSearchSms('phoneNumber', { from_date: new Date('2023-01-01T00:00:00Z'), limit: 5 }).then((response) => {
+  const smsMessages = response.data;
+});
+```
+
+This Cypress command does a few extra things out of the box compared to calling the raw API directly:
+
+- Waits until at least one SMS matches the filters (override with `wait: false`).
+- Times out after 5 minutes if nothing shows up (adjust via `requestOptions.timeout`).
+- Ignores SMS older than 15 minutes by default (override with `from_date`).
+
+#### Quick examples
+
+```js
+// wait up to the default 5 min for *any* new SMS sent to the phone number
+cy.mailiskSearchSms('phoneNumber');
+// custom 60-second timeout
+cy.mailiskSearchSms('phoneNumber', {}, { timeout: 1000 * 60 });
+// polling pattern — return immediately, even if inbox is empty
+cy.mailiskSearchSms('phoneNumber', { wait: false });
+// returns the last 20 SMS messages for the phone number immediately
+cy.mailiskSearchSms('phoneNumber', { wait: false, from_date: new Date(0), limit: 20 });
+```
+
+#### Filter by sender phone number
+
+Use `from_number` to narrow results to a specific phone number.
+
+```js
+cy.mailiskSearchSms('phoneNumber', {
+  from_number: '1234567890',
+}).then((response) => {
+  const smsMessages = response.data;
+});
+```
+
+#### Filter by body contents
+
+Use `body` to narrow results to a specific message body.
+
+```js
+cy.mailiskSearchSms('phoneNumber', {
+  body: 'Here is your code:',
+}).then((response) => {
+  const smsMessages = response.data;
+});
+```
+
+### cy.mailiskListSmsNumbers
+
+This command lists the SMS numbers available to the current API key.
+
+```js
+cy.mailiskListSmsNumbers().then((response) => {
+  const smsNumbers = response.data;
+  expect(smsNumbers).to.not.be.empty;
 });
 ```
 
 ## Common test cases
 
+### Working with email attachments
+
+This example demonstrates how to search for emails with attachments and download them:
+
+```js
+describe('Test email attachments', () => {
+  const namespace = 'yournamespace';
+  const testEmailAddr = `test.user@${namespace}.mailisk.net`;
+
+  it('Finds email with attachment and downloads it', () => {
+    cy.mailiskSearchInbox(namespace, {
+      to_addr_prefix: testEmailAddr,
+      subject_includes: 'invoice',
+    }).then((response) => {
+      expect(response.data).to.not.be.empty;
+      const email = response.data[0];
+
+      // Check if email has attachments
+      expect(email.attachments).to.not.be.empty;
+      const attachment = email.attachments[0];
+
+      // Get attachment metadata
+      cy.mailiskGetAttachment(attachment.id).then((attachmentData) => {
+        expect(attachmentData.data.filename).to.contain('.pdf');
+        expect(attachmentData.data.content_type).to.equal('application/pdf');
+
+        // Download the attachment
+        cy.mailiskDownloadAttachment(attachment.id).then((buffer) => {
+          // Save to downloads folder
+          cy.writeFile(`downloads/${attachmentData.data.filename}`, buffer);
+
+          // Verify file was downloaded
+          cy.readFile(`downloads/${attachmentData.data.filename}`).should('exist');
+        });
+      });
+    });
+  });
+});
+```
+
 ### Password reset page
 
 This example demonstrates going to a password reset page, requesting a new password, receiving reset code link via email and finally setting the new password.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress-mailisk",
-  "version": "2.0.1",
+  "version": "2.2.1",
   "description": "Mailisk library for Cypress",
   "keywords": [
     "mailisk",
@@ -13,7 +13,10 @@
   "main": "index.js",
   "types": "src/mailiskCommands.d.ts",
   "scripts": {
-    "tsc": "node_modules/.bin/tsc src/mailiskCommands.d.ts --types node"
+    "tsc": "node_modules/.bin/tsc src/mailiskCommands.d.ts --types node",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
   },
   "peerDependencies": {
     "cypress": ">= 2.1.0"
@@ -32,6 +35,8 @@
   },
   "homepage": "https://github.com/mailisk-app/cypress-mailisk#readme",
   "devDependencies": {
-    "typescript": "^4.7.4"
+    "typescript": "^4.7.4",
+    "jest": "^29.0.0",
+    "@jest/globals": "^29.0.0"
   }
 }

package/src/mailiskCommands.d.ts

@@ -7,6 +7,17 @@ export interface EmailAddress {
   name?: string;
 }
 
+export interface EmailAttachment {
+  /** Unique identifier for the attachment */
+  id: string;
+  /** Filename of the attachment */
+  filename: string;
+  /** Content type of the attachment */
+  content_type: string;
+  /** Size in bytes of the attachment */
+  size: number;
+}
+
 export interface Email {
   /** Namespace scoped ID */
   id: string;
@@ -32,6 +43,46 @@ export interface Email {
   expires_timestamp: number;
   /** The spam score as reported by SpamAssassin */
   spam_score?: number;
+  /** The headers of the email */
+  headers?: Record<string, string>;
+  /** The attachments of the email */
+  attachments?: EmailAttachment[];
+}
+
+export interface SmsMessage {
+  /** Unique identifier for the message */
+  id: string;
+  /** Unique identifier for the SMS phone number */
+  sms_phone_number_id: string;
+  /** Body of the message */
+  body: string;
+  /** From number of the message */
+  from_number: string;
+  /** To number of the message */
+  to_number: string;
+  /** Provider message ID */
+  provider_message_id?: string;
+  /** Date and time the message was created */
+  created_at: string;
+  /** Direction of the message */
+  direction: 'inbound' | 'outbound';
+}
+
+export interface SmsNumber {
+  /** Unique identifier for the SMS number */
+  id: string;
+  /** Unique identifier for the organisation */
+  organisation_id: string;
+  /** Status of the SMS number */
+  status: 'requested' | 'active' | 'disabled';
+  /** Country of the SMS number */
+  country: string;
+  /** SMS Phone number */
+  phone_number?: string;
+  /** Date and time the SMS number was created */
+  created_at: string;
+  /** Date and time the SMS number was updated */
+  updated_at: string;
 }
 
 export interface SearchInboxParams {
@@ -92,9 +143,87 @@ export interface SearchInboxResponse {
   data: Email[];
 }
 
+export interface SmtpSettings {
+  data: {
+    host: string;
+    port: number;
+    username: string;
+    password: string;
+  };
+}
+
+export interface GetAttachmentResponse {
+  data: {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    expires_at: string | null;
+    download_url: string;
+  };
+}
+
+export interface ListNamespacesResponse {
+  total_count: number;
+  data: { id: string; namespace: string }[];
+}
+
+export interface SearchSmsMessagesParams {
+  /**
+   * The maximum number of SMS messages returned (1-100), used alongside `offset` for pagination.
+   */
+  limit?: number;
+  /**
+   * The number of SMS messages to skip/ignore, used alongside `limit` for pagination.
+   */
+  offset?: number;
+  /**
+   * Filter messages by body contents (case insensitive).
+   */
+  body?: string;
+  /**
+   * Filter messages by sender phone number prefix.
+   */
+  from_number?: string;
+  /**
+   * Filter messages created on or after this date (Date object or ISO 8601 string).
+   */
+  from_date?: Date | string;
+  /**
+   * Filter messages created on or before this date (Date object or ISO 8601 string).
+   */
+  to_date?: Date | string;
+  /**
+   * When true, keep the request open until at least one SMS is returned.
+   */
+  wait?: boolean;
+}
+
+export interface SearchSmsMessagesResponse {
+  total_count: number;
+  options: SearchSmsMessagesParams;
+  data: SmsMessage[];
+}
+
+export interface ListSmsNumbersResponse {
+  total_count: number;
+  data: SmsNumber[];
+}
+
+export interface SendVirtualSmsParams {
+  /** The phone number to send the SMS from */
+  from_number: string;
+  /** The phone number to send the SMS to */
+  to_number: string;
+  /** The body of the SMS message */
+  body: string;
+}
+
 declare global {
   namespace Cypress {
     interface Chainable {
+      mailiskListNamespaces(): Cypress.Chainable<ListNamespacesResponse>;
+
       mailiskSearchInbox(
         /**
          * The unique namespace to search.
@@ -111,6 +240,58 @@ declare global {
          */
         options?: Partial<Cypress.RequestOptions>,
       ): Cypress.Chainable<SearchInboxResponse>;
+
+      mailiskGetAttachment(
+        /**
+         * The attachment ID to retrieve.
+         */
+        attachmentId: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<GetAttachmentResponse>;
+
+      mailiskDownloadAttachment(
+        /**
+         * The attachment ID to download.
+         */
+        attachmentId: string,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<Buffer>;
+
+      mailiskSearchSms(
+        /**
+         * The phone number to search.
+         */
+        phoneNumber: string,
+        /**
+         * Search parameters.
+         */
+        params?: SearchSmsMessagesParams,
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<SearchSmsMessagesResponse>;
+
+      mailiskListSmsNumbers(
+        /**
+         * Request options.
+         *
+         * See https://docs.cypress.io/api/commands/request#Arguments
+         */
+        options?: Partial<Cypress.RequestOptions>,
+      ): Cypress.Chainable<ListSmsNumbersResponse>;
     }
   }
 }

package/src/mailiskCommands.js

@@ -2,23 +2,31 @@ const Request = require('./request');
 
 class MailiskCommands {
   static get cypressCommands() {
-    return ['mailiskSetApiKey', 'mailiskListNamespaces', 'mailiskSearchInbox'];
+    return [
+      'mailiskSetApiKey',
+      'mailiskListNamespaces',
+      'mailiskSearchInbox',
+      'mailiskGetAttachment',
+      'mailiskDownloadAttachment',
+      'mailiskSearchSms',
+      'mailiskListSmsNumbers',
+    ];
   }
 
   constructor() {
-    const defaultApiKey = Cypress.env('MAILISK_API_KEY');
-    this.mailiskSetApiKey(defaultApiKey);
+    const apiKey = Cypress.env('MAILISK_API_KEY');
+    this.mailiskSetApiKey(apiKey);
   }
 
   mailiskSetApiKey(apiKey) {
-    this.request = new Request({ apiKey, baseUrl: Cypress.env('MAILISK_API_URL') });
+    this.request = new Request({ apiKey, apiUrl: Cypress.env('MAILISK_API_URL') });
   }
 
   mailiskListNamespaces() {
     return this.request.get('api/namespaces');
   }
 
-  _mailiskSearchAction(namespace, _options, urlParams, startTime, nextTimeout) {
+  _mailiskSearchInboxAction(namespace, _options, urlParams, startTime, nextTimeout) {
     return this.request
       .get(`api/emails/${namespace}/inbox?${urlParams.toString()}`, { ..._options, timeout: nextTimeout })
       .then((response) => {
@@ -27,27 +35,27 @@ class MailiskCommands {
         }
         const timeout = Math.max(_options.timeout - (Date.now() - startTime), 1);
         cy.wait(Math.min(timeout, 9000), { log: false });
-        return this._mailiskSearchAction(namespace, _options, urlParams, startTime, timeout);
+        return this._mailiskSearchInboxAction(namespace, _options, urlParams, startTime, timeout);
       });
   }
 
-  mailiskSearchInbox(namespace, params, options = {}) {
+  mailiskSearchInbox(namespace, params = {}, options = {}) {
     let _params = { ...params };
 
     // default from_timestamp, 15 minutes before starting this request
-    if (params.from_timestamp == null) {
-      _params.from_timestamp = Math.floor(new Date().getTime() / 1000) - 15 * 60;
+    if (_params.from_timestamp == null) {
+      _params.from_timestamp = Math.floor(Date.now() / 1000) - 15 * 60;
     }
 
     // by default wait for email
-    if (params.wait !== false) {
+    if (_params.wait !== false) {
       _params.wait = true;
     }
 
     const urlParams = new URLSearchParams();
     for (const key in _params) {
       const value = _params[key];
-      if (value) urlParams.set(key, value.toString());
+      if (value !== undefined && value !== null) urlParams.set(key, value.toString());
     }
 
     let _options = { ...options };
@@ -61,11 +69,81 @@ class MailiskCommands {
     if (_params.wait) {
       urlParams.delete('wait');
       const startTime = Date.now();
-      return this._mailiskSearchAction(namespace, _options, urlParams, startTime, _options.timeout);
+      return this._mailiskSearchInboxAction(namespace, _options, urlParams, startTime, _options.timeout);
     } else {
       return this.request.get(`api/emails/${namespace}/inbox?${urlParams.toString()}`, _options);
     }
   }
+
+  mailiskGetAttachment(attachmentId, options = {}) {
+    return this.request.get(`api/attachments/${attachmentId}`, options);
+  }
+
+  mailiskDownloadAttachment(attachmentId, options = {}) {
+    return this.mailiskGetAttachment(attachmentId, options).then((attachment) => {
+      return this.request.getBinary(attachment.data.download_url, options);
+    });
+  }
+
+  _mailiskSearchSmsAction(phoneNumber, _options, urlParams, startTime, nextTimeout) {
+    return this.request
+      .get(`api/sms/${phoneNumber}/messages?${urlParams.toString()}`, { ..._options, timeout: nextTimeout })
+      .then((response) => {
+        if (response.total_count !== 0) {
+          return response;
+        }
+        const timeout = Math.max(_options.timeout - (Date.now() - startTime), 1);
+        cy.wait(Math.min(timeout, 9000), { log: false });
+        return this._mailiskSearchSmsAction(phoneNumber, _options, urlParams, startTime, timeout);
+      });
+  }
+
+  mailiskSearchSms(phoneNumber, params = {}, options = {}) {
+    let _params = { ...params };
+
+    // default from_date, 15 minutes before starting this request
+    if (_params.from_date == null) {
+      _params.from_date = new Date(Date.now() - 15 * 60 * 1000);
+    }
+
+    // by default wait for email
+    if (params.wait !== false) {
+      _params.wait = true;
+    }
+
+    if (_params.from_date instanceof Date) {
+      _params.from_date = _params.from_date.toISOString();
+    }
+    if (_params.to_date instanceof Date) {
+      _params.to_date = _params.to_date.toISOString();
+    }
+
+    const urlParams = new URLSearchParams();
+    for (const key in _params) {
+      const value = _params[key];
+      if (value !== undefined && value !== null) urlParams.set(key, value.toString());
+    }
+
+    let _options = { ...options };
+
+    // by default wait 5 minutes for emails
+    if (_params.wait && !options.timeout) {
+      _options.timeout = 1000 * 60 * 5;
+    }
+
+    // temporary workaround due cypress not supporting overriding maxRedirects
+    if (_params.wait) {
+      urlParams.delete('wait');
+      const startTime = Date.now();
+      return this._mailiskSearchSmsAction(phoneNumber, _options, urlParams, startTime, _options.timeout);
+    } else {
+      return this.request.get(`api/sms/${phoneNumber}/messages?${urlParams.toString()}`, _options);
+    }
+  }
+
+  mailiskListSmsNumbers(options = {}) {
+    return this.request.get(`api/sms/numbers`, options);
+  }
 }
 
 module.exports = MailiskCommands;

package/src/request.js

@@ -81,6 +81,24 @@ class Request {
   del(path, opts) {
     return this.request('DELETE', path, undefined, opts);
   }
+
+  getBinary(url, opts) {
+    // For binary downloads, we need to use the full URL directly
+    const options = {
+      method: 'GET',
+      url: url,
+      encoding: null, // This tells Cypress to return binary data
+      ...opts,
+    };
+    options.failOnStatusCode = false;
+    return cy.request(options).then((response) => {
+      if (response.isOkStatusCode) {
+        return Buffer.from(response.body);
+      }
+      // Use the same error handling as regular requests
+      return this.getResponseHandler()(response);
+    });
+  }
 }
 
 module.exports = Request;