@c9up/rover 0.1.6 → 0.1.7

package/src/queue/MemoryMailMessenger.ts

@@ -0,0 +1,45 @@
+import { randomBytes } from "node:crypto";
+import type { EmitterLike, MailMessage } from "../Mail.js";
+import type { MailDispatcher } from "./MailJob.js";
+
+/**
+ * Default in-memory messenger for `sendLater()` when no `@c9up/bay` queue is
+ * wired — mirrors `@adonisjs/mail`'s `MemoryQueueMessenger`. The send is
+ * scheduled on a microtask so `sendLater()` returns immediately (fire-and-
+ * forget). Background delivery failures surface on the `queued:mail:error`
+ * event rather than becoming unhandled rejections.
+ */
+export class MemoryMailMessenger {
+	#dispatcher: MailDispatcher;
+	#emitter: EmitterLike | null;
+
+	constructor(dispatcher: MailDispatcher, emitter: EmitterLike | null) {
+		this.#dispatcher = dispatcher;
+		this.#emitter = emitter;
+	}
+
+	queue(message: MailMessage, transport?: string): string {
+		const jobId = `mem_${randomBytes(12).toString("hex")}`;
+		queueMicrotask(() => {
+			this.#dispatcher
+				.dispatchMessage(message, transport)
+				.catch((error: unknown) => {
+					if (!this.#emitter) return;
+					try {
+						this.#emitter.emit("queued:mail:error", {
+							jobId,
+							transportName: transport,
+							error:
+								error instanceof Error
+									? { message: error.message }
+									: { message: String(error) },
+						});
+					} catch {
+						// Event bus failure ≠ mail failure — swallow so the microtask
+						// never rejects.
+					}
+				});
+		});
+		return jobId;
+	}
+}

package/src/testing/FakeMail.ts

@@ -1,3 +1,4 @@
+import { BaseMail } from "../BaseMail.js";
 import type { MailMessage, MailSendOutcome, MailTransport } from "../Mail.js";
 
 export interface FakeMailPredicate {
@@ -15,59 +16,259 @@ export type FakeMailPredicateArg =
 	| ((m: MailMessage) => boolean);
 
 /**
- * In-memory transport for tests — captures every `send(message)` call and
- * exposes Adonis/Laravel-style `assertSent` / `assertNotSent` helpers.
+ * Constructor of a `BaseMail` subclass — the `new (...args: never[]) => T`
+ * form keeps `instanceof` sound without an `any` in the signature.
+ */
+export type MailConstructor<T extends BaseMail = BaseMail> = new (
+	...args: never[]
+) => T;
+
+interface Capture {
+	message: MailMessage;
+	mail?: BaseMail;
+}
+
+/**
+ * In-memory capture for tests — records every `send` (`trackSent`) and
+ * `sendLater` (`trackQueued`) routed through a faked `Mail`, and exposes
+ * Adonis/Laravel-style assertions over both message content (predicate form)
+ * and the originating `BaseMail` class (constructor form).
  *
  * Not re-exported from the main barrel; reach via `@c9up/rover/testing`.
  */
 export class FakeMail implements MailTransport {
-	#captured: MailMessage[] = [];
+	#sent: Capture[] = [];
+	#queued: Capture[] = [];
 
+	/** MailTransport contract — direct `send()` capture (backward compatible). */
 	async send(message: MailMessage): Promise<MailSendOutcome> {
-		this.#captured.push(message);
+		this.trackSent(message);
 		return undefined;
 	}
 
+	/** Record a synchronously-sent message (and its source `BaseMail`, if any). */
+	trackSent(message: MailMessage, mail?: BaseMail): void {
+		this.#sent.push({ message, mail });
+	}
+
+	/** Record a queued message (and its source `BaseMail`, if any). */
+	trackQueued(message: MailMessage, mail?: BaseMail): void {
+		this.#queued.push({ message, mail });
+	}
+
 	/**
-	 * Return a defensive snapshot of captured messages. Each message is cloned
+	 * Return a defensive snapshot of sent messages. Each message is cloned
 	 * (shallow-per-field with array copies) so test-side mutations can't bleed
 	 * back into the internal capture store — avoids cross-test contamination.
 	 */
 	getSent(): MailMessage[] {
-		return this.#captured.map((m) => ({
-			from: m.from,
-			to: m.to.slice(),
-			cc: m.cc.slice(),
-			bcc: m.bcc.slice(),
-			replyTo: m.replyTo,
-			subject: m.subject,
-			html: m.html,
-			text: m.text,
-			attachments: m.attachments.slice(),
-			headers: { ...m.headers },
-		}));
+		return this.#sent.map((e) => cloneMessage(e.message));
+	}
+
+	/** Return a defensive snapshot of queued messages. */
+	getQueued(): MailMessage[] {
+		return this.#queued.map((e) => cloneMessage(e.message));
 	}
 
 	reset(): void {
-		this.#captured = [];
+		this.#sent = [];
+		this.#queued = [];
 	}
 
-	assertSent(predicate: FakeMailPredicateArg): void {
-		const match = makeMatcher(predicate);
-		if (this.#captured.some(match)) return;
-		throw new Error(
-			`mail.assertSent() failed — no captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`,
+	assertSent(predicate: FakeMailPredicateArg): void;
+	assertSent<T extends BaseMail>(
+		mailConstructor: MailConstructor<T>,
+		findFn?: (mail: T) => boolean,
+	): void;
+	assertSent(
+		arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+		findFn?: (mail: BaseMail) => boolean,
+	): void {
+		this.#assertPresence("assertSent", "sent", this.#sent, arg, findFn, true);
+	}
+
+	assertNotSent(predicate: FakeMailPredicateArg): void;
+	assertNotSent<T extends BaseMail>(
+		mailConstructor: MailConstructor<T>,
+		findFn?: (mail: T) => boolean,
+	): void;
+	assertNotSent(
+		arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+		findFn?: (mail: BaseMail) => boolean,
+	): void {
+		this.#assertPresence(
+			"assertNotSent",
+			"sent",
+			this.#sent,
+			arg,
+			findFn,
+			false,
+		);
+	}
+
+	assertQueued(predicate: FakeMailPredicateArg): void;
+	assertQueued<T extends BaseMail>(
+		mailConstructor: MailConstructor<T>,
+		findFn?: (mail: T) => boolean,
+	): void;
+	assertQueued(
+		arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+		findFn?: (mail: BaseMail) => boolean,
+	): void {
+		this.#assertPresence(
+			"assertQueued",
+			"queued",
+			this.#queued,
+			arg,
+			findFn,
+			true,
 		);
 	}
 
-	assertNotSent(predicate: FakeMailPredicateArg): void {
-		const match = makeMatcher(predicate);
-		const found = this.#captured.find(match);
-		if (!found) return;
+	assertNotQueued(predicate: FakeMailPredicateArg): void;
+	assertNotQueued<T extends BaseMail>(
+		mailConstructor: MailConstructor<T>,
+		findFn?: (mail: T) => boolean,
+	): void;
+	assertNotQueued(
+		arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+		findFn?: (mail: BaseMail) => boolean,
+	): void {
+		this.#assertPresence(
+			"assertNotQueued",
+			"queued",
+			this.#queued,
+			arg,
+			findFn,
+			false,
+		);
+	}
+
+	assertSentCount(count: number): void;
+	assertSentCount(
+		mailConstructor: MailConstructor<BaseMail>,
+		count: number,
+	): void;
+	assertSentCount(
+		arg: number | MailConstructor<BaseMail>,
+		count?: number,
+	): void {
+		this.#assertCount("assertSentCount", this.#sent, arg, count);
+	}
+
+	assertQueuedCount(count: number): void;
+	assertQueuedCount(
+		mailConstructor: MailConstructor<BaseMail>,
+		count: number,
+	): void;
+	assertQueuedCount(
+		arg: number | MailConstructor<BaseMail>,
+		count?: number,
+	): void {
+		this.#assertCount("assertQueuedCount", this.#queued, arg, count);
+	}
+
+	assertNoneSent(): void {
+		if (this.#sent.length !== 0) {
+			throw new Error(
+				`mail.assertNoneSent() failed — expected zero sent messages, found ${this.#sent.length}.\n${describeCaptured(this.#sent)}`,
+			);
+		}
+	}
+
+	assertNoneQueued(): void {
+		if (this.#queued.length !== 0) {
+			throw new Error(
+				`mail.assertNoneQueued() failed — expected zero queued messages, found ${this.#queued.length}.\n${describeCaptured(this.#queued)}`,
+			);
+		}
+	}
+
+	/**
+	 * Shared body for the present/absent assertions. `expectPresent` flips the
+	 * pass/fail sense so `assertSent` and `assertNotSent` share one code path.
+	 */
+	#assertPresence(
+		method: string,
+		bucket: string,
+		entries: Capture[],
+		arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+		findFn: ((mail: BaseMail) => boolean) | undefined,
+		expectPresent: boolean,
+	): void {
+		const found = isMailConstructor(arg)
+			? entries.some(
+					(e) =>
+						e.mail !== undefined &&
+						e.mail instanceof arg &&
+						(findFn ? findFn(e.mail) : true),
+				)
+			: entries.some((e) => makeMatcher(arg)(e.message));
+		if (found === expectPresent) return;
+		const target = isMailConstructor(arg)
+			? `an instance of ${arg.name}`
+			: describePredicate(arg);
+		const reason = expectPresent
+			? `no ${bucket} message matches ${target}`
+			: `at least one ${bucket} message matches ${target}`;
 		throw new Error(
-			`mail.assertNotSent() failed — at least one captured message matches ${describePredicate(predicate)}.\n${describeCaptured(this.#captured)}`,
+			`mail.${method}() failed — ${reason}.\n${describeCaptured(entries)}`,
 		);
 	}
+
+	#assertCount(
+		method: string,
+		entries: Capture[],
+		arg: number | MailConstructor<BaseMail>,
+		count: number | undefined,
+	): void {
+		if (typeof arg === "number") {
+			if (entries.length !== arg) {
+				throw new Error(
+					`mail.${method}() failed — expected ${arg}, found ${entries.length}.\n${describeCaptured(entries)}`,
+				);
+			}
+			return;
+		}
+		const expected = count ?? 0;
+		const actual = entries.filter(
+			(e) => e.mail !== undefined && e.mail instanceof arg,
+		).length;
+		if (actual !== expected) {
+			throw new Error(
+				`mail.${method}() failed — expected ${expected} of ${arg.name}, found ${actual}.\n${describeCaptured(entries)}`,
+			);
+		}
+	}
+}
+
+function isMailConstructor(
+	arg: FakeMailPredicateArg | MailConstructor<BaseMail>,
+): arg is MailConstructor<BaseMail> {
+	return (
+		typeof arg === "function" &&
+		typeof arg.prototype === "object" &&
+		arg.prototype instanceof BaseMail
+	);
+}
+
+function cloneMessage(m: MailMessage): MailMessage {
+	return {
+		from: m.from,
+		to: m.to.slice(),
+		cc: m.cc.slice(),
+		bcc: m.bcc.slice(),
+		replyTo: m.replyTo,
+		subject: m.subject,
+		html: m.html,
+		text: m.text,
+		attachments: m.attachments.slice(),
+		headers: { ...m.headers },
+		priority: m.priority,
+		messageId: m.messageId,
+		inReplyTo: m.inReplyTo,
+		references: m.references ? m.references.slice() : undefined,
+	};
 }
 
 function makeMatcher(
@@ -102,11 +303,11 @@ function describePredicate(predicate: FakeMailPredicateArg): string {
 	return JSON.stringify(predicate);
 }
 
-function describeCaptured(captured: MailMessage[]): string {
+function describeCaptured(captured: Capture[]): string {
 	if (captured.length === 0) return "Captured: (none)";
 	const lines = captured.map(
-		(m, i) =>
-			`  [${i}] to=[${m.to.join(", ")}] subject="${m.subject}" from="${m.from}"`,
+		(e, i) =>
+			`  [${i}] to=[${e.message.to.join(", ")}] subject="${e.message.subject}" from="${e.message.from}"`,
 	);
 	return `Captured (${captured.length}):\n${lines.join("\n")}`;
 }

package/src/transports/BrevoTransport.ts

@@ -0,0 +1,174 @@
+import { Buffer } from "node:buffer";
+import {
+	type MailMessage,
+	type MailSendOutcome,
+	type MailTransport,
+	registerTransport,
+} from "../Mail.js";
+import { RoverError } from "../RoverError.js";
+import { wrapFetchNetworkError } from "./fetchError.js";
+
+const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
+const normalizeConfig = (v: string): string => stripCrlf(v).trim();
+const MAX_PROVIDER_MESSAGE = 16 * 1024;
+const capMessage = (s: string): string =>
+	s.length <= MAX_PROVIDER_MESSAGE
+		? s
+		: `${s.slice(0, MAX_PROVIDER_MESSAGE)}...[truncated]`;
+/** Redact Basic/Bearer tokens if the upstream echoes our own request headers. */
+const redactSecrets = (s: string): string =>
+	s
+		.replace(/Bearer\s+[A-Za-z0-9._~+/=-]+/g, "Bearer [REDACTED]")
+		.replace(/Basic\s+[A-Za-z0-9+/=]+/g, "Basic [REDACTED]");
+
+interface BrevoContact {
+	email: string;
+	name?: string;
+}
+
+interface BrevoBody {
+	sender: BrevoContact;
+	to: BrevoContact[];
+	cc?: BrevoContact[];
+	bcc?: BrevoContact[];
+	replyTo?: BrevoContact;
+	subject: string;
+	htmlContent?: string;
+	textContent?: string;
+	headers?: Record<string, string>;
+	attachment?: Array<{ name: string; content: string }>;
+}
+
+/**
+ * Brevo (formerly Sendinblue) transactional email transport. Talks to the
+ * `v3/smtp/email` REST API over `fetch`, mirroring the `@adonisjs/mail` Brevo
+ * transport. Same conventions as the other fetch-based transports (Resend /
+ * SES): CRLF stripping at the wire boundary, secret redaction, `retry-after`
+ * surfacing.
+ */
+export class BrevoTransport implements MailTransport {
+	#apiKey: string;
+	#baseUrl: string;
+
+	constructor(config: Record<string, unknown>) {
+		const apiKey =
+			typeof config.apiKey === "string"
+				? normalizeConfig(config.apiKey)
+				: typeof config.key === "string"
+					? normalizeConfig(config.key)
+					: "";
+		if (!apiKey) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"Brevo transport requires apiKey",
+				{ hint: "Set { apiKey } in your mail config." },
+			);
+		}
+		this.#apiKey = apiKey;
+		this.#baseUrl =
+			typeof config.baseUrl === "string"
+				? normalizeConfig(config.baseUrl).replace(/\/+$/, "")
+				: "https://api.brevo.com";
+	}
+
+	async send(message: MailMessage): Promise<MailSendOutcome> {
+		if (
+			message.to.length === 0 &&
+			message.cc.length === 0 &&
+			message.bcc.length === 0
+		) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"Mail message has no recipients",
+				{ hint: "Set at least one `to`, `cc`, or `bcc` before sending." },
+			);
+		}
+		const body: BrevoBody = {
+			sender: parseContact(message.from),
+			to: (message.to.length > 0 ? message.to : [message.from]).map(
+				parseContact,
+			),
+			subject: stripCrlf(message.subject),
+		};
+		if (message.cc.length) body.cc = message.cc.map(parseContact);
+		if (message.bcc.length) body.bcc = message.bcc.map(parseContact);
+		if (message.replyTo) body.replyTo = parseContact(message.replyTo);
+		if (message.html) body.htmlContent = message.html;
+		if (message.text) body.textContent = message.text;
+		const customHeaders = Object.entries(message.headers);
+		if (customHeaders.length > 0) {
+			body.headers = {};
+			for (const [k, v] of customHeaders) {
+				body.headers[stripCrlf(k)] = Array.isArray(v)
+					? v.map(stripCrlf).join(", ")
+					: stripCrlf(v);
+			}
+		}
+		if (message.attachments.length > 0) {
+			body.attachment = message.attachments.map((att) => ({
+				name: stripCrlf(att.filename),
+				content: Buffer.from(att.content as Buffer | string).toString("base64"),
+			}));
+		}
+
+		let res: Response;
+		try {
+			res = await fetch(`${this.#baseUrl}/v3/smtp/email`, {
+				method: "POST",
+				headers: {
+					"api-key": this.#apiKey,
+					"Content-Type": "application/json",
+					Accept: "application/json",
+				},
+				body: JSON.stringify(body),
+			});
+		} catch (err) {
+			throw wrapFetchNetworkError("brevo", err);
+		}
+		if (!res.ok) {
+			const providerMessage = redactSecrets(capMessage(await res.text()));
+			const retryAfter = res.headers.get("retry-after") ?? undefined;
+			const ctx: Record<string, string> = {
+				provider: "brevo",
+				upstreamStatus: String(res.status),
+				providerMessage,
+			};
+			if (retryAfter) ctx.retryAfter = retryAfter;
+			throw new RoverError(
+				"MAIL_PROVIDER_ERROR",
+				`Brevo returned ${res.status}`,
+				{
+					hint: "Inspect `context.upstreamStatus` to decide retry eligibility. `context.retryAfter` (when set) carries the provider's backoff hint in seconds.",
+					context: ctx,
+				},
+			);
+		}
+		// Success: Brevo returns `{ messageId: "<id>" }`.
+		try {
+			const parsed = (await res.json()) as { messageId?: string };
+			if (typeof parsed.messageId === "string" && parsed.messageId.length > 0) {
+				return { providerId: parsed.messageId };
+			}
+		} catch {
+			// Empty / non-JSON body — fall back to generated id.
+		}
+		return undefined;
+	}
+}
+
+/**
+ * Split a possibly-formatted address (`"Name" <addr>` / `Name <addr>` / bare
+ * `addr`) into Brevo's `{ email, name? }` contact shape.
+ */
+function parseContact(input: string): BrevoContact {
+	const s = stripCrlf(input).trim();
+	const match = s.match(/^(.*)<([^>]+)>\s*$/);
+	if (match) {
+		const email = match[2].trim();
+		const name = match[1].trim().replace(/^"|"$/g, "").trim();
+		return name ? { email, name } : { email };
+	}
+	return { email: s };
+}
+
+registerTransport("brevo", (config) => new BrevoTransport(config));

package/src/transports/MailgunTransport.ts

@@ -128,7 +128,9 @@ export class MailgunTransport implements MailTransport {
 		if (message.html) data.html = message.html;
 		if (message.replyTo) data["h:Reply-To"] = stripCrlf(message.replyTo);
 		for (const [k, v] of Object.entries(message.headers)) {
-			data[`h:${stripCrlf(k)}`] = stripCrlf(v);
+			data[`h:${stripCrlf(k)}`] = Array.isArray(v)
+				? v.map(stripCrlf).join(", ")
+				: stripCrlf(v);
 		}
 		if (message.attachments.length > 0) {
 			data.attachment = message.attachments.map((att) => {

package/src/transports/ResendTransport.ts

@@ -1,11 +1,11 @@
 import { Buffer } from "node:buffer";
-import { RoverError } from "../RoverError.js";
 import {
 	type MailMessage,
 	type MailSendOutcome,
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { RoverError } from "../RoverError.js";
 import { wrapFetchNetworkError } from "./fetchError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
@@ -92,7 +92,9 @@ export class ResendTransport implements MailTransport {
 		if (customHeaders.length > 0) {
 			body.headers = {};
 			for (const [k, v] of customHeaders) {
-				body.headers[stripCrlf(k)] = stripCrlf(v);
+				body.headers[stripCrlf(k)] = Array.isArray(v)
+					? v.map(stripCrlf).join(", ")
+					: stripCrlf(v);
 			}
 		}
 

package/src/transports/SendGridTransport.ts

@@ -1,4 +1,3 @@
-import { RoverError } from "../RoverError.js";
 import sgMail, {
 	type MailDataRequired,
 	type MailService,
@@ -9,6 +8,7 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { RoverError } from "../RoverError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
 const normalizeConfig = (v: string): string => stripCrlf(v).trim();
@@ -92,7 +92,7 @@ export class SendGridTransport implements MailTransport {
 						headers: Object.fromEntries(
 							Object.entries(message.headers).map(([k, v]) => [
 								stripCrlf(k),
-								stripCrlf(v),
+								Array.isArray(v) ? v.map(stripCrlf).join(", ") : stripCrlf(v),
 							]),
 						),
 					}

package/src/transports/SesTransport.ts

@@ -281,7 +281,9 @@ function buildRawMime(message: MailMessage): string {
 	]);
 	for (const [k, v] of Object.entries(message.headers)) {
 		if (reserved.has(k.toLowerCase())) continue;
-		parts.push(`${stripCrlf(k)}: ${encodeHeaderWord(v)}`);
+		parts.push(
+			`${stripCrlf(k)}: ${encodeHeaderWord(Array.isArray(v) ? v.join(", ") : v)}`,
+		);
 	}
 
 	const hasAttachments = message.attachments.length > 0;