@c9up/rover 0.1.3

package/src/transports/MailgunTransport.ts

@@ -0,0 +1,204 @@
+import { RoverError } from "../RoverError.js";
+import formData from "form-data";
+// mailgun.js is UMD-bundled; the class lives on `.default` under NodeNext.
+import MailgunModule from "mailgun.js";
+import {
+	type MailMessage,
+	type MailSendOutcome,
+	type MailTransport,
+	registerTransport,
+} from "../Mail.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]`;
+
+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]");
+
+/** Minimal mailgun.js client surface — matches the subset we need. */
+interface MailgunClientLike {
+	messages: {
+		create(
+			domain: string,
+			data: Record<string, unknown>,
+		): Promise<{ id?: string; message?: string; status?: number }>;
+	};
+}
+
+export class MailgunTransport implements MailTransport {
+	#client: MailgunClientLike;
+	#domain: string;
+
+	constructor(config: Record<string, unknown>) {
+		const apiKey =
+			typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
+		const domain =
+			typeof config.domain === "string" ? normalizeConfig(config.domain) : "";
+		if (!apiKey || !domain) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"Mailgun transport requires apiKey and domain",
+				{ hint: "Set { apiKey, domain } in your mail config." },
+			);
+		}
+		this.#domain = domain;
+
+		// Region: reject non-string when *defined* (wrong type signals a config
+		// bug — defaulting to "us" under those conditions is a compliance risk).
+		if (config.region !== undefined && typeof config.region !== "string") {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				`Mailgun region must be a string ("us" or "eu"), got ${typeof config.region}`,
+				{ hint: "Set config.region explicitly as 'us' or 'eu'." },
+			);
+		}
+		const rawRegion =
+			typeof config.region === "string"
+				? normalizeConfig(config.region).toLowerCase()
+				: "us";
+		if (rawRegion !== "us" && rawRegion !== "eu") {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				`Mailgun region must be "us" or "eu", got "${rawRegion}"`,
+				{
+					hint: "Use { region: 'us' } or { region: 'eu' }. A typo silently routing EU traffic to US infrastructure is a compliance risk.",
+				},
+			);
+		}
+		const url =
+			rawRegion === "eu"
+				? "https://api.eu.mailgun.net"
+				: "https://api.mailgun.net";
+
+		// Dependency injection for tests: `_client` wins over real SDK. Guarded
+		// against non-object and non-shape inputs so a typo'd config can't
+		// silently bypass the real client.
+		const injected = config._client;
+		if (
+			injected &&
+			typeof injected === "object" &&
+			"messages" in (injected as object) &&
+			typeof (injected as MailgunClientLike).messages?.create === "function"
+		) {
+			this.#client = injected as MailgunClientLike;
+		} else {
+			// mailgun.js ships a UMD-style default export; the class constructor
+			// lives on `.default` in the typings (`static get default`).
+			const MailgunCtor = MailgunModule.default;
+			const mailgun = new MailgunCtor(formData);
+			this.#client = mailgun.client({ username: "api", key: apiKey, url });
+		}
+	}
+
+	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." },
+			);
+		}
+
+		// CRLF stripping is applied at the wire boundary regardless of SDK
+		// promises — defence-in-depth. Anti-pattern from spec Dev Notes:
+		// "never skip CRLF sanitisation because the provider will handle it".
+		const data: Record<string, unknown> = {
+			from: stripCrlf(message.from),
+			to: message.to.map(stripCrlf),
+			subject: stripCrlf(message.subject),
+		};
+		if (message.cc.length) data.cc = message.cc.map(stripCrlf);
+		if (message.bcc.length) data.bcc = message.bcc.map(stripCrlf);
+		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)) {
+			data[`h:${stripCrlf(k)}`] = stripCrlf(v);
+		}
+		if (message.attachments.length > 0) {
+			data.attachment = message.attachments.map((att) => {
+				const entry: { filename: string; data: Buffer; contentType?: string } =
+					{
+						filename: stripCrlf(att.filename),
+						data: Buffer.from(att.content as Buffer | string),
+					};
+				if (att.contentType) {
+					entry.contentType = stripCrlf(att.contentType);
+				}
+				return entry;
+			});
+		}
+
+		try {
+			const res = await this.#client.messages.create(this.#domain, data);
+			if (res.id) return { providerId: res.id };
+			return undefined;
+		} catch (err) {
+			throw wrapMailgunError(err);
+		}
+	}
+}
+
+/**
+ * mailgun.js's own error shape is `{ status, details | message, ... }`.
+ * Map it to our uniform `MAIL_PROVIDER_ERROR` so retry + observability
+ * consumers don't need to branch on provider.
+ *
+ * Bare `Error` (no `status`) — typical for network/ECONNRESET failures from
+ * mailgun.js — surface the original errno (`code`) in context so the retry
+ * predicate can still classify it as transient.
+ */
+function wrapMailgunError(err: unknown): RoverError {
+	if (err instanceof RoverError) return err;
+	const anyErr = err as {
+		status?: unknown;
+		details?: string;
+		message?: string;
+		code?: string;
+		headers?: Record<string, string | string[]>;
+	};
+	// Coerce string-typed status ("401") into number — mailgun.js is
+	// inconsistent across versions.
+	const statusNum = Number(anyErr.status);
+	const status = Number.isFinite(statusNum) ? statusNum : 0;
+	const providerMessage = redactSecrets(
+		capMessage(anyErr.details ?? anyErr.message ?? "unknown"),
+	);
+	const ctx: Record<string, string> = {
+		provider: "mailgun",
+		upstreamStatus: String(status),
+		providerMessage,
+	};
+	if (typeof anyErr.code === "string") {
+		ctx.networkCode = anyErr.code;
+	}
+	// Retry-After may arrive either as a header (`retry-after`) or as a JSON
+	// body field — pass both upstream so `computeBackoffMs` can honour it.
+	const retryAfterHeader = anyErr.headers?.["retry-after"];
+	if (retryAfterHeader) {
+		ctx.retryAfter = Array.isArray(retryAfterHeader)
+			? (retryAfterHeader[0] ?? "")
+			: retryAfterHeader;
+	}
+	return new RoverError(
+		"MAIL_PROVIDER_ERROR",
+		`Mailgun returned ${status || "unknown"}`,
+		{
+			hint: "Inspect `context.upstreamStatus` (HTTP) or `context.networkCode` (ECONNRESET/etc.) to decide retry eligibility.",
+			context: ctx,
+		},
+	);
+}
+
+registerTransport("mailgun", (config) => new MailgunTransport(config));

package/src/transports/ResendTransport.ts

@@ -0,0 +1,147 @@
+import { Buffer } from "node:buffer";
+import { RoverError } from "../RoverError.js";
+import {
+	type MailMessage,
+	type MailSendOutcome,
+	type MailTransport,
+	registerTransport,
+} from "../Mail.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 ResendBody {
+	from: string;
+	to: string[];
+	cc?: string[];
+	bcc?: string[];
+	reply_to?: string;
+	subject: string;
+	html?: string;
+	text?: string;
+	attachments?: Array<{
+		filename: string;
+		content: string;
+		content_type?: string;
+	}>;
+	headers?: Record<string, string>;
+}
+
+export class ResendTransport implements MailTransport {
+	#apiKey: string;
+
+	constructor(config: Record<string, unknown>) {
+		const apiKey =
+			typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
+		if (!apiKey) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"Resend transport requires apiKey",
+				{ hint: "Set { apiKey } in your mail config." },
+			);
+		}
+		this.#apiKey = apiKey;
+	}
+
+	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: ResendBody = {
+			from: stripCrlf(message.from),
+			to: message.to.map(stripCrlf),
+			subject: stripCrlf(message.subject),
+		};
+		if (message.cc.length) body.cc = message.cc.map(stripCrlf);
+		if (message.bcc.length) body.bcc = message.bcc.map(stripCrlf);
+		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) => {
+				const buf = Buffer.from(att.content as Buffer | string);
+				return {
+					filename: stripCrlf(att.filename),
+					content: buf.toString("base64"),
+					content_type: att.contentType
+						? stripCrlf(att.contentType)
+						: undefined,
+				};
+			});
+		}
+		const customHeaders = Object.entries(message.headers);
+		if (customHeaders.length > 0) {
+			body.headers = {};
+			for (const [k, v] of customHeaders) {
+				body.headers[stripCrlf(k)] = stripCrlf(v);
+			}
+		}
+
+		// fetch() rejections (DNS / TCP / TLS / socket reset) bypass the
+		// !res.ok branch entirely. Wrap them so retry classification can
+		// pick up the underlying errno (top-level `.code` for legacy
+		// shims, `.cause.code` for Node's built-in undici).
+		let res: Response;
+		try {
+			res = await fetch("https://api.resend.com/emails", {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${this.#apiKey}`,
+					"Content-Type": "application/json",
+				},
+				body: JSON.stringify(body),
+			});
+		} catch (err) {
+			throw wrapFetchNetworkError("resend", 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: "resend",
+				upstreamStatus: String(res.status),
+				providerMessage,
+			};
+			if (retryAfter) ctx.retryAfter = retryAfter;
+			throw new RoverError(
+				"MAIL_PROVIDER_ERROR",
+				`Resend 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: Resend returns `{ id: "<uuid>" }` per API docs.
+		try {
+			const body = (await res.json()) as { id?: string };
+			if (typeof body.id === "string" && body.id.length > 0) {
+				return { providerId: body.id };
+			}
+		} catch {
+			// Empty body or non-JSON — fall back to generated id.
+		}
+		return;
+	}
+}
+
+registerTransport("resend", (config) => new ResendTransport(config));

package/src/transports/SendGridTransport.ts

@@ -0,0 +1,246 @@
+import { RoverError } from "../RoverError.js";
+import sgMail, {
+	type MailDataRequired,
+	type MailService,
+} from "@sendgrid/mail";
+import {
+	type MailMessage,
+	type MailSendOutcome,
+	type MailTransport,
+	registerTransport,
+} from "../Mail.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]`;
+
+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]");
+
+/**
+ * Minimal slice of the SendGrid client we depend on. A per-transport client
+ * instance is created in the constructor so concurrent transports with
+ * different API keys cannot race each other — the original module-level
+ * `sgMail.setApiKey()` would have been a multi-tenant foot-gun.
+ */
+interface SendGridClientLike {
+	setApiKey(apiKey: string): void;
+	send(
+		data: MailDataRequired,
+	): Promise<
+		[
+			{ statusCode: number; headers: Record<string, string | string[]> },
+			unknown,
+		]
+	>;
+}
+
+export class SendGridTransport implements MailTransport {
+	#client: SendGridClientLike;
+
+	constructor(config: Record<string, unknown>) {
+		const apiKey =
+			typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
+		if (!apiKey) {
+			throw new RoverError(
+				"MAIL_PROVIDER_CONFIG",
+				"SendGrid transport requires apiKey",
+				{ hint: "Set { apiKey } in your mail config." },
+			);
+		}
+
+		// Dependency injection for tests — stronger guard than the old version
+		// (require both `send` AND `setApiKey` to pass through).
+		const injected = config._client;
+		if (
+			injected &&
+			typeof injected === "object" &&
+			typeof (injected as SendGridClientLike).send === "function" &&
+			typeof (injected as SendGridClientLike).setApiKey === "function"
+		) {
+			this.#client = injected as SendGridClientLike;
+		} else {
+			// Per-instance MailService (not the shared `sgMail` singleton) so
+			// `setApiKey` can't race across multiple transports.
+			this.#client = new (resolveMailServiceCtor(sgMail))();
+		}
+		this.#client.setApiKey(apiKey);
+	}
+
+	async send(message: MailMessage): Promise<MailSendOutcome> {
+		assertHasRecipients(message);
+		const content = buildSendGridContent(message);
+
+		// CRLF stripping at the wire boundary (defence-in-depth, matches the
+		// Dev Notes anti-pattern: never trust the SDK to handle it).
+		const data: MailDataRequired = {
+			from: stripCrlf(message.from),
+			to: message.to.map(stripCrlf),
+			subject: stripCrlf(message.subject),
+			content,
+			...(message.cc.length ? { cc: message.cc.map(stripCrlf) } : {}),
+			...(message.bcc.length ? { bcc: message.bcc.map(stripCrlf) } : {}),
+			...(message.replyTo ? { replyTo: stripCrlf(message.replyTo) } : {}),
+			...(Object.keys(message.headers).length
+				? {
+						headers: Object.fromEntries(
+							Object.entries(message.headers).map(([k, v]) => [
+								stripCrlf(k),
+								stripCrlf(v),
+							]),
+						),
+					}
+				: {}),
+			...(message.attachments.length
+				? {
+						attachments: message.attachments.map((att) => {
+							const entry: {
+								filename: string;
+								content: string;
+								type?: string;
+								disposition: "attachment";
+							} = {
+								filename: stripCrlf(att.filename),
+								content: Buffer.from(att.content as Buffer | string).toString(
+									"base64",
+								),
+								disposition: "attachment" as const,
+							};
+							if (att.contentType) entry.type = stripCrlf(att.contentType);
+							return entry;
+						}),
+					}
+				: {}),
+		};
+
+		try {
+			const result = await this.#client.send(data);
+			// Guard against non-standard SDK responses: `[]`, `[undefined]`, etc.
+			const response = Array.isArray(result) ? result[0] : undefined;
+			const msgId = response?.headers?.["x-message-id"];
+			const idStr = Array.isArray(msgId) ? msgId[0] : msgId;
+			if (idStr && typeof idStr === "string" && idStr.length > 0) {
+				return { providerId: idStr };
+			}
+			return undefined;
+		} catch (err) {
+			throw wrapSendGridError(err);
+		}
+	}
+}
+
+type SendGridContent = { type: string; value: string };
+
+function assertHasRecipients(message: MailMessage): void {
+	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." },
+		);
+	}
+}
+
+/**
+ * Build the SendGrid v3 `content[]`: text/plain when text is set, text/html when
+ * html is set, always at least one entry (SendGrid rejects empty content). The
+ * non-empty tuple type lets the SDK's MailDataRequired see `content[0]` exists.
+ */
+function buildSendGridContent(
+	message: MailMessage,
+): [SendGridContent, ...SendGridContent[]] {
+	const first: SendGridContent = message.text
+		? { type: "text/plain", value: message.text }
+		: message.html
+			? { type: "text/html", value: message.html }
+			: { type: "text/plain", value: "" };
+	const rest: SendGridContent[] = [];
+	if (message.text && message.html) {
+		rest.push({ type: "text/html", value: message.html });
+	}
+	return [first, ...rest];
+}
+
+function wrapSendGridError(err: unknown): RoverError {
+	if (err instanceof RoverError) return err;
+	// @sendgrid/mail throws `{ code, message, response: { body, headers, statusCode } }`
+	const anyErr = err as {
+		code?: number | string;
+		message?: string;
+		response?: {
+			statusCode?: number;
+			body?: unknown;
+			headers?: Record<string, string>;
+		};
+	};
+	const statusFromResponse = anyErr.response?.statusCode;
+	const statusFromCode = Number(anyErr.code);
+	const status = Number.isFinite(statusFromResponse as number)
+		? (statusFromResponse as number)
+		: Number.isFinite(statusFromCode)
+			? statusFromCode
+			: 0;
+	const body = anyErr.response?.body;
+	const providerMessage = redactSecrets(
+		capMessage(
+			typeof body === "string"
+				? body
+				: body !== undefined
+					? JSON.stringify(body)
+					: (anyErr.message ?? "unknown"),
+		),
+	);
+	const ctx: Record<string, string> = {
+		provider: "sendgrid",
+		upstreamStatus: String(status),
+		providerMessage,
+	};
+	if (typeof anyErr.code === "string") {
+		ctx.networkCode = anyErr.code;
+	}
+	const retryAfter = anyErr.response?.headers?.["retry-after"];
+	if (retryAfter) ctx.retryAfter = retryAfter;
+	return new RoverError(
+		"MAIL_PROVIDER_ERROR",
+		`SendGrid returned ${status || "unknown"}`,
+		{
+			hint: "Inspect `context.upstreamStatus` (HTTP) or `context.networkCode` (ECONNRESET/etc.) to decide retry eligibility. `context.retryAfter` (when set) carries the provider's backoff hint in seconds.",
+			context: ctx,
+		},
+	);
+}
+
+/**
+ * Type-guard resolver for the `MailService` constructor attached to the
+ * module's default export at runtime. The cerebrum forbids `as unknown as T`;
+ * here we receive `sgMail` through a parameter typed `unknown`, narrow with
+ * runtime `typeof` checks, and return a single cast to a precise callable
+ * type. No double-cast chain, no `as unknown` anchor.
+ */
+function resolveMailServiceCtor(mod: unknown): new () => MailService {
+	if (mod && typeof mod === "object" && "MailService" in mod) {
+		const candidate = (mod as { MailService: unknown }).MailService;
+		if (typeof candidate === "function") {
+			return candidate as new () => MailService;
+		}
+	}
+	throw new RoverError(
+		"MAIL_PROVIDER_CONFIG",
+		"@sendgrid/mail runtime does not expose `.MailService` — upgrade to v8+",
+		{
+			hint: "Expected `module.exports.MailService` to be the MailService class (index.js attaches it).",
+		},
+	);
+}
+
+registerTransport("sendgrid", (config) => new SendGridTransport(config));