Add email previews support

.github/workflows/build.yml

@@ -5,9 +5,9 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   workflow_dispatch:
 
 concurrency: 

src/mailosaurCommands.d.ts

@@ -629,6 +629,102 @@ export interface OtpResult {
     expires?: Date;
 }
 
+/**
+ * Describes an email preview.
+ */
+export interface Preview {
+    /**
+     * Unique identifier for the email preview.
+     */
+    id?: string;
+    /**
+     * The email client the preview was generated with.
+     */
+    emailClient?: string;
+    /**
+     * True if images were disabled in the preview.
+     */
+    disableImages?: boolean;
+}
+
+/**
+ * A list of requested email previews.
+ */
+export interface PreviewListResult {
+    /**
+     * The summaries for each requested preview.
+     */
+    items?: Preview[];
+}
+
+/**
+ * Describes an email client with which email previews can be generated.
+ */
+export interface PreviewEmailClient {
+    /**
+     * The unique identifier of the email client.
+     */
+    id?: string;
+    /**
+     * The display name of the email client.
+     */
+    name?: string;
+    /**
+     * Whether the platform is desktop, mobile, or web-based.
+     */
+    platformGroup?: string;
+    /**
+     * The type of platform on which the email client is running.
+     */
+    platformType?: string;
+    /**
+     * The platform version number.
+     */
+    platformVersion?: string;
+    /**
+     * If true, images can be disabled when generating previews.
+     */
+    canDisableImages?: boolean;
+    /**
+     * The current status of the email client.
+     */
+    status?: string;
+}
+
+/**
+ * A list of available email clients with which to generate email previews.
+ */
+export interface PreviewEmailClientListResult {
+    /**
+     * A list of available email clients.
+     */
+    items?: PreviewEmailClient[];
+}
+
+/**
+ * Describes an email preview request.
+ */
+export interface PreviewRequest {
+    /**
+     * The email client you wish to generate a preview for.
+     */
+    emailClient?: string;
+    /**
+     * If true, images will be disabled (only if supported by the client).
+     */
+    disableImages?: boolean;
+}
+
+/**
+ * Preview request options.
+ */
+export interface PreviewRequestOptions {
+    /**
+     * The list of email preview requests.
+     */
+    previews: PreviewRequest[];
+}
+
 declare global {
     namespace Cypress {
         interface Chainable {
@@ -864,6 +960,20 @@ declare global {
                 sentTo: string
             ): Cypress.Chainable<MessageListResult>;
 
+            /**
+             * Generates screenshots of an email rendered in the specified email clients.
+             */
+            mailosaurGenerateEmailPreviews(
+                /**
+                 * The identifier of the email to preview.
+                 */
+                messageId: string,
+                /**
+                 * The options with which to generate previews.
+                 */
+                options: PreviewRequestOptions
+            ): Cypress.Chainable<PreviewListResult>;
+
             /**
              * Downloads a single attachment.
              */
@@ -884,6 +994,17 @@ declare global {
                 messageId: string
             ): Cypress.Chainable<string>;
 
+            /**
+             * Downloads a screenshot of your email rendered in a real email client. Simply supply
+             * the unique identifier for the required preview.
+             */
+            mailosaurDownloadPreview(
+                /**
+                 * The identifier of the email preview to be downloaded.
+                 */
+                previewId: string
+            ): Cypress.Chainable<unknown>;
+
             /**
              * Permanently deletes a message. Also deletes any attachments related to the message. This operation cannot be undone.
              */
@@ -964,6 +1085,12 @@ declare global {
                  */
                 deviceId: string
             ): Cypress.Chainable<null>;
+
+            /**
+             * List all email clients that can be used to generate email previews.
+             */
+            mailosaurListPreviewEmailClients(
+            ): Cypress.Chainable<PreviewEmailClientListResult>;
         }
     }
 }

src/mailosaurCommands.js

@@ -35,6 +35,9 @@ class MailosaurCommands {
       'mailosaurCreateDevice',
       'mailosaurGetDeviceOtp',
       'mailosaurDeleteDevice',
+      'mailosaurListPreviewEmailClients',
+      'mailosaurGenerateEmailPreviews',
+      'mailosaurDownloadPreview',
     ];
   }
 
@@ -252,6 +255,18 @@ class MailosaurCommands {
   mailosaurDeleteDevice(deviceId) {
     return this.request.del(`api/devices/${deviceId}`);
   }
+
+  mailosaurListPreviewEmailClients() {
+    return this.request.get('api/previews/clients');
+  }
+
+  mailosaurGenerateEmailPreviews(messageId, options = {}) {
+    return this.request.post(`api/messages/${messageId}/previews`, options);
+  }
+
+  mailosaurDownloadPreview(previewId) {
+    return this.request.get(`api/files/previews/${previewId}`, { encoding: 'binary' });
+  }
 }
 
 module.exports = MailosaurCommands;

test/react-app/cypress/e2e/previews.cy.js

@@ -0,0 +1,32 @@
+/* eslint-disable no-unused-expressions */
+describe('Mailosaur previews commands', () => {
+  const server = Cypress.env('MAILOSAUR_PREVIEWS_SERVER');
+
+  describe('.mailosaurListPreviewEmailClients', () => {
+    it('should list email clients', () => {
+      cy.mailosaurListPreviewEmailClients().then((result) => {
+        expect(result.items).to.have.lengthOf.above(1);
+      });
+    });
+  });
+
+  (server ? describe : describe.skip)('.mailosaurGenerateEmailPreviews', () => {
+    it('should generate email previews', () => {
+      cy.mailosaurCreateMessage(server, {})
+        .then(email => (
+          cy.mailosaurGenerateEmailPreviews(email.id, {
+            previews: [{
+              emailClient: 'OL2021'
+            }]
+          })
+        ))
+        .then(result => {
+          expect(result.items).to.have.lengthOf.above(0);
+          return cy.mailosaurDownloadPreview(result.items[0].id);
+        })
+        .then(file => {
+          expect(file).to.be.ok();
+        });
+    });
+  });
+});

test/react-app/package.json

@@ -23,7 +23,7 @@
     "cypress:verify": "cypress verify",
     "cypress:open": "cypress open",
     "cypress:run": "cypress run",
-    "test:ci": "$(npm bin)/start-server-and-test build:serve http-get://localhost:3000 cypress:run"
+    "test:ci": "npx start-server-and-test build:serve http-get://localhost:3000 cypress:run"
   },
   "browserslist": {
     "production": [