@remit/smtp-service 0.0.18 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/smtp-service",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "type": "module",
   "main": "src/index.ts",
   "exports": {
@@ -11,6 +11,10 @@
     "./message-builder": {
       "types": "./src/message-builder.ts",
       "default": "./src/message-builder.ts"
+    },
+    "./test-fake-smtp": {
+      "types": "./src/test-fake-smtp.ts",
+      "default": "./src/test-fake-smtp.ts"
     }
   },
   "scripts": {

package/src/message-builder.ts

@@ -5,17 +5,17 @@ import nodemailer, { type SendMailOptions } from "nodemailer";
 export interface MailMessage {
 	from: string;
 	to: string[];
-	cc?: string[];
-	bcc?: string[];
-	replyTo?: string;
-	subject?: string;
-	text?: string;
-	html?: string;
+	cc?: string[] | undefined;
+	bcc?: string[] | undefined;
+	replyTo?: string | undefined;
+	subject?: string | undefined;
+	text?: string | undefined;
+	html?: string | undefined;
 	messageId: string;
-	inReplyTo?: string;
-	references?: string;
-	date?: Date;
-	attachments?: MailAttachment[];
+	inReplyTo?: string | undefined;
+	references?: string | undefined;
+	date?: Date | undefined;
+	attachments?: MailAttachment[] | undefined;
 }
 
 export interface MailAttachment {

package/src/smtp-client.test.ts

@@ -3,81 +3,24 @@ import net from "node:net";
 import { after, describe, it } from "node:test";
 import type { MailMessage } from "./message-builder.js";
 import {
+	directSmtpSocket,
 	type SmtpConfig,
 	SmtpConnectionError,
 	type SmtpCredentials,
 	sendMail,
+	verifySmtpConnection,
 } from "./smtp-client.js";
-
-interface FakeSmtpOptions {
-	authResponse?: string;
-	dataFinalResponse?: string;
-	dropAfterGreeting?: boolean;
-}
-
-interface FakeSmtp {
-	port: number;
-	authCommands: string[];
-	close: () => void;
+import {
+	type FakeSmtp,
+	type FakeSmtpOptions,
+	startFakeSmtp,
+} from "./test-fake-smtp.js";
+
+interface SocketRequest {
+	host: string | undefined;
+	port: string | number | undefined;
 }
 
-const startFakeSmtp = (opts: FakeSmtpOptions = {}): Promise<FakeSmtp> =>
-	new Promise((resolve) => {
-		const authCommands: string[] = [];
-		const server = net.createServer((socket) => {
-			if (opts.dropAfterGreeting) {
-				socket.destroy();
-				return;
-			}
-			socket.write("220 fake ESMTP\r\n");
-			let inData = false;
-			socket.on("data", (buffer) => {
-				const line = buffer.toString();
-				if (inData) {
-					if (line.includes("\r\n.\r\n")) {
-						inData = false;
-						socket.write(opts.dataFinalResponse ?? "250 2.0.0 Ok\r\n");
-					}
-					return;
-				}
-				const command = line.slice(0, 4).toUpperCase();
-				if (command.startsWith("EHLO") || command.startsWith("HELO")) {
-					socket.write("250-fake\r\n250 AUTH PLAIN LOGIN XOAUTH2\r\n");
-					return;
-				}
-				if (command.startsWith("AUTH")) {
-					authCommands.push(line.trim());
-					socket.write(opts.authResponse ?? "235 2.7.0 Accepted\r\n");
-					return;
-				}
-				if (command.startsWith("MAIL") || command.startsWith("RCPT")) {
-					socket.write("250 2.1.0 Ok\r\n");
-					return;
-				}
-				if (command.startsWith("DATA")) {
-					socket.write("354 End data\r\n");
-					inData = true;
-					return;
-				}
-				if (command.startsWith("QUIT")) {
-					socket.write("221 Bye\r\n");
-					socket.end();
-					return;
-				}
-				socket.write("250 Ok\r\n");
-			});
-		});
-		server.listen(0, "127.0.0.1", () => {
-			const address = server.address();
-			const port = typeof address === "object" && address ? address.port : 0;
-			resolve({
-				port,
-				authCommands,
-				close: () => server.close(),
-			});
-		});
-	});
-
 const configFor = (
 	port: number,
 	credentials: SmtpCredentials = { kind: "password", password: "secret" },
@@ -88,6 +31,7 @@ const configFor = (
 	user: "user@example.com",
 	credentials,
 	connectionTimeout: 2000,
+	getSocket: directSmtpSocket,
 });
 
 const testMessage: MailMessage = {
@@ -121,6 +65,28 @@ describe("sendMail", () => {
 		assert.ok(result.response);
 	});
 
+	it("talks to the server over the socket the host's factory opens", async () => {
+		const server = await spawn();
+		const requests: SocketRequest[] = [];
+		const result = await sendMail(
+			{
+				...configFor(server.port),
+				host: "smtp.invalid",
+				port: 2525,
+				getSocket: (request, callback) => {
+					requests.push({ host: request.host, port: request.port });
+					const connection = net.connect(server.port, "127.0.0.1", () =>
+						callback(null, { connection }),
+					);
+				},
+			},
+			testMessage,
+		);
+
+		assert.equal(result.success, true);
+		assert.deepEqual(requests, [{ host: "smtp.invalid", port: 2525 }]);
+	});
+
 	it("sends attachments through the transport", async () => {
 		const server = await spawn();
 		const result = await sendMail(configFor(server.port), {
@@ -211,3 +177,40 @@ describe("sendMail", () => {
 		assert.ok(result.error);
 	});
 });
+
+describe("verifySmtpConnection", () => {
+	const servers: FakeSmtp[] = [];
+	const spawn = async (opts?: FakeSmtpOptions): Promise<FakeSmtp> => {
+		const server = await startFakeSmtp(opts);
+		servers.push(server);
+		return server;
+	};
+
+	after(() => {
+		for (const server of servers) {
+			server.close();
+		}
+	});
+
+	it("succeeds when the server accepts the login", async () => {
+		const server = await spawn();
+
+		const result = await verifySmtpConnection(configFor(server.port));
+
+		assert.deepEqual(result, { success: true });
+	});
+
+	it("reports a rejected login as an authentication failure", async () => {
+		const server = await spawn({
+			authResponse: "535 5.7.8 Authentication credentials invalid\r\n",
+		});
+
+		const result = await verifySmtpConnection(configFor(server.port));
+
+		assert.deepEqual(result, {
+			success: false,
+			error:
+				"SMTP authentication failed: 535 5.7.8 Authentication credentials invalid",
+		});
+	});
+});

package/src/smtp-client.ts

@@ -1,4 +1,6 @@
+import type { TestResult } from "@remit/data-ports";
 import nodemailer from "nodemailer";
+import type { SMTPTransportGetSocket } from "nodemailer/lib/smtp-transport";
 import { type MailMessage, toNodemailerOptions } from "./message-builder.js";
 
 /**
@@ -31,7 +33,9 @@ export class SmtpConnectionError extends Error {
 	}
 }
 
-export interface SmtpConfig {
+export type SmtpGetSocket = SMTPTransportGetSocket;
+
+export interface SmtpServerConfig {
 	host: string;
 	port: number;
 	secure: boolean; // true for TLS (465), false for STARTTLS (587)
@@ -43,12 +47,20 @@ export interface SmtpConfig {
 	connectionTimeout?: number; // milliseconds, default 30000
 }
 
+export const directSmtpSocket: SmtpGetSocket = (_request, callback) => {
+	queueMicrotask(() => callback(null, false));
+};
+
+export interface SmtpConfig extends SmtpServerConfig {
+	getSocket: SmtpGetSocket;
+}
+
 export interface SendResult {
 	success: boolean;
-	messageId?: string;
-	response?: string;
-	error?: Error;
-	smtpCode?: number;
+	messageId?: string | undefined;
+	response?: string | undefined;
+	error?: Error | undefined;
+	smtpCode?: number | undefined;
 	isTransient: boolean;
 }
 
@@ -78,15 +90,26 @@ const buildSmtpAuth = (
 	throw new Error(`Unknown credential kind: ${JSON.stringify(_exhaustive)}`);
 };
 
-/**
- * Send email via SMTP using Nodemailer
- */
-export const sendMail = async (
-	config: SmtpConfig,
-	message: MailMessage,
-): Promise<SendResult> => {
+type SmtpFailure = Error & {
+	responseCode?: number;
+	code?: string;
+	command?: string;
+	response?: string;
+};
+
+const NETWORK_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ETIMEDOUT",
+	"ENOTFOUND",
+	"ECONNRESET",
+	"EHOSTUNREACH",
+]);
+
+const VERIFY_TIMEOUT_MS = 12_000;
+
+const transporterFor = (config: SmtpConfig, socketTimeout: number) => {
 	const timeout = config.connectionTimeout ?? 30_000;
-	const transporter = nodemailer.createTransport({
+	return nodemailer.createTransport({
 		host: config.host,
 		port: config.port,
 		secure: config.secure,
@@ -94,8 +117,50 @@ export const sendMail = async (
 		tls: config.tls,
 		connectionTimeout: timeout,
 		greetingTimeout: timeout,
-		socketTimeout: 300_000,
+		socketTimeout,
+		getSocket: config.getSocket,
 	});
+};
+
+const classifySmtpError = (error: SmtpFailure): SmtpConnectionError | null => {
+	const smtpCode = error.responseCode;
+
+	if (
+		error.code === "EAUTH" ||
+		(smtpCode !== undefined && smtpCode >= 500 && error.command === "AUTH")
+	) {
+		// The server's own words, when it gave any: a 535 reading
+		// "SmtpClientAuthentication is disabled for the Tenant" is not a
+		// failure signing in again clears, and the account card can only
+		// say so if the text survives the classification.
+		return new SmtpConnectionError(
+			"auth",
+			error.response
+				? `SMTP authentication failed: ${error.response.trim()}`
+				: "SMTP authentication failed",
+			error,
+		);
+	}
+
+	if (error.code !== undefined && NETWORK_ERROR_CODES.has(error.code)) {
+		return new SmtpConnectionError(
+			"network",
+			`SMTP connection failed: ${error.code}`,
+			error,
+		);
+	}
+
+	return null;
+};
+
+/**
+ * Send email via SMTP using Nodemailer
+ */
+export const sendMail = async (
+	config: SmtpConfig,
+	message: MailMessage,
+): Promise<SendResult> => {
+	const transporter = transporterFor(config, 300_000);
 
 	return transporter
 		.sendMail(toNodemailerOptions(message))
@@ -105,62 +170,45 @@ export const sendMail = async (
 			response: info.response,
 			isTransient: false,
 		}))
+		.catch((error: SmtpFailure) => {
+			const classified = classifySmtpError(error);
+			if (classified) {
+				throw classified;
+			}
+
+			// 4xx = transient (retry), 5xx = permanent (no retry)
+			const smtpCode = error.responseCode;
+			const isTransient =
+				smtpCode !== undefined && smtpCode >= 400 && smtpCode < 500;
+			return {
+				success: false,
+				error,
+				smtpCode,
+				isTransient,
+			};
+		})
+		.finally(() => transporter.close());
+};
+
+export const verifySmtpConnection = async (
+	config: SmtpConfig,
+): Promise<TestResult> => {
+	const transporter = transporterFor(
+		{
+			...config,
+			connectionTimeout: config.connectionTimeout ?? VERIFY_TIMEOUT_MS,
+		},
+		VERIFY_TIMEOUT_MS,
+	);
+
+	return transporter
+		.verify()
+		.then((): TestResult => ({ success: true }))
 		.catch(
-			(
-				error: Error & {
-					responseCode?: number;
-					code?: string;
-					command?: string;
-					response?: string;
-				},
-			) => {
-				const smtpCode = error.responseCode;
-
-				// Classify auth errors — EAUTH or 5xx on AUTH command
-				if (
-					error.code === "EAUTH" ||
-					(smtpCode !== undefined &&
-						smtpCode >= 500 &&
-						error.command === "AUTH")
-				) {
-					// The server's own words, when it gave any: a 535 reading
-					// "SmtpClientAuthentication is disabled for the Tenant" is not a
-					// failure signing in again clears, and the account card can only
-					// say so if the text survives the classification.
-					throw new SmtpConnectionError(
-						"auth",
-						error.response
-							? `SMTP authentication failed: ${error.response.trim()}`
-							: "SMTP authentication failed",
-						error,
-					);
-				}
-
-				// Classify network errors
-				if (
-					error.code === "ECONNREFUSED" ||
-					error.code === "ETIMEDOUT" ||
-					error.code === "ENOTFOUND" ||
-					error.code === "ECONNRESET" ||
-					error.code === "EHOSTUNREACH"
-				) {
-					throw new SmtpConnectionError(
-						"network",
-						`SMTP connection failed: ${error.code}`,
-						error,
-					);
-				}
-
-				// 4xx = transient (retry), 5xx = permanent (no retry)
-				const isTransient =
-					smtpCode !== undefined && smtpCode >= 400 && smtpCode < 500;
-				return {
-					success: false,
-					error,
-					smtpCode,
-					isTransient,
-				};
-			},
+			(error: SmtpFailure): TestResult => ({
+				success: false,
+				error: (classifySmtpError(error) ?? error).message,
+			}),
 		)
 		.finally(() => transporter.close());
 };

package/src/test-fake-smtp.ts

@@ -0,0 +1,74 @@
+import net from "node:net";
+
+export interface FakeSmtpOptions {
+	authResponse?: string;
+	dataFinalResponse?: string;
+	dropAfterGreeting?: boolean;
+}
+
+export interface FakeSmtp {
+	port: number;
+	authCommands: string[];
+	received: string[];
+	close: () => void;
+}
+
+export const startFakeSmtp = (opts: FakeSmtpOptions = {}): Promise<FakeSmtp> =>
+	new Promise((resolve) => {
+		const authCommands: string[] = [];
+		const received: string[] = [];
+		const server = net.createServer((socket) => {
+			if (opts.dropAfterGreeting) {
+				socket.destroy();
+				return;
+			}
+			socket.write("220 fake ESMTP\r\n");
+			let inData = false;
+			socket.on("data", (buffer) => {
+				const line = buffer.toString();
+				if (inData) {
+					received.push(line);
+					if (line.includes("\r\n.\r\n")) {
+						inData = false;
+						socket.write(opts.dataFinalResponse ?? "250 2.0.0 Ok\r\n");
+					}
+					return;
+				}
+				const command = line.slice(0, 4).toUpperCase();
+				if (command.startsWith("EHLO") || command.startsWith("HELO")) {
+					socket.write("250-fake\r\n250 AUTH PLAIN LOGIN XOAUTH2\r\n");
+					return;
+				}
+				if (command.startsWith("AUTH")) {
+					authCommands.push(line.trim());
+					socket.write(opts.authResponse ?? "235 2.7.0 Accepted\r\n");
+					return;
+				}
+				if (command.startsWith("MAIL") || command.startsWith("RCPT")) {
+					socket.write("250 2.1.0 Ok\r\n");
+					return;
+				}
+				if (command.startsWith("DATA")) {
+					socket.write("354 End data\r\n");
+					inData = true;
+					return;
+				}
+				if (command.startsWith("QUIT")) {
+					socket.write("221 Bye\r\n");
+					socket.end();
+					return;
+				}
+				socket.write("250 Ok\r\n");
+			});
+		});
+		server.listen(0, "127.0.0.1", () => {
+			const address = server.address();
+			const port = typeof address === "object" && address ? address.port : 0;
+			resolve({
+				port,
+				authCommands,
+				received,
+				close: () => server.close(),
+			});
+		});
+	});