pixl-mail 1.0.13 → 1.1.0

package/README.md

@@ -1,3 +1,19 @@
+<details><summary>Table of Contents</summary>
+
+<!-- toc -->
+- [Overview](#overview)
+- [Usage](#usage)
+	* [Placeholder Substitution](#placeholder-substitution)
+	* [Loading From Files](#loading-from-files)
+	* [Attachments](#attachments)
+	* [HTML Emails](#html-emails)
+	* [Options](#options)
+	* [Logging](#logging)
+	* [Debugging](#debugging)
+- [License](#license)
+
+</details>
+
 # Overview
 
 This module provides a very simple e-mail sender, which leans heavily on the awesome [nodemailer](https://nodemailer.com/) package.  It layers on the ability to pass in a complete e-mail message with headers and body in one string (or file), and optionally perform placeholder substitution using [sub()](https://www.npmjs.com/package/pixl-tools#sub) from the [pixl-tools](https://www.npmjs.com/package/pixl-tools) package.  Auto-detects HTML or plain text e-mail body, and supports custom headers and attachments as well.
@@ -6,36 +22,36 @@ This module provides a very simple e-mail sender, which leans heavily on the awe
 
 Use [npm](https://www.npmjs.com/) to install the module:
 
-```
+```sh
 npm install pixl-mail
 ```
 
 Then use `require()` to load it in your code:
 
-```javascript
-var PixlMail = require('pixl-mail');
+```js
+const PixlMail = require('pixl-mail');
 ```
 
 Instantiate a mailer object and pass in the SMTP hostname (defaults to `127.0.0.1`) and the port number (defaults to `25`):
 
-```javascript
-var mail = new PixlMail( 'smtp.myserver.com', 25 );
-var mail = new PixlMail( '127.0.0.1' );
-var mail = new PixlMail();
+```js
+let mail = new PixlMail( 'smtp.myserver.com', 25 );
+let mail = new PixlMail( '127.0.0.1' );
+let mail = new PixlMail();
 ```
 
 Send mail using the `send()` method.  Pass in the complete e-mail message as a multi-line string including `To`, `From` and `Subject` headers, and a callback:
 
-```javascript
-var message = 
+```js
+let message = 
 	"To: president@whitehouse.gov\n" + 
 	"From: citizen@email.com\n" + 
-	"Subject: NASA Budget\n" +
+	"Subject: State Budget\n" +
 	"\n" +  
-	"Dear Mr. President,\nPlease give NASA back their money.\n";
+	"Dear Mr. President,\nOur state needs more money.\n";
 
 mail.send( message, function(err) {
-	if (err) console.log( "Mail Error: " + err );
+	if (err) console.error( "Mail Error: " + err );
 } );
 ```
 
@@ -43,13 +59,13 @@ For multiple recipients, simply separate them by commas on the `To` line.  You c
 
 ## Placeholder Substitution
 
-The library supports a simple e-mail templating system, where you can insert `[bracket_placeholders]` in your e-mail message, and have the library fill them with appropriate content from a separate object.  This feature uses the [sub()](https://www.npmjs.com/package/pixl-tools#sub) function from the [pixl-tools](https://www.npmjs.com/package/pixl-tools) package.
+The library supports a simple e-mail templating system, where you can insert `[bracket_placeholders]` in your e-mail message, and have the library fill them with appropriate content from a separate object.  This feature uses the [sub()](https://github.com/jhuckaby/pixl-tools#sub) function from the [pixl-tools](https://github.com/jhuckaby/pixl-tools) package.
 
 As an example, imagine a welcome e-mail for a new user who has signed up for your app.  You have the welcome e-mail "template" stored separately, and want to fill in the user's e-mail address, full name and username at sending time.  Here is how to do this:
 
-```javascript
+```js
 // email template
-var message = 
+let message = 
 	"To: [email]\n" + 
 	"From: support@myapp.com\n" + 
 	"Subject: Welcome to My App, [full_name]!\n" +
@@ -57,7 +73,7 @@ var message =
 	"Dear [full_name],\nWelcome to My App!  Your username is '[username]'.\n";
 
 // placeholder args
-var user = {
+let user = {
 	username: "jhuckaby",
 	full_name: "Joseph Huckaby",
 	email: "jhuckaby@email.com"
@@ -79,14 +95,14 @@ Dear Joseph Huckaby,
 Welcome to My App!  Your username is 'jhuckaby'.
 ```
 
-You can actually use a complex hash / array tree of arguments, and then specify `[filesystem/style/paths]` or `[dot.style.paths]` in your placeholders.  See the [sub()](https://www.npmjs.com/package/pixl-tools#sub) docs for details.
+You can actually use a complex hash / array tree of arguments, and then specify `[filesystem/style/paths]` or `[dot.style.paths]` in your placeholders.  See the [sub()](https://github.com/jhuckaby/pixl-tools#sub) docs for details.
 
 ## Loading From Files
 
 You can specify a file path instead of the raw message, like this:
 
-```javascript
-var user = {
+```js
+let user = {
 	username: "jhuckaby",
 	full_name: "Joseph Huckaby",
 	email: "jhuckaby@email.com"
@@ -101,8 +117,8 @@ mail.send( "conf/emails/new_user_welcome.txt", user, function(err) {
 
 To attach files, include an `attachments` array in your `args` object, and specify a `filename` and `path` for each one.  This is passed directly to [nodemailer](https://nodemailer.com/), so you can use all of their attachment features.  Example:
 
-```javascript
-var args = {
+```js
+let args = {
 	attachments: [
 		{ filename: "contract.pdf", path: "files/contracts/4573D.PDF" },
 		{ filename: "policy.pdf", path: "files/misc/POLICY-2015.PDF" }
@@ -110,7 +126,7 @@ var args = {
 };
 
 mail.send( message, args, function(err) {
-	if (err) console.log( "Mail Error: " + err );
+	if (err) console.error( "Mail Error: " + err );
 } );
 ```
 
@@ -120,16 +136,16 @@ For details, see the [Attachments](https://nodemailer.com/message/attachments/)
 
 If you want to send HTML formatted e-mails, the library will automatically detect this.  Just provide the headers in plain text, two end-of-lines, then start your HTML markup.  Example:
 
-```javascript
-var message = 
+```js
+let message = 
 	"To: president@whitehouse.gov\n" + 
 	"From: citizen@email.com\n" + 
-	"Subject: NASA Budget\n" + 
+	"Subject: State Budget\n" + 
 	"\n" + 
-	"<h1>Dear Mr. President,</h1>\n<p><b>Please</b> give NASA back their <i>money</i>.</p>\n";
+	"<h1>Dear Mr. President,</h1>\n<p><b>Please</b> give our state more <i>money</i>.</p>\n";
 
 mail.send( message, function(err) {
-	if (err) console.log( "Mail Error: " + err );
+	if (err) console.error( "Mail Error: " + err );
 } );
 ```
 
@@ -141,7 +157,7 @@ You can set a number of options using the `setOption()` or `setOptions()` method
 
 The `setOption()` method takes one single key/value to set or replace, while `setOptions()` accepts an object containing multiple keys/values.
 
-```javascript
+```js
 mail.setOption( 'secure', true ); // use ssl
 mail.setOption( 'auth', { user: 'fsmith', pass: '12345' } );
 
@@ -162,11 +178,57 @@ mail.setOptions({
 });
 ```
 
+## Logging
+
+You can optionally attach a [pixl-logger](https://github.com/jhuckaby/pixl-logger) compatible log agent, which will log all the [nodemailer](https://nodemailer.com/) debug messages at level 9, with the component column set to `Mailer`.  To use this feature, call the `attachLogAgent()` method on your class instance, and pass in your pixl-logger instance:
+
+```js
+mail.attachLogAgent( logger );
+```
+
+## Debugging
+
+The `send()` method actually returns three arguments: the error (if any), the final composed mail body with headers (after all macro expansion), and a full debug log capture from [nodemailer](https://nodemailer.com/).  Here is how to use them:
+
+```js
+mail.send( message, function(err, message, log) {
+	if (err) console.error( "Mail Error: " + err );
+	
+	console.log( "Full composed message: " + message );
+	
+	log.forEach( function(row) {
+		console.log( ...row );
+	} );
+} );
+```
+
+Each log row will contain two elements: the log message itself, and an object containing additional metadata.  These come directly from [nodemailer](https://nodemailer.com/).  Here is an example excerpt:
+
+```
+Creating transport: nodemailer (6.4.11; +https://nodemailer.com/; SMTP/6.4.11[client:6.4.11])
+{"component":"mail","tnx":"create"}
+
+Sending mail using SMTP/6.4.11[client:6.4.11]
+{"component":"mail","tnx":"transport","name":"SMTP","version":"6.4.11[client:6.4.11]","action":"send"}
+
+Resolved localhost as ::1 [cache miss]
+{"component":"smtp-connection","sid":"N5uAYhHPKsY","tnx":"dns","source":"localhost","resolved":"::1","cached":false}
+
+Connection established to ::1:25
+{"component":"smtp-connection","sid":"N5uAYhHPKsY","tnx":"network","localAddress":"::1","localPort":53068,"remoteAddress":"::1","remotePort":25}
+
+220 joemax.local ESMTP Postfix
+{"component":"smtp-connection","sid":"N5uAYhHPKsY","tnx":"server"}
+
+EHLO joemax.local
+{"component":"smtp-connection","sid":"N5uAYhHPKsY","tnx":"client"}
+```
+
 # License
 
 **The MIT License (MIT)**
 
-*Copyright (c) 2015 - 2019 Joseph Huckaby.*
+*Copyright (c) 2015 - 2024 Joseph Huckaby.*
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/mail.js

@@ -1,37 +1,40 @@
 // Simple SMTP Email Sender
-// Copyright (c) 2015 - 2019 Joseph Huckaby
+// Copyright (c) 2015 - 2024 Joseph Huckaby
 // Released under the MIT License
 
-var fs = require('fs');
-var nodemailer = require('nodemailer');
-var Tools = require('pixl-tools');
-var Class = require('pixl-class');
+const fs = require('fs');
+const util = require('util');
+const nodemailer = require('nodemailer');
+const Tools = require('pixl-tools');
 
-module.exports = Class.create({
+module.exports = class Mailer {
 	
-	options: null,
-	
-	__construct: function(host, port) {
+	constructor(host, port) {
 		// class constructor
 		this.options = {
 			host: host || '127.0.0.1',
 			port: port || 25
 		};
-	},
+	}
 	
-	setOption: function(key, value) {
+	setOption(key, value) {
 		// set single option
 		this.options[key] = value;
-	},
+	}
 	
-	setOptions: function(opts) {
+	setOptions(opts) {
 		// set multiple options
 		for (var key in opts) {
 			this.options[key] = opts[key];
 		}
-	},
+	}
+	
+	attachLogAgent(agent) {
+		// attach pixl-logger compatible log agent
+		this.logger = agent;
+	}
 	
-	send: function(data, args, callback) {
+	send(data, args, callback) {
 		// send e-mail
 		var self = this;
 		
@@ -95,6 +98,20 @@ module.exports = Class.create({
 			delete this.options.port;
 		}
 		
+		// capture debug trace from nodemailer, and log if configured
+		// also send it back with response, whatever the result
+		this.options.debug = true;
+		this.options.logger = {};
+		var log = [];
+		
+		['trace', 'debug', 'info', 'warn', 'error', 'fatal'].forEach( function(level) {
+			self.options.logger[level] = function(entry, message, ...args) {
+				message = util.format(message, ...args);
+				self.logDebug(9, message, entry);
+				log.push( message, entry );
+			};
+		} );
+		
 		// setup transport
 		var transport = nodemailer.createTransport(this.options);
 		
@@ -120,7 +137,16 @@ module.exports = Class.create({
 		
 		// send mail
 		transport.sendMail( opts, function(err) {
-			callback( err, data );
+			callback( err, data, log );
 		} );
 	}
-});
+	
+	logDebug(level, msg, data) {
+		// log if we have an attached agent
+		if (this.logger) {
+			this.logger.set( 'component', 'Mailer' );
+			this.logger.debug( level, msg, data );
+		}
+	}
+	
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pixl-mail",
-	"version": "1.0.13",
+	"version": "1.1.0",
 	"description": "A very simple class for sending e-mail via SMTP.",
 	"author": "Joseph Huckaby <jhuckaby@gmail.com>",
 	"homepage": "https://github.com/jhuckaby/pixl-mail",
@@ -19,9 +19,8 @@
 		"smtp"
 	],
 	"dependencies": {
-		"nodemailer": "6.6.1",
-		"pixl-tools": "^1.0.19",
-		"pixl-class": "^1.0.3"
+		"nodemailer": "6.9.9",
+		"pixl-tools": "^1.0.19"
 	},
 	"devDependencies": {