@c9up/rover 0.1.13 → 0.1.15

package/src/Mail.ts

@@ -199,13 +199,13 @@ export class SmtpTransport implements MailTransport {
 		// construction with an actionable message instead.
 		if (config.host !== undefined && typeof config.host !== "string") {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				`SMTP host must be a string, got ${typeof config.host}`,
 				{ hint: "Set config.host to your SMTP server hostname." },
 			);
 		}
 		if (typeof config.host !== "string" || config.host.length === 0) {
-			throw new RoverError("MAIL_PROVIDER_CONFIG", "SMTP host is required", {
+			throw new RoverError("E_MAIL_PROVIDER_CONFIG", "SMTP host is required", {
 				hint: "Set config.host (e.g. process.env.SMTP_HOST). Use the fake / log transports for local development.",
 			});
 		}
@@ -220,7 +220,7 @@ export class SmtpTransport implements MailTransport {
 		// fail fast rather than connect anonymously and let the server reject.
 		if ((user && !pass) || (!user && pass)) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"SMTP auth requires both `user` and `pass` or neither",
 				{
 					hint: "Check your env vars — one half of the credential pair is missing.",
@@ -250,7 +250,7 @@ export class SmtpTransport implements MailTransport {
 			message.bcc.length === 0
 		) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Mail message has no recipients",
 				{ hint: "Set at least one `to`, `cc`, or `bcc` before sending." },
 			);
@@ -310,7 +310,7 @@ export class SmtpTransport implements MailTransport {
 }
 
 /**
- * Normalise nodemailer / socket errors into the uniform `MAIL_PROVIDER_ERROR`
+ * Normalise nodemailer / socket errors into the uniform `E_MAIL_PROVIDER_ERROR`
  * shape used by the rest of the library. Preserves the `code` field (errno)
  * in `context.networkCode` so `isRetryableError` can classify transient
  * network failures without losing the root cause.
@@ -333,7 +333,7 @@ function wrapSmtpError(err: unknown): RoverError {
 		ctx.networkCode = anyErr.code;
 	}
 	return new RoverError(
-		"MAIL_PROVIDER_ERROR",
+		"E_MAIL_PROVIDER_ERROR",
 		`SMTP failed: ${anyErr.message ?? "unknown"}`,
 		{
 			hint: "Inspect `context.networkCode` (ECONNRESET/ETIMEDOUT/...) or `context.upstreamStatus` (SMTP response code) to decide retry eligibility.",
@@ -433,7 +433,7 @@ export class Mail {
 			const factory = transportFactories[transportConfig.transport];
 			if (!factory) {
 				throw new RoverError(
-					"MAIL_UNKNOWN_TRANSPORT",
+					"E_MAIL_UNKNOWN_TRANSPORT",
 					`Unknown mail transport type '${transportConfig.transport}' (configured under name '${name}')`,
 					{
 						hint: "Register the transport with registerTransport() before constructing Mail, or fix the typo in config.mail.transports[*].transport.",
@@ -452,7 +452,7 @@ export class Mail {
 		// production. Refuse at construction and name what was declared.
 		if (!this.#transports.has(this.#defaultTransport)) {
 			throw new RoverError(
-				"MAIL_UNKNOWN_MAILER",
+				"E_MAIL_UNKNOWN_MAILER",
 				`Mail default mailer '${this.#defaultTransport}' is not declared in config.mailers`,
 				{
 					hint: `${knownMailers(this.#transports)} Add it, or point \`default\` at one of them.`,
@@ -735,11 +735,17 @@ export class Mail {
 			);
 		}
 		if (this.#emitter) {
-			try {
-				this.#emitter.emit(name, event);
-			} catch {
-				// Event bus failure ≠ mail delivery failure — swallow.
-			}
+			// Not just `try`: an Adonis-shaped emitter returns a promise, and a
+			// listener that failed asynchronously rejected it with nobody to
+			// catch — an unhandled rejection ending the process over a
+			// notification, long after the mail itself went out fine.
+			void (async () => this.#emitter?.emit(name, event))().catch(
+				(err: unknown) => {
+					process.stderr.write(
+						`[rover] ${name} listener failed: ${err instanceof Error ? err.message : String(err)}\n`,
+					);
+				},
+			);
 		}
 	}
 
@@ -812,7 +818,7 @@ export class Mail {
 		const transport = this.#transports.get(name);
 		if (transport) return transport;
 		throw new RoverError(
-			"MAIL_UNKNOWN_MAILER",
+			"E_MAIL_UNKNOWN_MAILER",
 			`Mail mailer '${name}' is not declared in config.mailers`,
 			{ hint: knownMailers(this.#transports) },
 		);
@@ -911,7 +917,7 @@ function validateMailMessage(message: MailMessage): void {
 	// invalid per RFC 5321 reverse-path semantics.
 	if (typeof message.from !== "string" || message.from.trim() === "") {
 		throw new RoverError(
-			"MAIL_INVALID_MESSAGE",
+			"E_MAIL_INVALID_MESSAGE",
 			"Mail message has no `from` address",
 			{
 				hint: "Set `config.from`, an instance `from`, or call `message.from(...)` in the builder.",
@@ -922,14 +928,14 @@ function validateMailMessage(message: MailMessage): void {
 	// `to` to be an array (cc/bcc are optional at the queue boundary), so a
 	// deserialised job payload may reach here with `cc`/`bcc` as `undefined`.
 	// `.some(...)` on `undefined` throws `TypeError` instead of the
-	// structured `MAIL_INVALID_MESSAGE` this validator is supposed to surface.
+	// structured `E_MAIL_INVALID_MESSAGE` this validator is supposed to surface.
 	const hasRecipient =
 		(Array.isArray(message.to) && message.to.some(isNonEmptyAddress)) ||
 		(Array.isArray(message.cc) && message.cc.some(isNonEmptyAddress)) ||
 		(Array.isArray(message.bcc) && message.bcc.some(isNonEmptyAddress));
 	if (!hasRecipient) {
 		throw new RoverError(
-			"MAIL_INVALID_MESSAGE",
+			"E_MAIL_INVALID_MESSAGE",
 			"Mail message has no recipients",
 			{
 				hint: "Call `message.to(...)`, `cc(...)`, or `bcc(...)` with a non-empty address before sending.",
@@ -960,12 +966,12 @@ function errorDescriptor(
 	if (err instanceof Error) {
 		const errnoCode = (err as { code?: unknown }).code;
 		return {
-			code: typeof errnoCode === "string" ? errnoCode : "UNKNOWN",
+			code: typeof errnoCode === "string" ? errnoCode : "E_ROVER_UNKNOWN",
 			message: err.message,
 			attempts,
 		};
 	}
-	return { code: "UNKNOWN", message: String(err), attempts };
+	return { code: "E_ROVER_UNKNOWN", message: String(err), attempts };
 }
 
 /** "Declared mailers: a, b." — the half of an unknown-mailer error that helps. */

package/src/MessageBuilder.ts

@@ -183,7 +183,7 @@ export function attachmentsFor(message: MailMessage): MailAttachment[] {
 		// SMTP. An HTTP provider takes the bytes, and silently dropping the
 		// invitation would be worse than saying so.
 		throw new RoverError(
-			"ICAL_HREF_UNSUPPORTED",
+			"E_ICAL_HREF_UNSUPPORTED",
 			"icalEventFromUrl() is only supported by the SMTP transport, which fetches the URL itself.",
 			{
 				hint: "Fetch the ICS yourself and pass it to icalEvent(contents), or use icalEventFromFile().",
@@ -208,7 +208,7 @@ async function readAttachment(path: string, label: string): Promise<Buffer> {
 		return await readFile(path);
 	} catch (err) {
 		throw new RoverError(
-			"ATTACHMENT_UNREADABLE",
+			"E_ATTACHMENT_UNREADABLE",
 			`Could not read ${label} from "${path}": ${err instanceof Error ? err.message : String(err)}`,
 			{
 				hint: "Give an absolute path, or attach the bytes with attachData() / embedData().",
@@ -246,7 +246,7 @@ function renderListHeader(
 function expect(passed: boolean, expectation: string, actual: unknown): void {
 	if (passed) return;
 	throw new RoverError(
-		"ASSERTION_FAILED",
+		"E_ASSERTION_FAILED",
 		`Expected the message ${expectation}, got ${JSON.stringify(actual)}`,
 	);
 }
@@ -760,7 +760,7 @@ export class MessageBuilder {
 			for (const url of listUrls(value)) {
 				if (!url.toLowerCase().startsWith("http")) {
 					throw new RoverError(
-						"INVALID_LIST_HEADER",
+						"E_INVALID_LIST_HEADER",
 						`listUnsubscribe({ oneClick: true }) needs an https URL that can answer a POST, got "${url}".`,
 						{
 							hint: "Keep the mailto: form without oneClick, or add an https endpoint alongside it.",

package/src/format.ts

@@ -37,7 +37,7 @@ export function formatAddress(address: string, name?: string): string {
 function assertHeaderSafe(value: string, what: string): void {
 	if (!HEADER_BREAKERS.test(value)) return;
 	throw new RoverError(
-		"MAIL_HEADER_INJECTION",
+		"E_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/queue/MailJob.ts

@@ -70,14 +70,14 @@ export class MailJobHandler implements BayJobHandlerLike {
 
 /**
  * Narrow an `unknown` payload from the queue driver into a `MailJobPayload`.
- * Throws `MAIL_JOB_MALFORMED` when the shape is unrecognisable so Bay records
+ * Throws `E_MAIL_JOB_MALFORMED` when the shape is unrecognisable so Bay records
  * a clean failure rather than crashing inside `dispatchMessage` with a raw
  * `TypeError`.
  */
 function validatePayload(payload: unknown): MailJobPayload {
 	if (!payload || typeof payload !== "object") {
 		throw new RoverError(
-			"MAIL_JOB_MALFORMED",
+			"E_MAIL_JOB_MALFORMED",
 			"Mail job payload is missing or not an object",
 			{ hint: "Queue driver returned a non-object — check serialisation." },
 		);
@@ -86,7 +86,7 @@ function validatePayload(payload: unknown): MailJobPayload {
 	const message = asObj.message;
 	if (!message || typeof message !== "object") {
 		throw new RoverError(
-			"MAIL_JOB_MALFORMED",
+			"E_MAIL_JOB_MALFORMED",
 			"Mail job payload.message is missing or not an object",
 			{
 				hint: "Payload shape must be { message: MailMessage, transport?: string }.",
@@ -100,7 +100,7 @@ function validatePayload(payload: unknown): MailJobPayload {
 		!Array.isArray(m.attachments)
 	) {
 		throw new RoverError(
-			"MAIL_JOB_MALFORMED",
+			"E_MAIL_JOB_MALFORMED",
 			"Mail job payload.message does not match MailMessage shape",
 			{
 				hint: "Expected `{ from: string, to: string[], ..., attachments: [] }`.",

package/src/retry.ts

@@ -24,15 +24,15 @@ const RETRYABLE_ERRNO = new Set([
 
 /**
  * A failure is retryable when:
- *   - it's a `MAIL_PROVIDER_ERROR` with `upstreamStatus` 429 or ≥ 500
- *   - or it's a `MAIL_PROVIDER_ERROR` whose `context.networkCode` is a known
+ *   - it's a `E_MAIL_PROVIDER_ERROR` with `upstreamStatus` 429 or ≥ 500
+ *   - or it's a `E_MAIL_PROVIDER_ERROR` whose `context.networkCode` is a known
  *     retryable Node errno (SDK wrappers surface the original errno this way
  *     when the HTTP layer never produced a status)
  *   - or it's a raw Error with a matching Node networking errno on `.code`
  * 4xx (non-429) is treated as permanent: retrying won't help.
  */
 export function isRetryableError(err: unknown): boolean {
-	if (err instanceof RoverError && err.code === "MAIL_PROVIDER_ERROR") {
+	if (err instanceof RoverError && err.code === "E_MAIL_PROVIDER_ERROR") {
 		const statusStr = err.context.upstreamStatus;
 		const status = Number(statusStr);
 		if (Number.isFinite(status)) {
@@ -70,7 +70,7 @@ export function computeBackoffMs(
 	// SES/Resend transports capture it into `context.retryAfter`). Value is
 	// seconds per HTTP RFC 7231 §7.1.3; we cap at `maxDelayMs` so a malicious
 	// or mistaken provider can't force a very-long wait.
-	if (err instanceof RoverError && err.code === "MAIL_PROVIDER_ERROR") {
+	if (err instanceof RoverError && err.code === "E_MAIL_PROVIDER_ERROR") {
 		const hint = err.context.retryAfter;
 		if (hint) {
 			const seconds = Number(hint);
@@ -104,7 +104,7 @@ export function resolveRetryConfig(
 	};
 	if (!Number.isInteger(merged.maxAttempts) || merged.maxAttempts < 1) {
 		throw new RoverError(
-			"MAIL_RETRY_CONFIG",
+			"E_MAIL_RETRY_CONFIG",
 			`RetryConfig.maxAttempts must be an integer >= 1 (got ${merged.maxAttempts})`,
 			{ hint: "Set retry.maxAttempts to a positive integer." },
 		);
@@ -115,7 +115,7 @@ export function resolveRetryConfig(
 		merged.baseDelayMs < 0
 	) {
 		throw new RoverError(
-			"MAIL_RETRY_CONFIG",
+			"E_MAIL_RETRY_CONFIG",
 			`RetryConfig.baseDelayMs must be a non-negative finite number (got ${merged.baseDelayMs})`,
 			{ hint: "Use 0 or a positive number; the 50 ms floor kicks in anyway." },
 		);
@@ -126,7 +126,7 @@ export function resolveRetryConfig(
 		merged.factor <= 0
 	) {
 		throw new RoverError(
-			"MAIL_RETRY_CONFIG",
+			"E_MAIL_RETRY_CONFIG",
 			`RetryConfig.factor must be a positive finite number (got ${merged.factor})`,
 			{ hint: "Use >= 1 for exponential growth; 1 means constant delay." },
 		);

package/src/templating/SimpleTemplate.ts

@@ -84,13 +84,13 @@ function dataReplacer(_key: string, value: unknown): unknown {
 			return Number(value);
 		}
 		throw new RoverError(
-			"MAIL_TEMPLATE_SYNTAX",
+			"E_MAIL_TEMPLATE_SYNTAX",
 			`Cannot render bigint ${value} — it exceeds Number.MAX_SAFE_INTEGER and cannot cross the template engine boundary without precision loss; format it to a string before rendering`,
 		);
 	}
 	if (typeof value === "number" && !Number.isFinite(value)) {
 		throw new RoverError(
-			"MAIL_TEMPLATE_SYNTAX",
+			"E_MAIL_TEMPLATE_SYNTAX",
 			`Cannot render non-finite number ${value} — NaN and Infinity have no representation across the template engine boundary; format it to a string before rendering`,
 		);
 	}
@@ -129,7 +129,7 @@ function errnoCode(err: unknown): string {
 
 /**
  * Resolve + read + compile one template path, caching the compiled IR by its
- * resolved absolute path. Owns the `MAIL_TEMPLATE_NOT_FOUND` / `_READ_ERROR`
+ * resolved absolute path. Owns the `E_MAIL_TEMPLATE_NOT_FOUND` / `_READ_ERROR`
  * raising (unchanged from the pre-migration engine).
  */
 async function loadIr(viewPath: string, root: string): Promise<NativeRoverIr> {
@@ -145,7 +145,7 @@ async function loadIr(viewPath: string, root: string): Promise<NativeRoverIr> {
 		// Only ENOENT maps to NOT_FOUND; permission/io errors surface distinctly.
 		if (code !== "ENOENT") {
 			throw new RoverError(
-				"MAIL_TEMPLATE_READ_ERROR",
+				"E_MAIL_TEMPLATE_READ_ERROR",
 				`Template read failed at ${resolved} (${code || "unknown"})`,
 				{
 					hint: "Check filesystem permissions and file descriptor limits.",
@@ -154,7 +154,7 @@ async function loadIr(viewPath: string, root: string): Promise<NativeRoverIr> {
 			);
 		}
 		throw new RoverError(
-			"MAIL_TEMPLATE_NOT_FOUND",
+			"E_MAIL_TEMPLATE_NOT_FOUND",
 			`Template not found at ${resolved}`,
 			{
 				hint: "Create the file or update config.mail.viewsRoot.",
@@ -198,10 +198,10 @@ async function buildPartialMap(
 				// A partial referenced only inside a falsy `{{#if}}` is never
 				// rendered. The pre-migration engine loaded partials lazily, so a
 				// missing such partial did not error. Skip it here; if it IS reached
-				// at render time the Rust renderer raises MAIL_TEMPLATE_NOT_FOUND.
+				// at render time the Rust renderer raises E_MAIL_TEMPLATE_NOT_FOUND.
 				if (
 					err instanceof RoverError &&
-					err.code === "MAIL_TEMPLATE_NOT_FOUND"
+					err.code === "E_MAIL_TEMPLATE_NOT_FOUND"
 				) {
 					continue;
 				}
@@ -238,7 +238,7 @@ function resolveTemplatePath(
 	const rel = path.relative(rootAbs, candidate);
 	if (rel.startsWith("..") || path.isAbsolute(rel)) {
 		throw new RoverError(
-			"MAIL_TEMPLATE_NOT_FOUND",
+			"E_MAIL_TEMPLATE_NOT_FOUND",
 			`Template path "${viewPath}" resolves outside of viewsRoot`,
 			{
 				hint: "Template names must stay under viewsRoot. Absolute paths and `..` traversals are rejected.",

package/src/templating/loadNapi.ts

@@ -1,6 +1,6 @@
 // Loads the native `rover-template-engine-napi` binary built by
 // `scripts/copy-napi.mjs` and re-throws load failures as
-// `MAIL_TEMPLATE_NAPI_REQUIRED` (D55.2.4) — actionable hint points at
+// `E_MAIL_TEMPLATE_NAPI_REQUIRED` (D55.2.4) — actionable hint points at
 // `pnpm --filter @c9up/rover build:napi`.
 //
 // Per cerebrum 2026-04-15 there is NO JS fallback. If the binary fails to load,
@@ -25,7 +25,7 @@ function platformSuffix(): string {
 	const suffix = SUFFIX_MAP[key];
 	if (typeof suffix !== "string") {
 		throw new RoverError(
-			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			"E_MAIL_TEMPLATE_NAPI_REQUIRED",
 			`Unsupported platform/arch '${key}' for @c9up/rover native binary. Supported: ${Object.keys(SUFFIX_MAP).join(", ")}.`,
 			{
 				hint: "Build the native binary on a supported platform with 'pnpm --filter @c9up/rover build:napi'.",
@@ -87,7 +87,7 @@ export function getNative(): NativeExports {
 			? " If you are on Alpine/musl, note the prebuilt binaries target glibc (musl is not a supported target)."
 			: "";
 		throw new RoverError(
-			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			"E_MAIL_TEMPLATE_NAPI_REQUIRED",
 			`@c9up/rover native binary 'index.${suffix}.node' not found or failed to load near ${here} — run 'pnpm --filter @c9up/rover build:napi' to build it.${muslHint} Cause: ${causeMessage}`,
 			{
 				hint: "Run 'pnpm --filter @c9up/rover build:napi' to compile the native template engine.",
@@ -96,7 +96,7 @@ export function getNative(): NativeExports {
 	}
 	if (!isNativeExports(loaded)) {
 		throw new RoverError(
-			"MAIL_TEMPLATE_NAPI_REQUIRED",
+			"E_MAIL_TEMPLATE_NAPI_REQUIRED",
 			"@c9up/rover native binary loaded but missing expected exports (engineVersion / compile / renderIr). Rebuild with 'pnpm --filter @c9up/rover build:napi'.",
 			{
 				hint: "The native binary is stale — rebuild with 'pnpm --filter @c9up/rover build:napi'.",
@@ -126,11 +126,11 @@ function isNapiErrorPayload(value: unknown): value is NapiErrorPayload {
 
 /** Codes the Rust engine legitimately emits, with their actionable hints. */
 const CODE_HINTS: Readonly<Record<string, string>> = {
-	MAIL_TEMPLATE_SYNTAX:
+	E_MAIL_TEMPLATE_SYNTAX:
 		"Check the template grammar: {{ var }}, {{{ raw }}}, {{#if x}}...{{/if}}, {{> partial}}.",
 	MAIL_TEMPLATE_RECURSION:
 		"Break the cycle — a template cannot include itself (directly or via partials).",
-	MAIL_TEMPLATE_NOT_FOUND:
+	E_MAIL_TEMPLATE_NOT_FOUND:
 		"Create the referenced partial file or remove the {{> name}} reference.",
 };
 
@@ -156,12 +156,12 @@ export function toReamError(err: unknown): RoverError {
 			}
 		}
 		return new RoverError(
-			"MAIL_TEMPLATE_SYNTAX",
+			"E_MAIL_TEMPLATE_SYNTAX",
 			`Native template call failed: ${err.message}`,
 		);
 	}
 	return new RoverError(
-		"MAIL_TEMPLATE_SYNTAX",
+		"E_MAIL_TEMPLATE_SYNTAX",
 		`Native template call failed with non-Error: ${String(err)}`,
 	);
 }

package/src/transports/BrevoTransport.ts

@@ -60,7 +60,7 @@ export class BrevoTransport implements MailTransport {
 					: "";
 		if (!apiKey) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Brevo transport requires apiKey",
 				{ hint: "Set { apiKey } in your mail config." },
 			);
@@ -79,7 +79,7 @@ export class BrevoTransport implements MailTransport {
 			message.bcc.length === 0
 		) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Mail message has no recipients",
 				{ hint: "Set at least one `to`, `cc`, or `bcc` before sending." },
 			);
@@ -137,7 +137,7 @@ export class BrevoTransport implements MailTransport {
 			};
 			if (retryAfter) ctx.retryAfter = retryAfter;
 			throw new RoverError(
-				"MAIL_PROVIDER_ERROR",
+				"E_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.",

package/src/transports/MailgunTransport.ts

@@ -1,6 +1,3 @@
-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,
@@ -9,6 +6,7 @@ import {
 } from "../Mail.js";
 import { attachmentsFor, headerValue } from "../MessageBuilder.js";
 import { RoverError } from "../RoverError.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();
@@ -23,19 +21,10 @@ const redactSecrets = (s: string): string =>
 		.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;
+	#apiKey: string;
 	#domain: string;
+	#baseUrl: string;
 
 	constructor(config: Record<string, unknown>) {
 		const apiKey =
@@ -44,7 +33,7 @@ export class MailgunTransport implements MailTransport {
 			typeof config.domain === "string" ? normalizeConfig(config.domain) : "";
 		if (!apiKey || !domain) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Mailgun transport requires apiKey and domain",
 				{ hint: "Set { apiKey, domain } in your mail config." },
 			);
@@ -55,7 +44,7 @@ export class MailgunTransport implements MailTransport {
 		// 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",
+				"E_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'." },
 			);
@@ -66,7 +55,7 @@ export class MailgunTransport implements MailTransport {
 				: "us";
 		if (rawRegion !== "us" && rawRegion !== "eu") {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_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.",
@@ -78,24 +67,11 @@ export class MailgunTransport implements MailTransport {
 				? "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 });
-		}
+		this.#apiKey = apiKey;
+		this.#baseUrl =
+			typeof config.baseUrl === "string" && config.baseUrl.length > 0
+				? normalizeConfig(config.baseUrl).replace(/\/+$/, "")
+				: url;
 	}
 
 	async send(message: MailMessage): Promise<MailSendOutcome> {
@@ -105,7 +81,7 @@ export class MailgunTransport implements MailTransport {
 			message.bcc.length === 0
 		) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Mail message has no recipients",
 				{ hint: "Set at least one `to`, `cc`, or `bcc` before sending." },
 			);
@@ -134,38 +110,70 @@ export class MailgunTransport implements MailTransport {
 				? v.map(stripCrlf).join(", ")
 				: stripCrlf(v);
 		}
-		if (attachmentsFor(message).length > 0) {
-			data.attachment = attachmentsFor(message).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;
-			});
+		// Mailgun takes `multipart/form-data`; Node builds it, and `fetch` sets
+		// the boundary. Scalars first, then one file part per attachment.
+		const form = new FormData();
+		for (const [key, value] of Object.entries(data)) {
+			form.append(key, Array.isArray(value) ? value.join(", ") : String(value));
+		}
+		for (const att of attachmentsFor(message)) {
+			const bytes = Buffer.from(att.content as Buffer | string);
+			const blob = att.contentType
+				? new Blob([bytes], { type: stripCrlf(att.contentType) })
+				: new Blob([bytes]);
+			form.append("attachment", blob, stripCrlf(att.filename));
 		}
 
+		let res: Response;
 		try {
-			const res = await this.#client.messages.create(this.#domain, data);
-			if (res.id) return { providerId: res.id };
-			return undefined;
+			res = await fetchWithTimeout(
+				"Mailgun",
+				`${this.#baseUrl}/v3/${encodeURIComponent(this.#domain)}/messages`,
+				{
+					method: "POST",
+					headers: {
+						// HTTP Basic, the username is literally `api`.
+						Authorization: `Basic ${Buffer.from(`api:${this.#apiKey}`).toString("base64")}`,
+						Accept: "application/json",
+					},
+					body: form,
+				},
+			);
 		} catch (err) {
-			throw wrapMailgunError(err);
+			throw wrapFetchNetworkError("mailgun", err);
+		}
+
+		const raw = await res.text();
+		if (!res.ok) {
+			throw wrapMailgunError({
+				status: res.status,
+				message: raw,
+				headers: Object.fromEntries(res.headers.entries()),
+			});
+		}
+		// A 200 carries `{ id, message }`; anything unparseable is still a
+		// success on the wire, so it is not turned into an error.
+		try {
+			const parsed: unknown = JSON.parse(raw);
+			const id =
+				typeof parsed === "object" && parsed !== null
+					? Reflect.get(parsed, "id")
+					: undefined;
+			return typeof id === "string" ? { providerId: id } : undefined;
+		} catch {
+			return undefined;
 		}
 	}
 }
 
 /**
- * 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.
+ * Map an upstream refusal onto the uniform `E_MAIL_PROVIDER_ERROR` every
+ * transport raises, so retry and observability never branch on the 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.
+ * The shape is what the HTTP response gives: a status, the body as the
+ * message, and the response headers — `Retry-After` among them, which the
+ * backoff honours. A network failure never reaches here; `wrapFetchNetworkError`
+ * carries the errno so the retry predicate can still see it.
  */
 function wrapMailgunError(err: unknown): RoverError {
 	if (err instanceof RoverError) return err;
@@ -176,8 +184,8 @@ function wrapMailgunError(err: unknown): RoverError {
 		code?: string;
 		headers?: Record<string, string | string[]>;
 	};
-	// Coerce string-typed status ("401") into number — mailgun.js is
-	// inconsistent across versions.
+	// Coerce a string-typed status into a number: the field is built here, but
+	// a caller injecting a fake response may still hand one over as text.
 	const statusNum = Number(anyErr.status);
 	const status = Number.isFinite(statusNum) ? statusNum : 0;
 	const providerMessage = redactSecrets(
@@ -200,7 +208,7 @@ function wrapMailgunError(err: unknown): RoverError {
 			: retryAfterHeader;
 	}
 	return new RoverError(
-		"MAIL_PROVIDER_ERROR",
+		"E_MAIL_PROVIDER_ERROR",
 		`Mailgun returned ${status || "unknown"}`,
 		{
 			hint: "Inspect `context.upstreamStatus` (HTTP) or `context.networkCode` (ECONNRESET/etc.) to decide retry eligibility.",