@c9up/rover 0.1.3

package/src/MessageBuilder.ts

@@ -0,0 +1,101 @@
+import { renderFile as renderTemplateFile } from "./templating/SimpleTemplate.js";
+
+export interface MailMessage {
+	from: string;
+	to: string[];
+	cc: string[];
+	bcc: string[];
+	replyTo?: string;
+	subject: string;
+	html?: string;
+	text?: string;
+	attachments: MailAttachment[];
+	headers: Record<string, string>;
+}
+
+export interface MailAttachment {
+	filename: string;
+	content: Buffer | string;
+	contentType?: string;
+}
+
+export class MessageBuilder {
+	#msg: MailMessage = {
+		from: "",
+		to: [],
+		cc: [],
+		bcc: [],
+		subject: "",
+		attachments: [],
+		headers: {},
+	};
+	#pendingView: { path: string; data: Record<string, unknown> } | null = null;
+
+	from(address: string): this {
+		this.#msg.from = address;
+		return this;
+	}
+	to(address: string): this {
+		this.#msg.to.push(address);
+		return this;
+	}
+	cc(address: string): this {
+		this.#msg.cc.push(address);
+		return this;
+	}
+	bcc(address: string): this {
+		this.#msg.bcc.push(address);
+		return this;
+	}
+	replyTo(address: string): this {
+		this.#msg.replyTo = address;
+		return this;
+	}
+	subject(text: string): this {
+		this.#msg.subject = text;
+		return this;
+	}
+	html(content: string): this {
+		this.#msg.html = content;
+		return this;
+	}
+	text(content: string): this {
+		this.#msg.text = content;
+		return this;
+	}
+
+	attach(
+		filename: string,
+		content: Buffer | string,
+		contentType?: string,
+	): this {
+		this.#msg.attachments.push({ filename, content, contentType });
+		return this;
+	}
+
+	header(key: string, value: string): this {
+		this.#msg.headers[key] = value;
+		return this;
+	}
+
+	/**
+	 * Queue an HTML template render. The render happens lazily at `build()` time
+	 * so the fluent chain stays synchronous; `build()` is async and awaits the
+	 * render before returning the finalised `MailMessage`.
+	 */
+	htmlView(viewPath: string, data?: Record<string, unknown>): this {
+		this.#pendingView = { path: viewPath, data: data ?? {} };
+		return this;
+	}
+
+	async build(): Promise<MailMessage> {
+		if (this.#pendingView !== null) {
+			this.#msg.html = await renderTemplateFile(
+				this.#pendingView.path,
+				this.#pendingView.data,
+			);
+			this.#pendingView = null;
+		}
+		return this.#msg;
+	}
+}

package/src/RoverError.ts

@@ -0,0 +1,44 @@
+/**
+ * Rover's own structured error — keeps the package framework-agnostic (no
+ * dependency on `@c9up/ream`'s `ReamError`). Mirrors the error shape Rover
+ * carries through its transports and retry logic.
+ */
+export class RoverError extends Error {
+	/** Error code (e.g. "ROVER_SMTP_ERROR"). */
+	readonly code: string;
+	/** Additional context key-value pairs. */
+	readonly context: Record<string, string>;
+	/** Actionable hint for the developer. */
+	readonly hint?: string;
+	/** Source file where the error originated. */
+	readonly sourceFile?: string;
+	/** Line number in the source file. */
+	readonly sourceLine?: number;
+	/** URL to the error documentation page. */
+	readonly docsUrl?: string;
+	/** Pipeline stage where the error occurred (if applicable). */
+	readonly pipelineStage?: string;
+
+	constructor(
+		code: string,
+		message: string,
+		options?: {
+			context?: Record<string, string>;
+			hint?: string;
+			sourceFile?: string;
+			sourceLine?: number;
+			docsUrl?: string;
+			pipelineStage?: string;
+		},
+	) {
+		super(message);
+		this.name = "RoverError";
+		this.code = code;
+		this.context = options?.context ?? {};
+		this.hint = options?.hint;
+		this.sourceFile = options?.sourceFile;
+		this.sourceLine = options?.sourceLine;
+		this.docsUrl = options?.docsUrl;
+		this.pipelineStage = options?.pipelineStage;
+	}
+}

package/src/RoverProvider.ts

@@ -0,0 +1,72 @@
+import type { EmitterLike, MailConfig } from "./Mail.js";
+import { Mail } from "./Mail.js";
+import type { BayQueueLike } from "./queue/MailJob.js";
+import { setMail } from "./services/main.js";
+
+/**
+ * Duck-typed slice of the host's IoC container — rover does NOT import
+ * `@c9up/ream` so it stays publishable as a standalone package.
+ */
+interface RoverContainer {
+	singleton(token: unknown, factory: () => unknown): void;
+	resolve<T = unknown>(token: unknown): T;
+}
+interface RoverConfigStore {
+	get<T = unknown>(key: string): T | undefined;
+}
+export interface RoverAppContext {
+	container: RoverContainer;
+	config: RoverConfigStore;
+}
+
+export default class RoverProvider {
+	constructor(protected app: RoverAppContext) {}
+
+	register() {
+		this.app.container.singleton(Mail, () => {
+			const config = this.app.config.get<MailConfig>("mail");
+			return new Mail(
+				config ?? {
+					default: "log",
+					from: "noreply@localhost",
+					transports: { log: { transport: "log" } },
+				},
+				{
+					// Optional-peer wiring: if `@c9up/bay` is installed and its
+					// `QueueManager` is registered in the container, Mail gets
+					// queue support for `sendLater()`. If not, `sendLater()`
+					// throws `MAIL_QUEUE_REQUIRED` at call time (by design).
+					queue: tryResolve<BayQueueLike>(this.app, "QueueManager"),
+					// Same pattern for the event bus `Emitter` — enables `mail.sent`
+					// / `mail.failed` emission when available.
+					emitter: tryResolve<EmitterLike>(this.app, "Emitter"),
+				},
+			);
+		});
+		this.app.container.singleton("mail", () => {
+			return this.app.container.resolve<Mail>(Mail);
+		});
+	}
+
+	async boot() {
+		// Populate the `@c9up/rover/services/main` singleton with the
+		// container-resolved Mail instance so apps can
+		// `import mail from '@c9up/rover/services/main'` from anywhere.
+		setMail(this.app.container.resolve<Mail>(Mail));
+	}
+
+	async shutdown() {}
+}
+
+/**
+ * Resolve a token from the container without throwing when it's not
+ * registered. Rover never hard-depends on Bay or the event bus — both wire-points
+ * are purely opt-in.
+ */
+function tryResolve<T>(app: RoverAppContext, token: string): T | undefined {
+	try {
+		return app.container.resolve<T>(token);
+	} catch {
+		return undefined;
+	}
+}

package/src/config.ts

@@ -0,0 +1,7 @@
+import type { MailConfig } from "./Mail.js";
+
+export function defineConfig(config: MailConfig): MailConfig {
+	return config;
+}
+
+export type { MailConfig };

package/src/index.ts

@@ -0,0 +1,30 @@
+export type { MailAddress } from "./BaseMail.js";
+export { BaseMail } from "./BaseMail.js";
+export { defineConfig } from "./config.js";
+export { RoverError } from "./RoverError.js";
+export type {
+	EmitterLike,
+	MailAttachment,
+	MailConfig,
+	MailFailedEvent,
+	MailHooks,
+	MailMessage,
+	MailSendOutcome,
+	MailSendResult,
+	MailSentEvent,
+	MailTransport,
+	MailTransportFactory,
+} from "./Mail.js";
+export {
+	LogTransport,
+	Mail,
+	MessageBuilder,
+	registerTransport,
+	SmtpTransport,
+} from "./Mail.js";
+export { default as RoverProvider } from "./RoverProvider.js";
+export {
+	DEFAULT_RETRY_CONFIG,
+	isRetryableError,
+	type RetryConfig,
+} from "./retry.js";

package/src/queue/MailJob.ts

@@ -0,0 +1,131 @@
+import { Buffer } from "node:buffer";
+import { RoverError } from "../RoverError.js";
+import type { MailAttachment, MailMessage } from "../Mail.js";
+
+export const MAIL_JOB_NAME = "mail.send";
+
+export interface MailJobPayload {
+	message: MailMessage;
+	transport?: string;
+}
+
+/**
+ * Minimal structural interface for Bay's `QueueManager` — peer-dep friendly,
+ * matches `@c9up/bay`'s public API so `new QueueManager(driver)` is assignable.
+ */
+export interface BayQueueLike {
+	register(name: string, handler: BayJobHandlerLike): void;
+	dispatch(
+		name: string,
+		payload: unknown,
+		options?: { maxAttempts?: number },
+	): Promise<string>;
+}
+
+export interface BayJobHandlerLike {
+	handle(payload: unknown): Promise<void>;
+}
+
+/** Pared-down RetryConfig shape — avoids importing from `../retry.js` into queue/. */
+interface RetryOverride {
+	maxAttempts: number;
+	baseDelayMs: number;
+	factor: number;
+	maxDelayMs?: number;
+}
+
+export interface MailDispatcher {
+	dispatchMessage(
+		message: MailMessage,
+		transport?: string,
+		overrideRetry?: RetryOverride,
+	): Promise<void>;
+}
+
+/**
+ * Bay job handler for queued mail. Sets `maxAttempts: 1` so the in-process
+ * retry loop runs exactly once per job execution — Bay's own `maxAttempts`
+ * handles re-dispatch on throw. Prevents sync × queue retry compounding.
+ */
+export class MailJobHandler implements BayJobHandlerLike {
+	#mail: MailDispatcher;
+
+	constructor(mail: MailDispatcher) {
+		this.#mail = mail;
+	}
+
+	async handle(payload: unknown): Promise<void> {
+		const parsed = validatePayload(payload);
+		// `{ maxAttempts: 1 }` alone is sufficient — the loop runs exactly once
+		// and `computeBackoffMs` is never reached; the other RetryConfig fields
+		// resolve to defaults via `resolveRetryConfig` but don't affect control
+		// flow. Matches AC 8 wording exactly.
+		await this.#mail.dispatchMessage(revive(parsed.message), parsed.transport, {
+			maxAttempts: 1,
+			baseDelayMs: 0,
+			factor: 1,
+		});
+	}
+}
+
+/**
+ * Narrow an `unknown` payload from the queue driver into a `MailJobPayload`.
+ * Throws `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",
+			"Mail job payload is missing or not an object",
+			{ hint: "Queue driver returned a non-object — check serialisation." },
+		);
+	}
+	const asObj = payload as Record<string, unknown>;
+	const message = asObj.message;
+	if (!message || typeof message !== "object") {
+		throw new RoverError(
+			"MAIL_JOB_MALFORMED",
+			"Mail job payload.message is missing or not an object",
+			{
+				hint: "Payload shape must be { message: MailMessage, transport?: string }.",
+			},
+		);
+	}
+	const m = message as Record<string, unknown>;
+	if (
+		typeof m.from !== "string" ||
+		!Array.isArray(m.to) ||
+		!Array.isArray(m.attachments)
+	) {
+		throw new RoverError(
+			"MAIL_JOB_MALFORMED",
+			"Mail job payload.message does not match MailMessage shape",
+			{
+				hint: "Expected `{ from: string, to: string[], ..., attachments: [] }`.",
+			},
+		);
+	}
+	const transport =
+		typeof asObj.transport === "string" ? asObj.transport : undefined;
+	return { message: message as MailMessage, transport };
+}
+
+/**
+ * Revive Buffer attachments after JSON round-trip. Node serialises `Buffer` as
+ * `{ type: "Buffer", data: [...bytes] }`; we reconstruct to real `Buffer`.
+ */
+function revive(message: MailMessage): MailMessage {
+	if (!message.attachments || message.attachments.length === 0) return message;
+	const attachments: MailAttachment[] = message.attachments.map((att) => {
+		if (typeof att.content === "string") return att;
+		if (Buffer.isBuffer(att.content)) return att;
+		const serialised = att.content as { type?: string; data?: number[] };
+		if (serialised?.type === "Buffer" && Array.isArray(serialised.data)) {
+			return { ...att, content: Buffer.from(serialised.data) };
+		}
+		return att;
+	});
+	return { ...message, attachments };
+}

package/src/retry.ts

@@ -0,0 +1,135 @@
+import { RoverError } from "./RoverError.js";
+
+export interface RetryConfig {
+	maxAttempts: number;
+	baseDelayMs: number;
+	factor: number;
+	maxDelayMs?: number;
+}
+
+export const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {
+	maxAttempts: 3,
+	baseDelayMs: 500,
+	factor: 2,
+	maxDelayMs: 10_000,
+};
+
+const RETRYABLE_ERRNO = new Set([
+	"ETIMEDOUT",
+	"ECONNRESET",
+	"ECONNREFUSED",
+	"ENOTFOUND",
+	"EAI_AGAIN",
+]);
+
+/**
+ * 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
+ *     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") {
+		const statusStr = err.context.upstreamStatus;
+		const status = Number(statusStr);
+		if (Number.isFinite(status)) {
+			if (status === 429) return true;
+			if (status >= 500 && status < 600) return true;
+		}
+		const networkCode = err.context.networkCode;
+		if (networkCode && RETRYABLE_ERRNO.has(networkCode)) return true;
+		return false;
+	}
+	if (err instanceof Error) {
+		const code = (err as { code?: unknown }).code;
+		if (typeof code === "string" && RETRYABLE_ERRNO.has(code)) return true;
+		// Node 18+ `fetch` (undici) wraps the underlying socket error in
+		// `cause` and surfaces `TypeError: fetch failed` at the top level —
+		// the original errno is on `err.cause.code`, not `err.code`. Without
+		// this branch transient ECONNRESET/ENOTFOUND/etc. from raw fetch
+		// look indistinguishable from a permanent failure and never retry.
+		const cause = (err as { cause?: unknown }).cause;
+		if (cause && typeof cause === "object") {
+			const causeCode = (cause as { code?: unknown }).code;
+			if (typeof causeCode === "string" && RETRYABLE_ERRNO.has(causeCode))
+				return true;
+		}
+	}
+	return false;
+}
+
+export function computeBackoffMs(
+	attempt: number,
+	config: Required<RetryConfig>,
+	err?: unknown,
+): number {
+	// Honour the provider's Retry-After hint when present (Mailgun/SendGrid/
+	// 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") {
+		const hint = err.context.retryAfter;
+		if (hint) {
+			const seconds = Number(hint);
+			if (Number.isFinite(seconds) && seconds >= 0) {
+				return Math.min(config.maxDelayMs, Math.max(50, seconds * 1000));
+			}
+		}
+	}
+	const raw = config.baseDelayMs * config.factor ** (attempt - 1);
+	return Math.min(config.maxDelayMs, Math.max(50, raw));
+}
+
+export function resolveRetryConfig(
+	globalConfig: RetryConfig | undefined,
+	transportConfig: RetryConfig | undefined,
+): Required<RetryConfig> {
+	// Skip entries whose value is `undefined` so a partial override doesn't
+	// clobber a default or global value. Pre-spread filter is required because
+	// `{ ...obj }` propagates explicit-undefined keys.
+	const strip = <T extends object>(x: T | undefined): Partial<T> =>
+		x
+			? (Object.fromEntries(
+					Object.entries(x).filter(([, v]) => v !== undefined),
+				) as Partial<T>)
+			: {};
+
+	const merged: Required<RetryConfig> = {
+		...DEFAULT_RETRY_CONFIG,
+		...strip(globalConfig),
+		...strip(transportConfig),
+	};
+	if (!Number.isInteger(merged.maxAttempts) || merged.maxAttempts < 1) {
+		throw new RoverError(
+			"MAIL_RETRY_CONFIG",
+			`RetryConfig.maxAttempts must be an integer >= 1 (got ${merged.maxAttempts})`,
+			{ hint: "Set retry.maxAttempts to a positive integer." },
+		);
+	}
+	if (
+		typeof merged.baseDelayMs !== "number" ||
+		!Number.isFinite(merged.baseDelayMs) ||
+		merged.baseDelayMs < 0
+	) {
+		throw new RoverError(
+			"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." },
+		);
+	}
+	if (
+		typeof merged.factor !== "number" ||
+		!Number.isFinite(merged.factor) ||
+		merged.factor <= 0
+	) {
+		throw new RoverError(
+			"MAIL_RETRY_CONFIG",
+			`RetryConfig.factor must be a positive finite number (got ${merged.factor})`,
+			{ hint: "Use >= 1 for exponential growth; 1 means constant delay." },
+		);
+	}
+	return merged;
+}

package/src/services/main.ts

@@ -0,0 +1,41 @@
+/**
+ * Default `Mail` singleton — mirror of Adonis's
+ * `import mail from '@adonisjs/mail/services/main'` shape.
+ *
+ * The instance is populated by `RoverProvider.boot()` once the
+ * container has resolved the `Mail` binding. Callers can `import mail`
+ * before boot — the proxy delays method access until `setMail` runs.
+ *
+ *   import mail from '@c9up/rover/services/main'
+ *
+ *   await mail.send((m) => m.to(user.email).subject('Hi').text('Hello'))
+ */
+
+import type { Mail } from "../Mail.js";
+
+let instance: Mail | undefined;
+
+/** @internal Set the resolved singleton (called by RoverProvider.boot). */
+export function setMail(mail: Mail): void {
+	instance = mail;
+}
+
+/** @internal Get the resolved singleton (or `undefined` pre-boot). */
+export function getMail(): Mail | undefined {
+	return instance;
+}
+
+const mail: Mail = new Proxy({} as Mail, {
+	get(_target, prop) {
+		if (!instance) {
+			throw new Error(
+				"[rover] Mail singleton accessed before RoverProvider.boot() ran. " +
+					"Check that `@c9up/rover/provider` is listed in your reamrc.ts providers.",
+			);
+		}
+		const value = Reflect.get(instance, prop, instance);
+		return typeof value === "function" ? value.bind(instance) : value;
+	},
+});
+
+export default mail;