test-smtp-server 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Chris. Webster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# Test SMTP Server
+
+Test SMTP Server is a lightweight wrapper for
+[smtp-server](<https://nodemailer.com/extras/smtp-server/>).
+It is primarily intended for development and testing.  The test code can start the server, run email tests and then validate the email contents.  It can replace the use of external fake SMTP services which may have availablility issues.
+
+All received emails are stored in an array.  The emails may be viewed as raw data or a parsed object that is easily examined.
+
+## Getting Started
+
+### Prerequisites
+
+Tested on Node v16 with npm v7.
+
+### Installation
+
+```sh
+npm install test-smtp-server --save-dev
+```
+
+### Usage
+
+See [test code](https://github.com/webstech/test-smtp-server/test/index.ts) for an example.
+
+```js
+import { testSmtpServer } from "test-smtp-server";
+
+(async (): Promise<void> => {
+  const smtpserver = new testSmtpServer();
+  await smtpserver.startServer();   // start listening
+
+  // send some emails capturing ids ..
+  messageId.unshift( await sendMail(email, smtpOptions));
+
+  const mails = smtpserver.getEmails();
+
+  // validate/dump emails
+
+  if (mails.length) {
+    let entry = 0;
+    for (const mail of mails) {
+      console.log(`Checking mail entry <${entry}>`);
+      console.log(mail.envelope);
+      const parsed = await mail.getParsed();
+      if (parsed.messageId !== messageId[entry]) {
+        throw new Error(`Messageids do not match for email ${
+          entry} <${parsed.messageId}> <${messageId[entry]}>`);
+      }
+
+      console.log(parsed);
+      entry++;
+    }
+  } else {
+    throw new Error("No emails captured when expected");
+  }
+
+  await smtpserver.stopServer();    // terminate server
+```
+
+### Security
+
+The server is started as secure but that may not be possibly in the tesing
+environment.  If the server does not have a valid certificate, the connection
+will fail from the client side. Some clients (e.g. nodemailer/SMTP-Transport options)
+allow connections to non-secure servers.  Node allows connections through an
+environment variable that turns off certificate authorization chaecking.  See
+[node_tls_reject_unauthorizedvalue](https://nodejs.org/api/cli.html#node_tls_reject_unauthorizedvalue)
+for more information.  This may be insecure if other ports are used.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

package/build/lib/test-smtp-server.d.ts

@@ -0,0 +1,66 @@
+/// <reference types="node" />
+import { SMTPServerEnvelope } from "smtp-server";
+import { ParsedMail } from "mailparser";
+/**
+ * Class to describe an email.  The `envelope` contains the SMTP routing
+ * information.  This may not match the `to/cc/bcc` information in the
+ * email contaents.  The buffer contains the raw email content.  To easily
+ * access parts of the email, `getParsed` should be used.
+ */
+export declare class eMail {
+    envelope: SMTPServerEnvelope;
+    buffer: Buffer | null;
+    length: number;
+    constructor(envelope: SMTPServerEnvelope, buffer: Buffer);
+    /**
+     * Return a parsed email as formatted by `simpleParser`.
+     *
+     * @returns Promise<ParsedMail>  See
+     * https://nodemailer.com/extras/mailparser/ for the structure.
+     */
+    getParsed(): Promise<ParsedMail>;
+}
+/**
+ * testSmtpServer optional parameters
+ */
+export declare type testSmtpServerOptions = {
+    /** the port number to use (default: 1025) */
+    smtpPort?: number;
+    /** logging function like console.log() */
+    debug?: (message?: unknown, ...optionalParams: any[]) => void;
+};
+/**
+ * Create a testSmtpServer.  This provides a wrapper to SMTPServer that
+ * can be used for testing.  The emails are stored in an array that
+ * can be examined to validate the content.
+ */
+export declare class testSmtpServer {
+    private debug;
+    private emails;
+    private isDebugging;
+    private port;
+    private server;
+    constructor(options?: testSmtpServerOptions | undefined);
+    /**
+     * Clear the set of emails.
+     *
+     * @returns number of emails deleted
+     */
+    clearEmails(): number;
+    /**
+     * Retrieve the set of emails in order from latest to oldest.
+     *
+     * @returns array of eMail objects
+     */
+    getEmails(): eMail[];
+    /**
+     * Query for the port number used by the server.
+     *
+     * @returns the port number being used
+     */
+    getPort(): number;
+    /** Start the server */
+    startServer(): void;
+    /** Stop the server */
+    stopServer(): void;
+}

package/build/lib/test-smtp-server.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testSmtpServer = exports.eMail = void 0;
+const smtp_server_1 = require("smtp-server");
+const mailparser_1 = require("mailparser");
+const stream_1 = require("stream");
+/**
+ * Class to describe an email.  The `envelope` contains the SMTP routing
+ * information.  This may not match the `to/cc/bcc` information in the
+ * email contaents.  The buffer contains the raw email content.  To easily
+ * access parts of the email, `getParsed` should be used.
+ */
+class eMail {
+    constructor(envelope, buffer) {
+        this.buffer = null;
+        this.length = 0;
+        this.envelope = envelope;
+        this.buffer = buffer;
+    }
+    /**
+     * Return a parsed email as formatted by `simpleParser`.
+     *
+     * @returns Promise<ParsedMail>  See
+     * https://nodemailer.com/extras/mailparser/ for the structure.
+     */
+    async getParsed() {
+        if (this.buffer) {
+            const stream = stream_1.Readable.from(this.buffer);
+            const options = {
+                skipHtmlToText: true,
+                skipTextLinks: true,
+                skipTextToHtml: true
+            };
+            return (0, mailparser_1.simpleParser)(stream, options);
+        }
+        else {
+            throw new Error("Empty email buffer");
+        }
+    }
+}
+exports.eMail = eMail;
+/**
+ * Create a testSmtpServer.  This provides a wrapper to SMTPServer that
+ * can be used for testing.  The emails are stored in an array that
+ * can be examined to validate the content.
+ */
+class testSmtpServer {
+    constructor(options) {
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        this.debug = (_message, ..._optionalParams) => { };
+        this.emails = [];
+        this.isDebugging = false;
+        this.port = 1025;
+        if (options) {
+            if (options.smtpPort) {
+                this.port = options.smtpPort;
+            }
+            if (options.debug) {
+                this.debug = options.debug;
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const that = this; // preserve for use in other objects
+        this.server = new smtp_server_1.SMTPServer({
+            authOptional: true,
+            onConnect(session, callback) {
+                if (session.remoteAddress !== "127.0.0.1") {
+                    return callback(new Error("Only connections from localhost allowed"));
+                }
+                return callback(); // Accept the connection
+            },
+            onAuth(auth, _session, callback) {
+                that.debug(`SMTP login for user: ${auth.username}`);
+                callback(null, { user: auth.username });
+            },
+            onData(stream, session, callback) {
+                const buffers = [];
+                const writer = new stream_1.Writable({
+                    write(data, _encoding, writerCallback) {
+                        buffers.push(data);
+                        writerCallback();
+                    },
+                });
+                stream.pipe(writer);
+                stream.on("end", () => {
+                    const buffer = Buffer.concat(buffers);
+                    const email = new eMail(session.envelope, buffer);
+                    that.emails.unshift(email);
+                    if (that.isDebugging) {
+                        that.debug(JSON.stringify(email, (key, value) => {
+                            if ("buffer" === key) {
+                                return buffer.toString();
+                            }
+                            else {
+                                return value;
+                            }
+                        }, 2));
+                    }
+                    callback();
+                });
+            },
+            secure: true,
+        });
+    }
+    /**
+     * Clear the set of emails.
+     *
+     * @returns number of emails deleted
+     */
+    clearEmails() {
+        const count = this.emails.length;
+        this.emails.length = 0;
+        return count;
+    }
+    /**
+     * Retrieve the set of emails in order from latest to oldest.
+     *
+     * @returns array of eMail objects
+     */
+    getEmails() {
+        return this.emails;
+    }
+    /**
+     * Query for the port number used by the server.
+     *
+     * @returns the port number being used
+     */
+    getPort() {
+        return this.port;
+    }
+    /** Start the server */
+    startServer() {
+        this.server.listen(this.port);
+    }
+    /** Stop the server */
+    stopServer() {
+        this.server.close();
+    }
+}
+exports.testSmtpServer = testSmtpServer;
+//# sourceMappingURL=test-smtp-server.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "test-smtp-server",
+  "version": "0.9.0",
+  "description": "The test-smtp-server package allows internal testing of projects needing an SMTP server.",
+  "main": "./build/lib/test-smtp-server.js",
+  "xtype": "module",
+  "types": "./build/lib/test-smtp-server.d.ts",
+  "directories": {
+    "lib": "lib",
+    "test": "test"
+  },
+  "files": [
+    "/build/lib/test-smtp-server.js",
+    "/build/lib/test-smtp-server.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint --ignore-path .gitignore -c .eslintrc.js --ext .ts,.js \"{lib,test}/**/*.{ts,tsx,mjs,js}\"",
+    "test": "npm run test:ts && npm run test:js",
+    "test:ts": "node build/test/index.js",
+    "test:js": "node test/jstest.mjs"
+  },
+  "bugs": {
+    "url": "https://github.com/webstech/test-smtp-server/issues"
+  },
+  "homepage": "https://github.com/webstech/test-smtp-server#readme",
+  "keywords": [
+    "smtp",
+    "development",
+    "test",
+    "fake",
+    "dummy",
+    "mock",
+    "faux",
+    "email",
+    "e-mail",
+    "automated",
+    "integration",
+    "ci"
+  ],
+  "author": "Chris. Webster <chris@webstech.net> (https://www.webstech.com/)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webstech/test-smtp-server"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^6.4.4",
+    "@types/smtp-server": "^3.5.7",
+    "@typescript-eslint/eslint-plugin": "^5.1.0",
+    "@typescript-eslint/parser": "^5.1.0",
+    "commander": "^8.3.0",
+    "eslint": "^8.2.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-jsdoc": "^37.0.0",
+    "nodemailer": "^6.7.0",
+    "typescript": "^4.4.4"
+  },
+  "dependencies": {
+    "@types/mailparser": "^3.4.0",
+    "mailparser": "^3.4.0",
+    "smtp-server": "^3.9.0"
+  },
+  "engines": {
+    "node": ">= 16.0.0"
+  }
+}