@c9up/rover 0.1.12 → 0.1.14

package/src/config.ts

@@ -22,7 +22,9 @@ function describe(transport: string) {
 }
 
 /**
- * Mailer descriptors for `defineConfig`, matching the AdonisJS call site:
+ * One helper per transport rover ships. Each returns the descriptor a
+ * `mailers` entry is made of — the transport name plus the settings that
+ * transport reads:
  *
  *   defineConfig({
  *     default: 'smtp',
@@ -30,13 +32,12 @@ function describe(transport: string) {
  *     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.
+ * The descriptor is plain data, so a config file can be serialised and
+ * inspected; the transport itself registers on import of the package entry.
  *
- * 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.
+ * The list is exactly what rover can send through — naming a transport that
+ * has no helper fails to COMPILE, which says so plainly, instead of throwing
+ * at boot.
  */
 export const transports = {
 	smtp: describe("smtp"),

package/src/configure.ts

@@ -0,0 +1,53 @@
+/**
+ * `ream configure @c9up/rover` — wire mail in one command.
+ *
+ * The provider alone is not enough: it reads `config/mail.ts`, and a package
+ * registered without one falls back to a default that is rarely the one an
+ * application wants. Writing both together is what makes `ream add` mean
+ * installed AND working.
+ */
+
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	// The config below reads these, so they are declared here. Writing the file
+	// without them leaves an application whose config asks the environment for
+	// something nothing ever put there.
+	await codemods.addEnvVars({
+		MAIL_MAILER: "log",
+		MAIL_FROM: "noreply@example.com",
+		SMTP_HOST: "",
+		SMTP_PORT: "587",
+	});
+
+	await codemods.addProvider("@c9up/rover/provider");
+	await codemods.writeFile(
+		"config/mail.ts",
+		`import { defineConfig, transports } from '@c9up/rover'
+import env from '#start/env'
+
+export default defineConfig({
+  // Has to name one of the mailers below, or the application refuses to boot.
+  default: env.get('MAIL_MAILER', 'log'),
+  from: env.get('MAIL_FROM', 'noreply@example.com'),
+
+  mailers: {
+    // Writes to the logger instead of sending. The development mailer.
+    log: transports.log(),
+
+    smtp: transports.smtp({
+      host: env.get('SMTP_HOST', ''),
+      port: Number(env.get('SMTP_PORT', '587')),
+    }),
+  },
+})`,
+	);
+}

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

@@ -44,7 +44,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 +55,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 +66,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.",
@@ -105,7 +105,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." },
 			);
@@ -160,7 +160,7 @@ export class MailgunTransport implements MailTransport {
 
 /**
  * mailgun.js's own error shape is `{ status, details | message, ... }`.
- * Map it to our uniform `MAIL_PROVIDER_ERROR` so retry + observability
+ * Map it to our uniform `E_MAIL_PROVIDER_ERROR` so retry + observability
  * consumers don't need to branch on provider.
  *
  * Bare `Error` (no `status`) — typical for network/ECONNRESET failures from
@@ -200,7 +200,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.",

package/src/transports/ResendTransport.ts

@@ -47,7 +47,7 @@ export class ResendTransport implements MailTransport {
 			typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
 		if (!apiKey) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"Resend transport requires apiKey",
 				{ hint: "Set { apiKey } in your mail config." },
 			);
@@ -62,7 +62,7 @@ export class ResendTransport 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." },
 			);
@@ -127,7 +127,7 @@ export class ResendTransport implements MailTransport {
 			};
 			if (retryAfter) ctx.retryAfter = retryAfter;
 			throw new RoverError(
-				"MAIL_PROVIDER_ERROR",
+				"E_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.",

package/src/transports/SendGridTransport.ts

@@ -50,7 +50,7 @@ export class SendGridTransport implements MailTransport {
 			typeof config.apiKey === "string" ? normalizeConfig(config.apiKey) : "";
 		if (!apiKey) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"SendGrid transport requires apiKey",
 				{ hint: "Set { apiKey } in your mail config." },
 			);
@@ -148,7 +148,7 @@ function assertHasRecipients(message: MailMessage): void {
 		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." },
 		);
@@ -215,7 +215,7 @@ function wrapSendGridError(err: unknown): RoverError {
 	const retryAfter = anyErr.response?.headers?.["retry-after"];
 	if (retryAfter) ctx.retryAfter = retryAfter;
 	return new RoverError(
-		"MAIL_PROVIDER_ERROR",
+		"E_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.",
@@ -239,7 +239,7 @@ function resolveMailServiceCtor(mod: unknown): new () => MailService {
 		}
 	}
 	throw new RoverError(
-		"MAIL_PROVIDER_CONFIG",
+		"E_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).",

package/src/transports/SesTransport.ts

@@ -65,14 +65,14 @@ export class SesTransport implements MailTransport {
 				: "";
 		if (!accessKeyId || !secretAccessKey || !rawRegion) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"SES transport requires accessKeyId, secretAccessKey, and region",
 				{ hint: "Set all three in your mail config." },
 			);
 		}
 		if (!REGION_RE.test(rawRegion)) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				`SES region "${rawRegion}" is not a valid AWS region identifier`,
 				{
 					hint: "Use the lowercase canonical form, e.g. 'us-east-1'. Uppercase breaks the SigV4 signing scope.",
@@ -92,7 +92,7 @@ export class SesTransport 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." },
 			);
@@ -132,7 +132,7 @@ export class SesTransport implements MailTransport {
 			};
 			if (retryAfter) ctx.retryAfter = retryAfter;
 			throw new RoverError(
-				"MAIL_PROVIDER_ERROR",
+				"E_MAIL_PROVIDER_ERROR",
 				`SES 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/SparkPostTransport.ts

@@ -59,7 +59,7 @@ export class SparkPostTransport implements MailTransport {
 					: "";
 		if (!apiKey) {
 			throw new RoverError(
-				"MAIL_PROVIDER_CONFIG",
+				"E_MAIL_PROVIDER_CONFIG",
 				"SparkPost transport requires apiKey",
 				{ hint: "Set { apiKey } in your mail config." },
 			);
@@ -78,7 +78,7 @@ export class SparkPostTransport 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." },
 			);
@@ -148,7 +148,7 @@ export class SparkPostTransport implements MailTransport {
 			};
 			if (retryAfter) ctx.retryAfter = retryAfter;
 			throw new RoverError(
-				"MAIL_PROVIDER_ERROR",
+				"E_MAIL_PROVIDER_ERROR",
 				`SparkPost 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/fetchError.ts

@@ -1,7 +1,7 @@
 import { RoverError } from "../RoverError.js";
 
 /**
- * Wrap a `fetch()` rejection into the uniform `MAIL_PROVIDER_ERROR` shape
+ * Wrap a `fetch()` rejection into the uniform `E_MAIL_PROVIDER_ERROR` shape
  * so the retry classifier can recognise transient network failures
  * (ECONNRESET / ENOTFOUND / EAI_AGAIN / ...).
  *
@@ -32,7 +32,7 @@ export function wrapFetchNetworkError(
 	};
 	if (networkCode) ctx.networkCode = networkCode;
 	return new RoverError(
-		"MAIL_PROVIDER_ERROR",
+		"E_MAIL_PROVIDER_ERROR",
 		`${provider} fetch failed${networkCode ? ` (${networkCode})` : ""}`,
 		{
 			hint: "Inspect `context.networkCode` (ECONNRESET / ENOTFOUND / ...) — the retry classifier treats known transient errnos as retryable.",
@@ -50,7 +50,7 @@ const DEFAULT_TIMEOUT_MS = 30_000;
  * 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
+ * same `E_MAIL_PROVIDER_ERROR` shape the retry classifier already understands, so
  * it is retried like any other transient network failure.
  */
 export async function fetchWithTimeout(
@@ -68,7 +68,7 @@ export async function fetchWithTimeout(
 	} catch (err) {
 		if (err instanceof Error && err.name === "TimeoutError") {
 			throw new RoverError(
-				"MAIL_PROVIDER_ERROR",
+				"E_MAIL_PROVIDER_ERROR",
 				`${provider} did not answer within ${timeoutMs}ms.`,
 				{
 					context: { provider, upstreamStatus: "0", networkCode: "ETIMEDOUT" },

package/src/webhooks/resend.ts

@@ -57,6 +57,31 @@ const EVENT_MAP: Record<string, string> = {
 	"email.bounced": "mail.bounced",
 };
 
+/**
+ * Turn the configured signing secret into key bytes, or refuse.
+ *
+ * `Buffer.from(value, "base64")` never fails: it skips whatever it cannot read
+ * and hands back whatever is left, so a mistyped secret quietly becomes a
+ * short, deterministic key. Nothing then reports a configuration problem —
+ * every delivery just fails verification and looks like an attack, which is
+ * the one signal this endpoint exists to give.
+ */
+function decodeSigningSecret(value: string): Buffer {
+	const bytes = Buffer.from(value, "base64");
+	const normalize = (v: string) => v.replace(/=+$/, "").replace(/\s/g, "");
+	if (normalize(bytes.toString("base64")) !== normalize(value)) {
+		throw new Error(
+			"createResendWebhookHandler: secret is not valid base64. Copy it from the Resend dashboard — it looks like `whsec_<base64>`.",
+		);
+	}
+	if (bytes.length < 16) {
+		throw new Error(
+			`createResendWebhookHandler: secret decodes to ${bytes.length} bytes, which is too short to sign with. Expected at least 16.`,
+		);
+	}
+	return bytes;
+}
+
 export function createResendWebhookHandler(
 	options: ResendWebhookOptions,
 ): WebhookMiddleware {
@@ -68,7 +93,7 @@ export function createResendWebhookHandler(
 	const secretRaw = options.secret.startsWith("whsec_")
 		? options.secret.slice(6)
 		: options.secret;
-	const keyBytes = Buffer.from(secretRaw, "base64");
+	const keyBytes = decodeSigningSecret(secretRaw);
 	const emitter = options.emitter;
 	const maxAgeSeconds = options.maxAgeSeconds ?? 300;