@remit/smtp-service 0.0.8 → 0.0.10

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@remit/smtp-service",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "type": "module",
   "main": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./message-builder": {
+      "types": "./src/message-builder.ts",
+      "default": "./src/message-builder.ts"
+    }
+  },
   "scripts": {
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=75 --test 'src/**/*.test.ts'",
+    "test:run": "node --env-file=../../localhost-test-unit.env --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=95 --test 'src/**/*.test.ts'",
     "test": "npm run test:typecheck && npm run test:run",
     "test:integ": "RUN_INTEG_TESTS=true node --env-file=../../localhost-dev-aws.env --import tsx --test --test-force-exit 'src/**/*.integ.test.ts'"
   },

package/src/message-builder.test.ts

@@ -1,7 +1,11 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import type { OutboxMessageItem } from "@remit/data-ports";
-import { buildMailMessage, type MailAttachment } from "./message-builder.js";
+import {
+	buildMailMessage,
+	type MailAttachment,
+	renderRawMessage,
+} from "./message-builder.js";
 
 const baseOutbox = (
 	overrides: Partial<OutboxMessageItem> = {},
@@ -22,6 +26,16 @@ const baseOutbox = (
 });
 
 describe("buildMailMessage", () => {
+	it("stamps the Sent copy with the moment the send was recorded", () => {
+		const message = buildMailMessage(baseOutbox({ sentAt: 1_700_000_000_000 }));
+		assert.deepEqual(message.date, new Date(1_700_000_000_000));
+	});
+
+	it("leaves the date to the transport while the message is still going out", () => {
+		const message = buildMailMessage(baseOutbox({ sentAt: undefined }));
+		assert.equal(message.date, undefined);
+	});
+
 	it("formats From as a quoted display name when fromName is set", () => {
 		const message = buildMailMessage(
 			baseOutbox({
@@ -32,6 +46,16 @@ describe("buildMailMessage", () => {
 		assert.equal(message.from, '"Alice Sender" <alice@example.com>');
 	});
 
+	it("escapes a display name that carries a quote", () => {
+		const message = buildMailMessage(
+			baseOutbox({
+				fromName: 'Al "Big" Sender',
+				fromAddress: "alice@example.com",
+			}),
+		);
+		assert.equal(message.from, '"Al \\"Big\\" Sender" <alice@example.com>');
+	});
+
 	it("uses the bare address as From when fromName is absent", () => {
 		const message = buildMailMessage(
 			baseOutbox({ fromName: undefined, fromAddress: "alice@example.com" }),
@@ -115,3 +139,172 @@ describe("buildMailMessage", () => {
 		assert.equal(message.attachments, undefined);
 	});
 });
+
+/**
+ * `send-mime.spec.ts` compares both copies off a real server, which covers every
+ * shape the API can currently produce. What it cannot reach is what the compose
+ * path never sets — a display name, an attachment — so those are asserted here.
+ */
+describe("renderRawMessage", () => {
+	const headerOf = (raw: string, name: string): string | undefined => {
+		const head = raw.split(/\r?\n\r?\n/, 1)[0].replace(/\r?\n[ \t]+/g, " ");
+		return head
+			.split(/\r?\n/)
+			.find((line) => line.toLowerCase().startsWith(`${name.toLowerCase()}:`))
+			?.slice(name.length + 1)
+			.trim();
+	};
+
+	it("carries the display name into the rendered From", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({
+						fromName: "Alice Sender",
+						fromAddress: "alice@example.com",
+					}),
+				),
+			),
+		);
+		assert.equal(headerOf(raw, "From"), "Alice Sender <alice@example.com>");
+	});
+
+	it("keeps a display name with a comma from splitting into two addresses", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({ fromName: "Doe, John", fromAddress: "j@example.com" }),
+				),
+			),
+		);
+		assert.equal(headerOf(raw, "From"), '"Doe, John" <j@example.com>');
+	});
+
+	it("keeps the quotes inside a display name", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({
+						fromName: 'Al "Big" Sender',
+						fromAddress: "a@example.com",
+					}),
+				),
+			),
+		);
+		assert.equal(
+			headerOf(raw, "From"),
+			'"Al \\"Big\\" Sender" <a@example.com>',
+		);
+	});
+
+	it("renders text and HTML bodies as a multipart/alternative", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({ textBody: "plain text", htmlBody: "<p>html</p>" }),
+				),
+			),
+		);
+		assert.match(
+			headerOf(raw, "Content-Type") ?? "",
+			/^multipart\/alternative/,
+		);
+		assert.match(raw, /Content-Type: text\/plain/);
+		assert.match(raw, /Content-Type: text\/html/);
+	});
+
+	it("renders a text-only body without an HTML alternative", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({ textBody: "plain text", htmlBody: undefined }),
+				),
+			),
+		);
+		assert.match(headerOf(raw, "Content-Type") ?? "", /^text\/plain/);
+		assert.ok(!raw.includes("text/html"));
+	});
+
+	it("renders each attachment as its own part", async () => {
+		const attachments: MailAttachment[] = [
+			{
+				filename: "invoice.pdf",
+				content: Buffer.from("pdf-bytes"),
+				contentType: "application/pdf",
+			},
+			{
+				filename: "logo.png",
+				content: Buffer.from("png-bytes"),
+				contentType: "image/png",
+				cid: "logo-cid",
+				contentDisposition: "inline",
+			},
+		];
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(baseOutbox({ textBody: "body" }), attachments),
+			),
+		);
+
+		assert.match(headerOf(raw, "Content-Type") ?? "", /^multipart\/mixed/);
+		assert.match(raw, /Content-Type: application\/pdf; name=invoice\.pdf/);
+		assert.match(raw, /Content-Disposition: attachment; filename=invoice\.pdf/);
+		assert.match(raw, /Content-Type: image\/png; name=logo\.png/);
+		assert.match(raw, /Content-Disposition: inline; filename=logo\.png/);
+		assert.match(raw, /Content-ID: <logo-cid>/);
+		assert.ok(raw.includes(Buffer.from("pdf-bytes").toString("base64")));
+		assert.ok(raw.includes(Buffer.from("png-bytes").toString("base64")));
+	});
+
+	it("dates the rendered copy from the moment the send was recorded", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(baseOutbox({ sentAt: 1_700_000_000_000 })),
+			),
+		);
+		assert.equal(
+			new Date(headerOf(raw, "Date") ?? "").getTime(),
+			1_700_000_000_000,
+		);
+	});
+
+	it("carries addressing and identity headers through unchanged", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(
+					baseOutbox({
+						toAddresses: ["a@example.com", "b@example.com"],
+						ccAddresses: ["c@example.com"],
+						replyToAddress: "reply@example.com",
+						subject: "Quarterly numbers",
+						messageIdValue: "abc.123@example.com",
+						inReplyTo: "parent@example.com",
+						references: ["one@example.com", "two@example.com"],
+					}),
+				),
+			),
+		);
+
+		assert.equal(headerOf(raw, "To"), "a@example.com, b@example.com");
+		assert.equal(headerOf(raw, "Cc"), "c@example.com");
+		assert.equal(headerOf(raw, "Reply-To"), "reply@example.com");
+		assert.equal(headerOf(raw, "Subject"), "Quarterly numbers");
+		assert.equal(headerOf(raw, "Message-ID"), "<abc.123@example.com>");
+		assert.equal(headerOf(raw, "In-Reply-To"), "<parent@example.com>");
+		assert.equal(
+			headerOf(raw, "References"),
+			"<one@example.com> <two@example.com>",
+		);
+	});
+
+	// Only the sender ever reads this render, so the header stays. An SMTP
+	// transport strips it from the copy that goes to a recipient.
+	it("keeps Bcc on the copy filed in Sent", async () => {
+		const raw = String(
+			await renderRawMessage(
+				buildMailMessage(baseOutbox({ bccAddresses: ["hidden@example.com"] })),
+			),
+		);
+		assert.equal(headerOf(raw, "Bcc"), "hidden@example.com");
+	});
+});

package/src/message-builder.ts

@@ -1,4 +1,5 @@
 import type { OutboxMessageItem } from "@remit/data-ports";
+import nodemailer, { type SendMailOptions } from "nodemailer";
 
 export interface MailMessage {
 	from: string;
@@ -12,6 +13,7 @@ export interface MailMessage {
 	messageId: string;
 	inReplyTo?: string;
 	references?: string;
+	date?: Date;
 	attachments?: MailAttachment[];
 }
 
@@ -23,29 +25,66 @@ export interface MailAttachment {
 	contentDisposition?: "attachment" | "inline";
 }
 
-/**
- * Build Nodemailer message options from OutboxMessage entity
- */
+// Nodemailer parses the From string back into a name and an address, so a
+// display name carrying a quote or a backslash has to survive that round trip.
+const formatFrom = (address: string, name: string | undefined): string =>
+	name ? `"${name.replace(/(["\\])/g, "\\$1")}" <${address}>` : address;
+
+/** The one description of an outgoing message: the wire copy and the Sent copy. */
 export const buildMailMessage = (
 	outbox: OutboxMessageItem,
 	attachments?: MailAttachment[],
-): MailMessage => {
-	const from = outbox.fromName
-		? `"${outbox.fromName}" <${outbox.fromAddress}>`
-		: outbox.fromAddress;
+): MailMessage => ({
+	from: formatFrom(outbox.fromAddress, outbox.fromName),
+	to: outbox.toAddresses,
+	cc: outbox.ccAddresses,
+	bcc: outbox.bccAddresses,
+	replyTo: outbox.replyToAddress,
+	subject: outbox.subject,
+	text: outbox.textBody,
+	html: outbox.htmlBody,
+	messageId: `<${outbox.messageIdValue}>`,
+	inReplyTo: outbox.inReplyTo ? `<${outbox.inReplyTo}>` : undefined,
+	references: outbox.references?.map((r) => `<${r}>`).join(" "),
+	// Only the Sent copy has one to carry: the row is stamped after the
+	// submission is accepted, so on the wire path this is always absent and
+	// nodemailer dates the message as it goes out.
+	date: outbox.sentAt ? new Date(outbox.sentAt) : undefined,
+	attachments,
+});
+
+export const toNodemailerOptions = (message: MailMessage): SendMailOptions => ({
+	from: message.from,
+	to: message.to,
+	cc: message.cc,
+	bcc: message.bcc,
+	replyTo: message.replyTo,
+	subject: message.subject,
+	text: message.text,
+	html: message.html,
+	messageId: message.messageId,
+	inReplyTo: message.inReplyTo,
+	references: message.references,
+	date: message.date,
+	attachments: message.attachments?.map((a) => ({
+		filename: a.filename,
+		content: a.content,
+		contentType: a.contentType,
+		cid: a.cid,
+		contentDisposition: a.contentDisposition,
+	})),
+});
+
+/** The same message as RFC822 bytes, for an IMAP APPEND. */
+export const renderRawMessage = async (
+	message: MailMessage,
+): Promise<Buffer> => {
+	const transport = nodemailer.createTransport({ streamTransport: true });
+	const info = await transport.sendMail(toNodemailerOptions(message));
 
-	return {
-		from,
-		to: outbox.toAddresses,
-		cc: outbox.ccAddresses,
-		bcc: outbox.bccAddresses,
-		replyTo: outbox.replyToAddress,
-		subject: outbox.subject,
-		text: outbox.textBody,
-		html: outbox.htmlBody,
-		messageId: `<${outbox.messageIdValue}>`,
-		inReplyTo: outbox.inReplyTo ? `<${outbox.inReplyTo}>` : undefined,
-		references: outbox.references?.map((r) => `<${r}>`).join(" "),
-		attachments,
-	};
+	const chunks: Buffer[] = [];
+	for await (const chunk of info.message as AsyncIterable<Buffer>) {
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
 };

package/src/smtp-client.ts

@@ -1,5 +1,5 @@
 import nodemailer from "nodemailer";
-import type { MailMessage } from "./message-builder.js";
+import { type MailMessage, toNodemailerOptions } from "./message-builder.js";
 
 /**
  * Discriminated union of SMTP authentication credentials.
@@ -114,26 +114,7 @@ export const sendMail = async (
 	});
 
 	return transporter
-		.sendMail({
-			from: message.from,
-			to: message.to,
-			cc: message.cc,
-			bcc: message.bcc,
-			replyTo: message.replyTo,
-			subject: message.subject,
-			text: message.text,
-			html: message.html,
-			messageId: message.messageId,
-			inReplyTo: message.inReplyTo,
-			references: message.references,
-			attachments: message.attachments?.map((a) => ({
-				filename: a.filename,
-				content: a.content as Buffer,
-				contentType: a.contentType,
-				cid: a.cid,
-				contentDisposition: a.contentDisposition,
-			})),
-		})
+		.sendMail(toNodemailerOptions(message))
 		.then((info) => ({
 			success: true,
 			messageId: info.messageId,