@c9up/rover 0.1.8 → 0.1.10

package/src/config.ts

@@ -1,7 +1,53 @@
 import type { MailConfig } from "./Mail.js";
+import type { RetryConfig } from "./retry.js";
 
 export function defineConfig(config: MailConfig): MailConfig {
 	return config;
 }
 
+/** One mailer's settings — the transport name plus whatever it reads. */
+export interface TransportDescriptor {
+	transport: string;
+	retry?: RetryConfig;
+	[key: string]: unknown;
+}
+
+type Options = Record<string, unknown> & { retry?: RetryConfig };
+
+function describe(transport: string) {
+	return (config: Options = {}): TransportDescriptor => ({
+		...config,
+		transport,
+	});
+}
+
+/**
+ * Mailer descriptors for `defineConfig`, matching the AdonisJS call site:
+ *
+ *   defineConfig({
+ *     default: 'smtp',
+ *     from: 'noreply@acme.com',
+ *     mailers: { smtp: transports.smtp({ host: env.get('SMTP_HOST') }) },
+ *   })
+ *
+ * Named deviation: upstream returns a config PROVIDER that lazily imports the
+ * transport. Rover returns the plain descriptor its config can persist, and the
+ * transport registers itself on import.
+ *
+ * Postmark has no helper here on purpose: rover has no Postmark transport, so a
+ * migrated config naming it fails to COMPILE — which says so plainly — instead
+ * of throwing at boot.
+ */
+export const transports = {
+	smtp: describe("smtp"),
+	ses: describe("ses"),
+	mailgun: describe("mailgun"),
+	sparkpost: describe("sparkpost"),
+	resend: describe("resend"),
+	brevo: describe("brevo"),
+	sendgrid: describe("sendgrid"),
+	/** Writes to the logger instead of sending — the local-development mailer. */
+	log: describe("log"),
+};
+
 export type { MailConfig };

package/src/format.ts

@@ -4,11 +4,43 @@
  * the BaseMail ↔ MessageBuilder value cycle.
  */
 
+import { RoverError } from "./RoverError.js";
+
+/** CR, LF and NUL — the characters that end a header line or a C string. */
+const HEADER_BREAKERS = /[\r\n\0]/;
+
 /**
  * Format a recipient address with an optional display name into the
  * `"Name" <address>` form (RFC 5322 quoted display name). A bare address —
  * or an empty/whitespace-only name — is returned unchanged.
+ *
+ * The display name is a QUOTED string, so a `"` inside it would close the quote
+ * early: a name of `x" <evil@example.com>, "y` would otherwise forge a second
+ * recipient. Backslash and quote are escaped, which is what a quoted-string
+ * allows.
+ *
+ * A line break cannot be escaped in a header — it ENDS the header — so a value
+ * carrying CR, LF or NUL is rejected rather than mangled. Accepting it is how a
+ * contact form turns into an open relay: one `\r\nBcc:` and the message goes
+ * wherever the attacker asked.
  */
 export function formatAddress(address: string, name?: string): string {
-	return name !== undefined && name !== "" ? `"${name}" <${address}>` : address;
+	assertHeaderSafe(address, "address");
+	if (name === undefined || name === "") return address;
+	assertHeaderSafe(name, "name");
+	// Escape the escape character first, or a trailing backslash would swallow
+	// the closing quote.
+	const quoted = name.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+	return `"${quoted}" <${address}>`;
+}
+
+function assertHeaderSafe(value: string, what: string): void {
+	if (!HEADER_BREAKERS.test(value)) return;
+	throw new RoverError(
+		"MAIL_HEADER_INJECTION",
+		`The ${what} contains a line break or NUL, which cannot appear in a mail header.`,
+		{
+			hint: "Strip CR/LF/NUL from user-supplied names and addresses before building the message.",
+		},
+	);
 }

package/src/index.ts

@@ -1,10 +1,21 @@
+/**
+ * Every bundled transport is imported for its REGISTRATION side effect.
+ *
+ * Each module calls `registerTransport(name, factory)` when it loads, so a
+ * config naming `ses` or `mailgun` only worked if the app had imported that
+ * module itself — which nothing told it to do. `defineConfig` offers a helper
+ * for each of them, so each has to be there when the config is read.
+ */
+
 export type { MailAddress } from "./BaseMail.js";
 export { BaseMail } from "./BaseMail.js";
-export { defineConfig } from "./config.js";
+export type { TransportDescriptor } from "./config.js";
+export { defineConfig, transports } from "./config.js";
 export type {
 	EmitterLike,
 	MailAttachment,
 	MailConfig,
+	MailEventBase,
 	MailFailedEvent,
 	MailHooks,
 	MailMessage,
@@ -15,6 +26,7 @@ export type {
 	MailSentEvent,
 	MailTransport,
 	MailTransportFactory,
+	MessageBodyTemplates,
 } from "./Mail.js";
 export {
 	LogTransport,
@@ -24,7 +36,18 @@ export {
 	registerTransport,
 	SmtpTransport,
 } from "./Mail.js";
-export type { Recipient, RecipientObject } from "./MessageBuilder.js";
+export type {
+	AttachmentOptions,
+	CalendarEvent,
+	CalendarEventMethod,
+	CalendarEventOptions,
+	ListHeader,
+	MailEnvelope,
+	PreparedHeader,
+	Recipient,
+	RecipientObject,
+} from "./MessageBuilder.js";
+export { attachmentsFor, headerValue } from "./MessageBuilder.js";
 export { RoverError } from "./RoverError.js";
 export { default as RoverProvider } from "./RoverProvider.js";
 export {
@@ -32,3 +55,9 @@ export {
 	isRetryableError,
 	type RetryConfig,
 } from "./retry.js";
+export { BrevoTransport } from "./transports/BrevoTransport.js";
+export { MailgunTransport } from "./transports/MailgunTransport.js";
+export { ResendTransport } from "./transports/ResendTransport.js";
+export { SendGridTransport } from "./transports/SendGridTransport.js";
+export { SesTransport } from "./transports/SesTransport.js";
+export { SparkPostTransport } from "./transports/SparkPostTransport.js";

package/src/testing/FakeMail.ts

@@ -1,3 +1,4 @@
+import type { Plugin } from "@c9up/helix";
 import { BaseMail } from "../BaseMail.js";
 import type { MailMessage, MailSendOutcome, MailTransport } from "../Mail.js";
 
@@ -311,3 +312,48 @@ function describeCaptured(captured: Capture[]): string {
 	);
 	return `Captured (${captured.length}):\n${lines.join("\n")}`;
 }
+
+/** A mailer that can enter/exit fake mode — structurally the rover `Mail` manager. */
+export interface FakeableMailer {
+	/** Activate fake mode and return the capturing {@link FakeMail}. */
+	fake(): FakeMail;
+	/** Exit fake mode. */
+	restore(): void;
+}
+
+/**
+ * `mailFake()` — a helix plugin (AdonisJS `mail.fake()` parity) that injects a
+ * fresh {@link FakeMail} on the test context as `ctx.mail`, PER TEST, and
+ * auto-restores the mailer afterwards via `ctx.cleanup`:
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from "@c9up/helix";
+ *   import { mailFake } from "@c9up/rover/testing";
+ *   await configure({ plugins: [mailFake(mailer)] });
+ *
+ *   test("sends welcome", async ({ mail }) => {
+ *     await sendWelcome();
+ *     mail.assertSent((m) => m.hasTo("user@example.com"));
+ *   });
+ *
+ * The fake is activated lazily on first `ctx.mail` access (inside the test
+ * frame) and torn down when that test ends — so capture never leaks between
+ * tests. Uses the manager's own `fake()`/`restore()` (the Adonis pattern).
+ */
+export function mailFake(mailer: FakeableMailer): Plugin {
+	return (api) => {
+		api.context.getter("mail", (ctx) => {
+			const fake = mailer.fake();
+			ctx.cleanup(() => mailer.restore());
+			return fake;
+		});
+	};
+}
+
+// Typing side of the plugin — importing `@c9up/rover/testing` augments the
+// helix test context with `mail` (the Japa pattern).
+declare module "@c9up/helix" {
+	interface TestContext {
+		mail: FakeMail;
+	}
+}

package/src/transports/BrevoTransport.ts

@@ -5,8 +5,9 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
-import { wrapFetchNetworkError } from "./fetchError.js";
+import { fetchWithTimeout, wrapFetchNetworkError } from "./fetchError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
 const normalizeConfig = (v: string): string => stripCrlf(v).trim();
@@ -98,14 +99,15 @@ export class BrevoTransport implements MailTransport {
 		const customHeaders = Object.entries(message.headers);
 		if (customHeaders.length > 0) {
 			body.headers = {};
-			for (const [k, v] of customHeaders) {
+			for (const [k, raw] of customHeaders) {
+				const v = headerValue(raw);
 				body.headers[stripCrlf(k)] = Array.isArray(v)
 					? v.map(stripCrlf).join(", ")
 					: stripCrlf(v);
 			}
 		}
-		if (message.attachments.length > 0) {
-			body.attachment = message.attachments.map((att) => ({
+		if (attachmentsFor(message).length > 0) {
+			body.attachment = attachmentsFor(message).map((att) => ({
 				name: stripCrlf(att.filename),
 				content: Buffer.from(att.content as Buffer | string).toString("base64"),
 			}));
@@ -113,7 +115,7 @@ export class BrevoTransport implements MailTransport {
 
 		let res: Response;
 		try {
-			res = await fetch(`${this.#baseUrl}/v3/smtp/email`, {
+			res = await fetchWithTimeout("Brevo", `${this.#baseUrl}/v3/smtp/email`, {
 				method: "POST",
 				headers: {
 					"api-key": this.#apiKey,

package/src/transports/MailgunTransport.ts

@@ -7,6 +7,7 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
@@ -127,13 +128,14 @@ export class MailgunTransport implements MailTransport {
 		if (message.text) data.text = message.text;
 		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)) {
+		for (const [k, raw] of Object.entries(message.headers)) {
+			const v = headerValue(raw);
 			data[`h:${stripCrlf(k)}`] = Array.isArray(v)
 				? v.map(stripCrlf).join(", ")
 				: stripCrlf(v);
 		}
-		if (message.attachments.length > 0) {
-			data.attachment = message.attachments.map((att) => {
+		if (attachmentsFor(message).length > 0) {
+			data.attachment = attachmentsFor(message).map((att) => {
 				const entry: { filename: string; data: Buffer; contentType?: string } =
 					{
 						filename: stripCrlf(att.filename),

package/src/transports/ResendTransport.ts

@@ -5,8 +5,9 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
-import { wrapFetchNetworkError } from "./fetchError.js";
+import { fetchWithTimeout, wrapFetchNetworkError } from "./fetchError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
 const normalizeConfig = (v: string): string => stripCrlf(v).trim();
@@ -76,8 +77,8 @@ export class ResendTransport implements MailTransport {
 		if (message.replyTo) body.reply_to = stripCrlf(message.replyTo);
 		if (message.html) body.html = message.html;
 		if (message.text) body.text = message.text;
-		if (message.attachments.length > 0) {
-			body.attachments = message.attachments.map((att) => {
+		if (attachmentsFor(message).length > 0) {
+			body.attachments = attachmentsFor(message).map((att) => {
 				const buf = Buffer.from(att.content as Buffer | string);
 				return {
 					filename: stripCrlf(att.filename),
@@ -91,7 +92,8 @@ export class ResendTransport implements MailTransport {
 		const customHeaders = Object.entries(message.headers);
 		if (customHeaders.length > 0) {
 			body.headers = {};
-			for (const [k, v] of customHeaders) {
+			for (const [k, raw] of customHeaders) {
+				const v = headerValue(raw);
 				body.headers[stripCrlf(k)] = Array.isArray(v)
 					? v.map(stripCrlf).join(", ")
 					: stripCrlf(v);
@@ -104,7 +106,7 @@ export class ResendTransport implements MailTransport {
 		// shims, `.cause.code` for Node's built-in undici).
 		let res: Response;
 		try {
-			res = await fetch("https://api.resend.com/emails", {
+			res = await fetchWithTimeout("Resend", "https://api.resend.com/emails", {
 				method: "POST",
 				headers: {
 					Authorization: `Bearer ${this.#apiKey}`,

package/src/transports/SendGridTransport.ts

@@ -8,6 +8,7 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
@@ -90,16 +91,19 @@ export class SendGridTransport implements MailTransport {
 			...(Object.keys(message.headers).length
 				? {
 						headers: Object.fromEntries(
-							Object.entries(message.headers).map(([k, v]) => [
-								stripCrlf(k),
-								Array.isArray(v) ? v.map(stripCrlf).join(", ") : stripCrlf(v),
-							]),
+							Object.entries(message.headers).map(([k, raw]) => {
+								const v = headerValue(raw);
+								return [
+									stripCrlf(k),
+									Array.isArray(v) ? v.map(stripCrlf).join(", ") : stripCrlf(v),
+								];
+							}),
 						),
 					}
 				: {}),
-			...(message.attachments.length
+			...(attachmentsFor(message).length
 				? {
-						attachments: message.attachments.map((att) => {
+						attachments: attachmentsFor(message).map((att) => {
 							const entry: {
 								filename: string;
 								content: string;

package/src/transports/SesTransport.ts

@@ -7,8 +7,9 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
-import { wrapFetchNetworkError } from "./fetchError.js";
+import { fetchWithTimeout, wrapFetchNetworkError } from "./fetchError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
 const normalizeConfig = (v: string): string => stripCrlf(v).trim();
@@ -101,7 +102,8 @@ export class SesTransport implements MailTransport {
 		// compose the MIME ourselves), so flip to raw whenever the message
 		// carries headers, even without attachments.
 		const useRaw =
-			message.attachments.length > 0 || Object.keys(message.headers).length > 0;
+			attachmentsFor(message).length > 0 ||
+			Object.keys(message.headers).length > 0;
 		const form = useRaw
 			? buildRawEmailForm(message)
 			: buildSendEmailForm(message);
@@ -112,7 +114,7 @@ export class SesTransport implements MailTransport {
 		// why undici's `cause.code` matters for retry classification.
 		let res: Response;
 		try {
-			res = await fetch(url, {
+			res = await fetchWithTimeout("SES", url, {
 				method: "POST",
 				headers,
 				body: form,
@@ -279,14 +281,21 @@ function buildRawMime(message: MailMessage): string {
 		"content-transfer-encoding",
 		"content-disposition",
 	]);
-	for (const [k, v] of Object.entries(message.headers)) {
+	for (const [k, raw] of Object.entries(message.headers)) {
 		if (reserved.has(k.toLowerCase())) continue;
+		// A PREPARED header is the one case the flag actually decides: this
+		// builds raw MIME, and re-encoding a value that is already exactly what
+		// must go on the wire — a signature, a pre-encoded id — corrupts it.
+		if (!Array.isArray(raw) && typeof raw !== "string") {
+			parts.push(`${stripCrlf(k)}: ${stripCrlf(raw.value)}`);
+			continue;
+		}
 		parts.push(
-			`${stripCrlf(k)}: ${encodeHeaderWord(Array.isArray(v) ? v.join(", ") : v)}`,
+			`${stripCrlf(k)}: ${encodeHeaderWord(Array.isArray(raw) ? raw.join(", ") : raw)}`,
 		);
 	}
 
-	const hasAttachments = message.attachments.length > 0;
+	const hasAttachments = attachmentsFor(message).length > 0;
 	const mixedBoundary = freshBoundary();
 
 	if (hasAttachments) {
@@ -294,7 +303,7 @@ function buildRawMime(message: MailMessage): string {
 		parts.push("");
 		parts.push(`--${mixedBoundary}`);
 		appendBodyBlock(parts, message);
-		for (const att of message.attachments) {
+		for (const att of attachmentsFor(message)) {
 			appendAttachmentPart(parts, mixedBoundary, att);
 		}
 		parts.push(`--${mixedBoundary}--`);

package/src/transports/SparkPostTransport.ts

@@ -5,8 +5,9 @@ import {
 	type MailTransport,
 	registerTransport,
 } from "../Mail.js";
+import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.js";
-import { wrapFetchNetworkError } from "./fetchError.js";
+import { fetchWithTimeout, wrapFetchNetworkError } from "./fetchError.js";
 
 const stripCrlf = (v: string): string => v.replace(/[\r\n]/g, "");
 const normalizeConfig = (v: string): string => stripCrlf(v).trim();
@@ -102,15 +103,16 @@ export class SparkPostTransport implements MailTransport {
 		if (message.text) body.content.text = message.text;
 		if (message.replyTo) body.content.reply_to = stripCrlf(message.replyTo);
 		const headers: Record<string, string> = {};
-		for (const [k, v] of Object.entries(message.headers)) {
+		for (const [k, raw] of Object.entries(message.headers)) {
+			const v = headerValue(raw);
 			headers[stripCrlf(k)] = Array.isArray(v)
 				? v.map(stripCrlf).join(", ")
 				: stripCrlf(v);
 		}
 		if (message.cc.length) headers.CC = message.cc.map(stripCrlf).join(", ");
 		if (Object.keys(headers).length > 0) body.content.headers = headers;
-		if (message.attachments.length > 0) {
-			body.content.attachments = message.attachments.map((att) => ({
+		if (attachmentsFor(message).length > 0) {
+			body.content.attachments = attachmentsFor(message).map((att) => ({
 				name: stripCrlf(att.filename),
 				type: att.contentType
 					? stripCrlf(att.contentType)
@@ -121,14 +123,18 @@ export class SparkPostTransport implements MailTransport {
 
 		let res: Response;
 		try {
-			res = await fetch(`${this.#baseUrl}/api/v1/transmissions`, {
-				method: "POST",
-				headers: {
-					Authorization: this.#apiKey,
-					"Content-Type": "application/json",
+			res = await fetchWithTimeout(
+				"SparkPost",
+				`${this.#baseUrl}/api/v1/transmissions`,
+				{
+					method: "POST",
+					headers: {
+						Authorization: this.#apiKey,
+						"Content-Type": "application/json",
+					},
+					body: JSON.stringify(body),
 				},
-				body: JSON.stringify(body),
-			});
+			);
 		} catch (err) {
 			throw wrapFetchNetworkError("sparkpost", err);
 		}

package/src/transports/fetchError.ts

@@ -40,3 +40,42 @@ export function wrapFetchNetworkError(
 		},
 	);
 }
+
+/** Default ceiling on one provider request. */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * `fetch` with a deadline.
+ *
+ * Without one, a stalled provider connection never settles: the send hangs,
+ * the queue worker holding it hangs with it, and enough of them stop mail going
+ * out at all — with no error to explain the silence. A timeout surfaces as the
+ * same `MAIL_PROVIDER_ERROR` shape the retry classifier already understands, so
+ * it is retried like any other transient network failure.
+ */
+export async function fetchWithTimeout(
+	provider: string,
+	url: string,
+	init: RequestInit = {},
+	timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<Response> {
+	if (timeoutMs <= 0) return fetch(url, init);
+	try {
+		return await fetch(url, {
+			...init,
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+	} catch (err) {
+		if (err instanceof Error && err.name === "TimeoutError") {
+			throw new RoverError(
+				"MAIL_PROVIDER_ERROR",
+				`${provider} did not answer within ${timeoutMs}ms.`,
+				{
+					context: { provider, upstreamStatus: "0", networkCode: "ETIMEDOUT" },
+					hint: "Raise `requestTimeoutMs` for large attachments, or check connectivity to the provider.",
+				},
+			);
+		}
+		throw wrapFetchNetworkError(provider, err);
+	}
+}