feat: added simpleParser and returnHTML options, added sandbox and no-referrer to iframe, bump deps

Author: titanism

README.md

@@ -48,11 +48,11 @@ npm install preview-email
 
 As of v3.0.6 we have built-in support for previewing emails in the iOS Simulator (in addition to rendering them in your default web browser).
 
-This is only applicable if you are using macOS and if not running in a CI environment.  If you wish to disable this default behavior, then set `openSimulator` to `false` in the [options](#options).
+This is only applicable if you are using macOS and if not running in a CI environment. If you wish to disable this default behavior, then set `openSimulator` to `false` in the [options](#options).
 
-Otherwise you will need to install XCode from the [App Store][app-store] or [Apple Developer Website][apple-developer-website].  We have built-in friendly macOS notifications that will alert you if there are any issues while attempting to load the iOS Simulator.
+Otherwise you will need to install XCode from the [App Store][app-store] or [Apple Developer Website][apple-developer-website]. We have built-in friendly macOS notifications that will alert you if there are any issues while attempting to load the iOS Simulator.
 
-**After installing XCode**, you will need to open it and agree to the terms and conditions.  Then you will need to [assign Command Line Tools](https://stackoverflow.com/a/36726612).
+**After installing XCode**, you will need to open it and agree to the terms and conditions. Then you will need to [assign Command Line Tools](https://stackoverflow.com/a/36726612).
 
 **Once the Simulator is opened** – if you need to inspect the rendered email, then you can [use the Web Inspector in Safari Developer Tools](https://webkit.org/web-inspector/enabling-web-inspector/).
 
@@ -78,7 +78,7 @@ const message = {
   subject: 'Hello world',
   html: '<p>Hello world</p>',
   text: 'Hello world',
-  attachments: [ { filename: 'hello-world.txt', content: 'Hello world' } ]
+  attachments: [{ filename: 'hello-world.txt', content: 'Hello world' }]
 };
 
 // note that `attachments` will not be parsed unless you use
@@ -100,7 +100,9 @@ const path = require('path');
 
 // ...
 
-previewEmail(message, { template: path.join(__dirname, 'my-custom-preview-template.pug') })
+previewEmail(message, {
+  template: path.join(__dirname, 'my-custom-preview-template.pug')
+})
   .then(console.log)
   .catch(console.error);
 ```
@@ -125,6 +127,8 @@ NODE_DEBUG=preview-email node app.js
   * `template` (String) - a file path to a `pug` template file (defaults to preview-email's [template.pug](template.pug) by default) - **this is where you can pass a custom template for rendering email previews, e.g. your own stylesheet**
   * `urlTransform` (Function (path) => url) - a function to build preview url from file path (defaults to `(path) => 'file://[file path]'`) - *this is where you can customize the opened path to handle WSL to Windows transformation or build a http url if `dir` is served.*
   * `openSimulator` (Boolean) - whether or not to open the iOS Simulator with the preview url file path (defaults to `true` via `process.env.NODE_ENV !== 'test'` and will only run if macOS detected and not in a CI environment)
+  * `simpleParser` (Object) - an options Object to pass to `mailparser`'s `simpleParser` method (see [mailparser docs](https://nodemailer.com/extras/mailparser/#options) for available options – note that `Iconv` option is always overridden for safeguard)
+  * `returnHTML` (Boolean) - whether or not to return HTML only – and subsequently not write nor open the file preview file (defaults to `false`)
 
 
 ## Contributors

index.js

@@ -5,7 +5,6 @@ const os = require('os');
 const path = require('path');
 const process = require('process');
 const util = require('util');
-
 const displayNotification = require('display-notification');
 const getPort = require('get-port');
 const nodemailer = require('nodemailer');
@@ -14,6 +13,7 @@ const pEvent = require('p-event');
 const pWaitFor = require('p-wait-for');
 const pug = require('pug');
 const uuid = require('uuid');
+const { Iconv } = require('iconv');
 const { isCI } = require('ci-info');
 const { simpleParser } = require('mailparser');
 
@@ -35,6 +35,9 @@ const previewEmail = async (message, options) => {
     template: templateFilePath,
     urlTransform: (path) => `file://${path}`,
     openSimulator: process.env.NODE_ENV !== 'test',
+    returnHTML: false,
+    // <https://nodemailer.com/extras/mailparser/#options>
+    simpleParser: {},
     ...options
   };
   debug('message', message, 'options', options);
@@ -44,7 +47,10 @@ const previewEmail = async (message, options) => {
 
   const response = await transport.sendMail(message);
 
-  const parsed = await simpleParser(response.message);
+  const parsed = await simpleParser(response.message, {
+    ...options.simpleParser,
+    Iconv
+  });
 
   const html = await renderFilePromise(
     options.template,
@@ -55,10 +61,12 @@ const previewEmail = async (message, options) => {
   );
 
   const filePath = `${options.dir}/${options.id}.html`;
-  await writeFile(filePath, html);
-
   const url = options.urlTransform(filePath);
-  if (options.open) await open(url, options.open);
+
+  if (!options.returnHTML) {
+    await writeFile(filePath, html);
+    if (options.open) await open(url, options.open);
+  }
 
   //
   // if on macOS then send a toast notification about XCode and Simulator for iOS
@@ -216,7 +224,7 @@ const previewEmail = async (message, options) => {
     }
   }
 
-  return url;
+  return options.returnHTML ? html : url;
 };
 
 module.exports = previewEmail;

package.json

@@ -11,31 +11,32 @@
     "Nick Baugh <niftylettuce@gmail.com> (http://niftylettuce.com/)"
   ],
   "dependencies": {
-    "ci-info": "^3.7.1",
+    "ci-info": "^3.8.0",
     "display-notification": "2.0.0",
     "fixpack": "^4.0.0",
     "get-port": "5.1.1",
-    "mailparser": "^3.6.3",
-    "nodemailer": "^6.9.1",
+    "iconv": "^3.0.1",
+    "mailparser": "^3.6.4",
+    "nodemailer": "^6.9.2",
     "open": "7",
     "p-event": "4.2.0",
     "p-wait-for": "3.2.0",
     "pug": "^3.0.2",
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.4.2",
-    "@commitlint/config-conventional": "^17.4.2",
+    "@commitlint/cli": "^17.6.3",
+    "@commitlint/config-conventional": "^17.6.3",
     "ava": "^5.2.0",
     "cross-env": "^7.0.3",
-    "eslint": "^8.33.0",
+    "eslint": "^8.40.0",
     "eslint-config-xo-lass": "^2.0.1",
     "husky": "^8.0.3",
-    "lint-staged": "^13.1.1",
+    "lint-staged": "^13.2.2",
     "nyc": "^15.1.0",
     "remark-cli": "^11.0.0",
     "remark-preset-github": "^4.0.4",
-    "xo": "^0.53.1"
+    "xo": "^0.54.2"
   },
   "engines": {
     "node": ">=14"

template.pug

@@ -40,7 +40,7 @@ html
                       code= 'Unnamed file'
       if html
         tr: td(colspan=2): strong: code HTML Version:
-        tr: td(colspan=2): iframe(seamless='seamless', srcdoc=`<base target='_top'>${html}`)#html
+        tr: td(colspan=2): iframe(sandbox, referrerpolicy='no-referrer', seamless='seamless', srcdoc=`<base target='_top'>${html}`)#html
       if text
         tr: td(colspan=2): strong: code Text Version:
-        tr: td(colspan=2): iframe(seamless='seamless', srcdoc=`<pre>${text}</pre>`)#text
+        tr: td(colspan=2): iframe(sandbox, referrerpolicy='no-referrer', seamless='seamless', srcdoc=`<pre>${text}</pre>`)#text

test/test.js

@@ -1,9 +1,7 @@
 const fs = require('fs');
 const path = require('path');
-
 const test = require('ava');
 const nodemailer = require('nodemailer');
-
 const previewEmail = require('..');
 
 const transport = nodemailer.createTransport({ jsonTransport: true });
@@ -42,6 +40,38 @@ test('opens a preview email', async (t) => {
   t.true(typeof url === 'string');
 });
 
+test('returns HTML only', async (t) => {
+  const message = {
+    from: 'niftylettuce <niftylettuce+from@gmail.com>',
+    to: 'niftylettuce+to@gmail.com, niftylettuce <niftylettuce+test@gmail.com>',
+    subject: 'Hello world',
+    html: `<p>Hello world</p>`,
+    text: 'Hello world',
+    replyTo: 'niftylettuce <niftylettuce+replyto@gmail.com>',
+    inReplyTo: 'in reply to',
+    attachments: [
+      { filename: 'hello-world.txt', content: 'Hello world' },
+      { path: path.join(__dirname, '..', '.editorconfig') },
+      { path: path.join(__dirname, '..', 'media', 'browser.png') },
+      {
+        filename: 'test.txt',
+        content: fs.createReadStream(path.join(__dirname, 'test.txt'))
+      }
+    ],
+    headers: {
+      'X-Some-Custom-Header': 'Some Custom Value'
+    },
+    list: {
+      unsubscribe: 'https://niftylettuce.com/unsubscribe'
+    }
+  };
+  const response = await transport.sendMail(message);
+  const html = await previewEmail(JSON.parse(response.message), {
+    returnHTML: true
+  });
+  t.true(html.startsWith('<!DOCTYPE html>'));
+});
+
 test('does not open', async (t) => {
   const url = await previewEmail({}, { open: false });
   t.true(typeof url === 'string');