@c9up/rover 0.1.8 → 0.1.10

package/src/Mail.ts

@@ -4,6 +4,7 @@ import { BaseMail } from "./BaseMail.js";
 import {
 	type MailAttachment,
 	type MailMessage,
+	type MessageBodyTemplates,
 	MessageBuilder,
 } from "./MessageBuilder.js";
 import {
@@ -59,6 +60,11 @@ export type MailSendOutcome = MailSendResult | undefined;
 
 export interface MailTransport {
 	send(message: MailMessage): Promise<MailSendOutcome>;
+	/**
+	 * Release what this transport holds open — an SMTP connection pool, mostly.
+	 * Optional: an HTTP-API transport has nothing to close.
+	 */
+	close?(): Promise<void>;
 }
 
 /**
@@ -70,24 +76,40 @@ export interface EmitterLike {
 }
 
 /**
- * Emitted (`mail:sending`) right before the transport `send` runs — no
- * `messageId` yet, since the provider hasn't accepted the message.
+ * What every mail lifecycle event carries, matching `@adonisjs/mail`:
+ * the mailer that handled it, the message itself, and the templates it was
+ * rendered from. A listener migrating over reads `message.to` / `views.html`.
+ *
+ * `transportName` and the flattened recipient lists are rover's own and stay:
+ * the transport name is the same string as `mailerName` under the name rover
+ * used first, and a listener that only wants the addresses should not have to
+ * reach into the message for them.
  */
-export interface MailSendingEvent {
+export type { MessageBodyTemplates };
+
+export interface MailEventBase {
+	/** AdonisJS name for the mailer that handled the message. */
+	mailerName: string;
+	/** The built message. */
+	message: MailMessage;
+	/** Templates the message was rendered from, empty when it carried none. */
+	views: MessageBodyTemplates;
 	to: string[];
 	cc: string[];
 	bcc: string[];
+	/** rover's original name for {@link MailEventBase.mailerName}. */
 	transportName: string;
 	timestamp: number;
 }
 
-export interface MailSentEvent {
+/**
+ * Emitted (`mail:sending`) right before the transport `send` runs — no
+ * `messageId` yet, since the provider hasn't accepted the message.
+ */
+export interface MailSendingEvent extends MailEventBase {}
+
+export interface MailSentEvent extends MailEventBase {
 	messageId: string;
-	to: string[];
-	cc: string[];
-	bcc: string[];
-	transportName: string;
-	timestamp: number;
 }
 
 /**
@@ -95,22 +117,13 @@ export interface MailSentEvent {
  * only present on `mail:queued` (once the job has been accepted by the queue /
  * in-memory messenger).
  */
-export interface MailQueueEvent {
-	to: string[];
-	cc: string[];
-	bcc: string[];
-	transportName: string;
+export interface MailQueueEvent extends MailEventBase {
 	queue: string;
 	jobId?: string;
-	timestamp: number;
 }
 
-export interface MailFailedEvent {
+export interface MailFailedEvent extends MailEventBase {
 	messageId: string;
-	to: string[];
-	cc: string[];
-	bcc: string[];
-	transportName: string;
 	error: {
 		code: string;
 		message: string;
@@ -118,13 +131,21 @@ export interface MailFailedEvent {
 		upstreamStatusRaw?: string;
 		attempts: number;
 	};
-	timestamp: number;
 }
 
 export interface MailConfig {
 	default: string;
 	from: string;
-	transports: Record<
+	transports?: Record<
+		string,
+		{ transport: string; retry?: RetryConfig; [key: string]: unknown }
+	>;
+	/**
+	 * AdonisJS spelling of `transports`. Both are accepted and mean the same
+	 * thing, so a migrated `config/mail.ts` runs with its imports rewritten and
+	 * nothing else.
+	 */
+	mailers?: Record<
 		string,
 		{ transport: string; retry?: RetryConfig; [key: string]: unknown }
 	>;
@@ -236,6 +257,10 @@ export class SmtpTransport implements MailTransport {
 				subject: message.subject,
 				html: message.html,
 				text: message.text,
+				// nodemailer reads `watchHtml`; there is no bare `watch` field in
+				// its mail composer, so writing one — as AdonisJS does — never
+				// reaches the wire.
+				watchHtml: message.watchHtml,
 				priority: message.priority,
 				messageId: message.messageId,
 				inReplyTo: message.inReplyTo,
@@ -243,12 +268,20 @@ export class SmtpTransport implements MailTransport {
 				headers: Object.keys(message.headers).length
 					? message.headers
 					: undefined,
+				encoding: message.encoding,
+				// `list` is NOT passed: `build()` already rendered the `List-*`
+				// headers into `headers`, so handing nodemailer the structured form
+				// too would emit each of them twice.
+				icalEvent: message.icalEvent,
 				attachments: message.attachments.length
 					? message.attachments.map((att) => ({
 							filename: att.filename,
 							content: att.content,
 							contentType: att.contentType,
 							cid: att.cid,
+							contentDisposition: att.contentDisposition,
+							encoding: att.encoding,
+							headers: att.headers,
 						}))
 					: undefined,
 			});
@@ -258,6 +291,14 @@ export class SmtpTransport implements MailTransport {
 			throw wrapSmtpError(err);
 		}
 	}
+
+	/**
+	 * Drain nodemailer's connection pool. Idempotent — nodemailer tolerates a
+	 * second close, and a shutdown path may run twice.
+	 */
+	async close(): Promise<void> {
+		this.#transporter.close();
+	}
 }
 
 /**
@@ -377,7 +418,10 @@ export class Mail {
 			setViewsRoot(config.viewsRoot);
 		}
 
-		for (const [name, transportConfig] of Object.entries(config.transports)) {
+		// `mailers` (AdonisJS) and `transports` (rover) are the same map under two
+		// names; a config that sets both gets both, last name wins per key.
+		const declared = { ...config.transports, ...config.mailers };
+		for (const [name, transportConfig] of Object.entries(declared)) {
 			const factory = transportFactories[transportConfig.transport];
 			if (!factory) {
 				throw new RoverError(
@@ -395,11 +439,53 @@ export class Mail {
 		}
 
 		if (options?.queue) {
-			this.#queue = options.queue;
-			this.#queue.register(this.#queueName, new MailJobHandler(this));
+			this.setMessenger(options.queue);
 		}
 	}
 
+	/**
+	 * Send a message that is already built (AdonisJS `sendCompiled`).
+	 *
+	 * What a queue worker calls: the message was composed and serialised
+	 * elsewhere, so there is nothing left to render. An alias of
+	 * {@link dispatchMessage}, which is the name ream used first.
+	 */
+	async sendCompiled(message: MailMessage, transport?: string): Promise<void> {
+		await this.dispatchMessage(message, transport);
+	}
+
+	/**
+	 * Queue a message that is already built (AdonisJS `sendLaterCompiled`).
+	 *
+	 * Returns the job id, like {@link sendLater}.
+	 */
+	async sendLaterCompiled(
+		message: MailMessage,
+		options?: { transport?: string; queue?: string },
+	): Promise<string> {
+		// No views: a compiled message was rendered elsewhere, and the templates
+		// that produced it did not travel with it.
+		return this.#enqueue({ message, views: {} }, options);
+	}
+
+	/**
+	 * Hand `sendLater()` a queue after construction (AdonisJS `setMessenger`).
+	 *
+	 * The constructor takes one too, but a queue is often resolved later than
+	 * the mailer — a provider that boots after this one, a test that swaps it.
+	 * Without this the only way in was the constructor, so an app migrating
+	 * from `mail.setMessenger(queue)` stopped at a TypeError.
+	 *
+	 * "Messenger" is upstream's word for what rover's config calls `queue`;
+	 * they are the same thing, and the method keeps the upstream name so a
+	 * migrated call site resolves.
+	 */
+	setMessenger(messenger: BayQueueLike): this {
+		this.#queue = messenger;
+		this.#queue.register(this.#queueName, new MailJobHandler(this));
+		return this;
+	}
+
 	/** Send an email using the fluent message builder. */
 	async send(
 		callback: (message: MessageBuilder) => void,
@@ -416,15 +502,9 @@ export class Mail {
 		// BaseMail, for constructor-based assertions) instead of touching a
 		// transport. Still fire the send lifecycle so event wiring stays testable.
 		if (this.#fake !== null) {
-			const message = await this.#buildMessage(arg);
+			const { message, views } = await this.#buildMessageWithViews(arg);
 			this.#fake.trackSent(message, arg instanceof BaseMail ? arg : undefined);
-			const base = {
-				to: message.to.slice(),
-				cc: message.cc.slice(),
-				bcc: message.bcc.slice(),
-				transportName,
-				timestamp: Date.now(),
-			};
+			const base = this.#eventBase(message, views, transportName);
 			this.#fireSending(base);
 			this.#fireSent({ ...base, messageId: randomBytes(16).toString("hex") });
 			return;
@@ -434,8 +514,8 @@ export class Mail {
 			throw new Error(`Mail transport '${transportName}' not configured`);
 		}
 
-		const message = await this.#buildMessage(arg);
-		await this.dispatchMessage(message, transportName);
+		const { message, views } = await this.#buildMessageWithViews(arg);
+		await this.dispatchMessage(message, transportName, undefined, views);
 	}
 
 	/**
@@ -448,24 +528,34 @@ export class Mail {
 		arg: ((message: MessageBuilder) => void) | BaseMail,
 		options?: { transport?: string; queue?: string },
 	): Promise<string> {
-		const message = await this.#buildMessage(arg);
+		const built = await this.#buildMessageWithViews(arg);
+		return this.#enqueue(
+			{ ...built, source: arg instanceof BaseMail ? arg : undefined },
+			options,
+		);
+	}
+
+	/** The queueing half, shared with {@link sendLaterCompiled}. */
+	async #enqueue(
+		built: {
+			message: MailMessage;
+			views: MessageBodyTemplates;
+			/** The BaseMail it came from, for `assertQueued(WelcomeMail)`. */
+			source?: BaseMail;
+		},
+		options?: { transport?: string; queue?: string },
+	): Promise<string> {
+		const { message, views } = built;
 		const queueName = options?.queue ?? this.#queueName;
 		const transportName = options?.transport ?? this.#defaultTransport;
 		const base: MailQueueEvent = {
-			to: message.to.slice(),
-			cc: message.cc.slice(),
-			bcc: message.bcc.slice(),
-			transportName,
+			...this.#eventBase(message, views, transportName),
 			queue: queueName,
-			timestamp: Date.now(),
 		};
 
 		// Fake mode: capture into the queued bucket, don't dispatch.
 		if (this.#fake !== null) {
-			this.#fake.trackQueued(
-				message,
-				arg instanceof BaseMail ? arg : undefined,
-			);
+			this.#fake.trackQueued(message, built.source);
 			const jobId = `fake_${randomBytes(12).toString("hex")}`;
 			this.#fireQueueing(base);
 			this.#fireQueued({ ...base, jobId });
@@ -497,6 +587,11 @@ export class Mail {
 		message: MailMessage,
 		transportName?: string,
 		overrideRetry?: RetryConfig,
+		// The templates the message came from, when the caller still knows them.
+		// A message revived from a queue payload does not: the rendered bodies
+		// were serialised, the templates that produced them were not. Empty is
+		// the honest answer there rather than a guess.
+		views: MessageBodyTemplates = {},
 	): Promise<void> {
 		// Defense-in-depth: queue payloads bypass `#buildMessage`, so a
 		// malformed message deserialised from storage would otherwise reach
@@ -517,13 +612,7 @@ export class Mail {
 
 		// Fire once before the first attempt — `mail:sending` signals intent, not
 		// per-retry, matching @adonisjs/mail.
-		this.#fireSending({
-			to: message.to.slice(),
-			cc: message.cc.slice(),
-			bcc: message.bcc.slice(),
-			transportName: name,
-			timestamp: Date.now(),
-		});
+		this.#fireSending(this.#eventBase(message, views, name));
 
 		for (let attempt = 1; attempt <= retry.maxAttempts; attempt += 1) {
 			let sendResult: MailSendOutcome;
@@ -535,13 +624,9 @@ export class Mail {
 				if (!retryable || attempt === retry.maxAttempts) {
 					const annotated = this.#withAttempts(err, attempt);
 					this.#fireFailed({
+						...this.#eventBase(message, views, name),
 						messageId: generatedId,
-						to: message.to.slice(),
-						cc: message.cc.slice(),
-						bcc: message.bcc.slice(),
-						transportName: name,
 						error: errorDescriptor(annotated, attempt),
-						timestamp: Date.now(),
 					});
 					throw annotated;
 				}
@@ -563,12 +648,8 @@ export class Mail {
 			const providerId =
 				providerIdRaw && providerIdRaw.length > 0 ? providerIdRaw : undefined;
 			this.#fireSent({
+				...this.#eventBase(message, views, name),
 				messageId: providerId ?? generatedId,
-				to: message.to.slice(),
-				cc: message.cc.slice(),
-				bcc: message.bcc.slice(),
-				transportName: name,
-				timestamp: Date.now(),
 			});
 			return;
 		}
@@ -641,21 +722,49 @@ export class Mail {
 		}
 	}
 
-	async #buildMessage(
+	/**
+	 * Build the message AND report which templates it was rendered from, since
+	 * every lifecycle event carries both (AdonisJS `message` + `views`).
+	 */
+	async #buildMessageWithViews(
 		arg: ((message: MessageBuilder) => void) | BaseMail,
-	): Promise<MailMessage> {
+	): Promise<{ message: MailMessage; views: MessageBodyTemplates }> {
 		let result: MailMessage;
+		let views: MessageBodyTemplates;
 		if (arg instanceof BaseMail) {
 			const built = await arg.build(this.#viewsRoot);
 			result = built.from ? built : { ...built, from: this.#defaultFrom };
+			views = arg.message.views;
 		} else {
 			const builder = new MessageBuilder();
 			builder.from(this.#defaultFrom);
 			arg(builder);
 			result = await builder.build(this.#viewsRoot);
+			views = builder.views;
 		}
 		validateMailMessage(result);
-		return result;
+		return { message: result, views };
+	}
+
+	/**
+	 * The fields every lifecycle event shares. One place, so `mail:sending` and
+	 * `mail:sent` cannot describe the same message differently.
+	 */
+	#eventBase(
+		message: MailMessage,
+		views: MessageBodyTemplates,
+		mailerName: string,
+	): MailEventBase {
+		return {
+			mailerName,
+			message,
+			views,
+			to: message.to.slice(),
+			cc: message.cc.slice(),
+			bcc: message.bcc.slice(),
+			transportName: mailerName,
+			timestamp: Date.now(),
+		};
 	}
 
 	/**
@@ -681,6 +790,26 @@ export class Mail {
 		return t;
 	}
 
+	/**
+	 * Close one transport's open connections (Adonis `close`).
+	 *
+	 * An SMTP pool keeps sockets alive between sends; a process that exits
+	 * without closing them leaves the server holding connections until it times
+	 * them out. Unknown or already-closed names are a no-op — shutdown is not
+	 * the place to throw.
+	 */
+	async close(name?: string): Promise<void> {
+		const transportName = name ?? this.#defaultTransport;
+		await this.#transports.get(transportName)?.close?.();
+	}
+
+	/** Close every built transport (Adonis `closeAll`). What a shutdown hook calls. */
+	async closeAll(): Promise<void> {
+		await Promise.all(
+			[...this.#transports.values()].map((transport) => transport.close?.()),
+		);
+	}
+
 	/**
 	 * Enter fake mode. Every subsequent `send()` / `sendLater()` — including via
 	 * `use(name)` — is captured by the returned `FakeMail` instead of hitting a