@c9up/rover 0.1.7 → 0.1.9

package/src/MessageBuilder.ts

@@ -1,4 +1,8 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { fileURLToPath } from "node:url";
 import { formatAddress } from "./format.js";
+import { RoverError } from "./RoverError.js";
 import { renderFile as renderTemplateFile } from "./templating/SimpleTemplate.js";
 
 export interface MailMessage {
@@ -20,14 +24,83 @@ export interface MailMessage {
 	inReplyTo?: string;
 	/** `References` header — the thread's message ids. */
 	references?: string[];
+	/** SMTP envelope, when it differs from the visible From/To headers. */
+	envelope?: MailEnvelope;
+	/** Body transfer encoding (nodemailer `encoding`). SMTP only. */
+	encoding?: string;
+	/** RFC 2369 `List-*` headers, keyed WITHOUT the `List-` prefix. */
+	list?: Record<string, ListHeader | ListHeader[] | ListHeader[][]>;
+	/** A calendar invitation carried as `text/calendar` (nodemailer `icalEvent`). */
+	icalEvent?: CalendarEvent;
+}
+
+/**
+ * One `List-*` header value: a bare URL, or a URL with a human comment.
+ *
+ * `comment` is REQUIRED in the object form, as it is in nodemailer and
+ * AdonisJS — a URL without a comment is the bare string form.
+ */
+export type ListHeader = string | { url: string; comment: string };
+
+/** How the receiving client should treat the invitation (RFC 5546). */
+export type CalendarEventMethod =
+	| "PUBLISH"
+	| "REQUEST"
+	| "REPLY"
+	| "ADD"
+	| "CANCEL"
+	| "REFRESH"
+	| "COUNTER"
+	| "DECLINECOUNTER";
+
+/** Options shared by the three `icalEvent*` forms (AdonisJS `CalendarEventOptions`). */
+export interface CalendarEventOptions {
+	method?: CalendarEventMethod;
+	filename?: string;
+	encoding?: string;
+}
+
+/**
+ * A calendar invitation. Exactly one source: inline `content`, a `path` read at
+ * {@link MessageBuilder.build} time, or an `href` the provider fetches.
+ */
+export interface CalendarEvent extends CalendarEventOptions {
+	content?: string;
+	path?: string;
+	href?: string;
+}
+
+/** The addresses the mail SERVERS use, as distinct from the visible headers. */
+export interface MailEnvelope {
+	from?: string;
+	to?: string | string[];
+	cc?: string | string[];
+	bcc?: string | string[];
 }
 
 export interface MailAttachment {
 	filename: string;
 	content: Buffer | string;
 	contentType?: string;
-	/** Content-ID for inline (CID) embedding — set via `embedData()`. */
+	/** Content-ID for inline (CID) embedding — set via `embed()` / `embedData()`. */
 	cid?: string;
+	/** Source path, kept so `hasAttachment(file)` can answer by path. */
+	path?: string;
+	/** `Content-Disposition`, when it is not the default for the form used. */
+	contentDisposition?: "attachment" | "inline";
+	/** `Content-Transfer-Encoding` for this part. */
+	encoding?: string;
+	/** Extra part headers. */
+	headers?: Record<string, string | string[]>;
+}
+
+/** What the `attach*` / `embed*` methods accept (AdonisJS `AttachmentOptions`). */
+export interface AttachmentOptions {
+	filename?: string;
+	contentType?: string;
+	contentDisposition?: "attachment" | "inline";
+	encoding?: string;
+	headers?: Record<string, string | string[]>;
 }
 
 /**
@@ -41,6 +114,100 @@ export interface RecipientObject {
 
 export type Recipient = string | RecipientObject;
 
+/** Whether `list` holds `address`, or anything at all when it is omitted. */
+function contains(list: readonly string[], address?: string): boolean {
+	if (address === undefined) return list.length > 0;
+	// Addresses are stored formatted (`"Name" <a@b.c>`), so an assertion on the
+	// bare address has to match inside the display form too.
+	return list.some(
+		(entry) => entry === address || entry.includes(`<${address}>`),
+	);
+}
+
+/**
+ * The parts a transport with no calendar field must send: the declared
+ * attachments, plus the invitation rendered as a `text/calendar` part.
+ *
+ * Only nodemailer has a native `icalEvent`; the provider HTTP APIs carry an
+ * invitation the way every mail client reads it anyway — as an attachment with
+ * the right media type and `method` parameter.
+ */
+export function attachmentsFor(message: MailMessage): MailAttachment[] {
+	const ical = message.icalEvent;
+	if (ical === undefined) return message.attachments;
+	if (ical.content === undefined) {
+		// `icalEventFromUrl` leaves only an href, which nodemailer fetches for
+		// SMTP. An HTTP provider takes the bytes, and silently dropping the
+		// invitation would be worse than saying so.
+		throw new RoverError(
+			"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().",
+			},
+		);
+	}
+	const method = ical.method ?? "PUBLISH";
+	return [
+		...message.attachments,
+		{
+			filename: ical.filename ?? "invite.ics",
+			content: ical.content,
+			contentType: `text/calendar; charset=utf-8; method=${method}`,
+			encoding: ical.encoding,
+		},
+	];
+}
+
+/** Read a file declared by `attach()` / `embed()` / `icalEventFromFile()`. */
+async function readAttachment(path: string, label: string): Promise<Buffer> {
+	try {
+		return await readFile(path);
+	} catch (err) {
+		throw new RoverError(
+			"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().",
+			},
+		);
+	}
+}
+
+/** Every URL inside a `List-*` value, whatever nesting form it was written in. */
+function listUrls(value: ListHeader | ListHeader[] | ListHeader[][]): string[] {
+	if (typeof value === "string") return [value];
+	if (Array.isArray(value)) return value.flatMap((entry) => listUrls(entry));
+	return [value.url];
+}
+
+/** `unsubscribe` → `Unsubscribe`, `unsubscribe-post` → `Unsubscribe-Post`. */
+function titleCaseKey(key: string): string {
+	return key
+		.split("-")
+		.map((part) => (part ? part[0].toUpperCase() + part.slice(1) : part))
+		.join("-");
+}
+
+/** Render one `List-*` value the way RFC 2369 writes it: `<url> (comment)`. */
+function renderListHeader(
+	value: ListHeader | ListHeader[] | ListHeader[][],
+): string {
+	if (typeof value === "string") return `<${value}>`;
+	if (Array.isArray(value)) {
+		return value.map((entry) => renderListHeader(entry)).join(", ");
+	}
+	return value.comment ? `<${value.url}> (${value.comment})` : `<${value.url}>`;
+}
+
+function expect(passed: boolean, expectation: string, actual: unknown): void {
+	if (passed) return;
+	throw new RoverError(
+		"ASSERTION_FAILED",
+		`Expected the message ${expectation}, got ${JSON.stringify(actual)}`,
+	);
+}
+
 export class MessageBuilder {
 	#msg: MailMessage = {
 		from: "",
@@ -52,6 +219,196 @@ export class MessageBuilder {
 		headers: {},
 	};
 	#pendingView: { path: string; data: Record<string, unknown> } | null = null;
+	#pendingTextView: { path: string; data: Record<string, unknown> } | null =
+		null;
+
+	/**
+	 * Render a template as the PLAIN-TEXT body (AdonisJS `textView`).
+	 *
+	 * The counterpart of `htmlView`. A message with only an HTML part scores
+	 * worse with spam filters and is unreadable in a text-only client, which is
+	 * why upstream offers both.
+	 */
+	textView(path: string, data: Record<string, unknown> = {}): this {
+		this.#pendingTextView = { path, data };
+		return this;
+	}
+
+	/**
+	 * Override the SMTP envelope — who the message is really from and to, as
+	 * far as the mail servers are concerned (AdonisJS `envelope`).
+	 *
+	 * Distinct from the `From`/`To` HEADERS: a bounce goes to the envelope
+	 * sender, which is how VERP and mailing lists route failures away from the
+	 * visible author.
+	 */
+	envelope(envelope: MailEnvelope): this {
+		this.#msg.envelope = envelope;
+		return this;
+	}
+
+	/**
+	 * The message as built so far — what the `has*` / `assert*` helpers read.
+	 *
+	 * Exposed because a test asserts against a mail it never sent, and the
+	 * alternative is rebuilding the message just to look at it.
+	 */
+	toObject(): Readonly<MailMessage> {
+		return this.#msg;
+	}
+
+	toJSON(): Readonly<MailMessage> {
+		return this.toObject();
+	}
+
+	// ── Inspection ────────────────────────────────────────────────────────
+	// `has*` answers, `assert*` throws. Both exist because a test reads better
+	// as an assertion and a conditional reads better as a question.
+
+	hasTo(address?: string): boolean {
+		return contains(this.#msg.to, address);
+	}
+	hasCc(address?: string): boolean {
+		return contains(this.#msg.cc, address);
+	}
+	hasBcc(address?: string): boolean {
+		return contains(this.#msg.bcc, address);
+	}
+	hasFrom(address?: string): boolean {
+		return contains(this.#msg.from ? [this.#msg.from] : [], address);
+	}
+	hasReplyTo(address?: string): boolean {
+		return contains(this.#msg.replyTo ? [this.#msg.replyTo] : [], address);
+	}
+	hasSubject(subject?: string): boolean {
+		if (subject === undefined) return this.#msg.subject !== "";
+		return this.#msg.subject === subject;
+	}
+	/**
+	 * Whether the message carries an attachment — any at all, one with this
+	 * filename or source path, or one a predicate accepts (AdonisJS
+	 * `hasAttachment`, whose overloads are the same three).
+	 */
+	hasAttachment(
+		match?: string | URL | ((attachment: MailAttachment) => boolean),
+	): boolean {
+		if (match === undefined) return this.#msg.attachments.length > 0;
+		if (typeof match === "function") return this.#msg.attachments.some(match);
+		const needle = match instanceof URL ? fileURLToPath(match) : match;
+		return this.#msg.attachments.some(
+			(a) => a.filename === needle || a.path === needle,
+		);
+	}
+
+	/**
+	 * Whether `address` is a recipient in ANY field (AdonisJS `hasRecipient`).
+	 * Without one, whether the message has a recipient at all.
+	 */
+	hasRecipient(address?: string): boolean {
+		return this.hasTo(address) || this.hasCc(address) || this.hasBcc(address);
+	}
+
+	/**
+	 * Whether the given text appears in the HTML body or the plain-text one
+	 * (AdonisJS `hasContent`). The field-specific assertions are
+	 * {@link assertHtmlIncludes} and {@link assertTextIncludes}.
+	 */
+	hasContent(needle: string): boolean {
+		return (
+			(this.#msg.html?.includes(needle) ?? false) ||
+			(this.#msg.text?.includes(needle) ?? false)
+		);
+	}
+
+	/** Whether a `List-<key>` header was defined. */
+	hasListHeader(key: string, url?: string): boolean {
+		const value = this.#msg.list?.[key];
+		if (value === undefined) return false;
+		if (url === undefined) return true;
+		return listUrls(value).includes(url);
+	}
+	hasHeader(name: string, value?: string): boolean {
+		const found = this.#msg.headers[name];
+		if (found === undefined) return false;
+		if (value === undefined) return true;
+		return Array.isArray(found) ? found.includes(value) : found === value;
+	}
+
+	assertTo(address: string): void {
+		expect(this.hasTo(address), `to include "${address}"`, this.#msg.to);
+	}
+	assertFrom(address: string): void {
+		expect(this.hasFrom(address), `from to be "${address}"`, this.#msg.from);
+	}
+	assertCc(address: string): void {
+		expect(this.hasCc(address), `cc to include "${address}"`, this.#msg.cc);
+	}
+	assertBcc(address: string): void {
+		expect(this.hasBcc(address), `bcc to include "${address}"`, this.#msg.bcc);
+	}
+	assertReplyTo(address: string): void {
+		expect(
+			this.hasReplyTo(address),
+			`replyTo to be "${address}"`,
+			this.#msg.replyTo,
+		);
+	}
+	assertSubject(subject: string): void {
+		expect(
+			this.hasSubject(subject),
+			`subject to be "${subject}"`,
+			this.#msg.subject,
+		);
+	}
+	assertAttachment(
+		match: string | URL | ((attachment: MailAttachment) => boolean),
+	): void {
+		expect(
+			this.hasAttachment(match),
+			typeof match === "function"
+				? "an attachment matching the predicate"
+				: `an attachment named "${String(match)}"`,
+			this.#msg.attachments.map((a) => a.path ?? a.filename),
+		);
+	}
+
+	/** `address` is a recipient in some field (AdonisJS `assertRecipient`). */
+	assertRecipient(address: string): void {
+		expect(this.hasRecipient(address), `to reach "${address}"`, {
+			to: this.#msg.to,
+			cc: this.#msg.cc,
+			bcc: this.#msg.bcc,
+		});
+	}
+
+	/** The text appears in the HTML or the plain-text body (AdonisJS `assertContent`). */
+	assertContent(needle: string): void {
+		expect(this.hasContent(needle), `to contain "${needle}"`, {
+			html: this.#msg.html,
+			text: this.#msg.text,
+		});
+	}
+	assertHeader(name: string, value?: string): void {
+		expect(
+			this.hasHeader(name, value),
+			value === undefined ? `a "${name}" header` : `${name}: ${value}`,
+			this.#msg.headers[name],
+		);
+	}
+	assertHtmlIncludes(substring: string): void {
+		expect(
+			(this.#msg.html ?? "").includes(substring),
+			`html to include "${substring}"`,
+			this.#msg.html,
+		);
+	}
+	assertTextIncludes(substring: string): void {
+		expect(
+			(this.#msg.text ?? "").includes(substring),
+			`text to include "${substring}"`,
+			this.#msg.text,
+		);
+	}
 
 	from(address: string, name?: string): this {
 		this.#msg.from = formatAddress(address, name);
@@ -121,23 +478,85 @@ export class MessageBuilder {
 		return this;
 	}
 
-	attach(
-		filename: string,
+	/**
+	 * Attach a FILE by path or `file://` URL (AdonisJS `attach`). The bytes are
+	 * read at {@link build} time, so the fluent chain stays synchronous.
+	 *
+	 * The filename defaults to the file's own basename. For bytes you already
+	 * hold, use {@link attachData}.
+	 */
+	attach(file: string | URL, options?: AttachmentOptions): this {
+		const path = file instanceof URL ? fileURLToPath(file) : file;
+		this.#msg.attachments.push({
+			filename: options?.filename ?? basename(path),
+			// Filled in by `build()`; an unread attachment must never ship as an
+			// empty part, so `build()` failing to read is an error, not a warning.
+			content: "",
+			path,
+			contentType: options?.contentType,
+			contentDisposition: options?.contentDisposition,
+			encoding: options?.encoding,
+			headers: options?.headers,
+		});
+		return this;
+	}
+
+	/**
+	 * Attach bytes you already hold (AdonisJS `attachData`). `filename` is
+	 * required — there is no path to take it from.
+	 */
+	attachData(
 		content: Buffer | string,
-		contentType?: string,
+		options: AttachmentOptions & { filename: string },
 	): this {
-		this.#msg.attachments.push({ filename, content, contentType });
+		this.#msg.attachments.push({
+			filename: options.filename,
+			content,
+			contentType: options.contentType,
+			contentDisposition: options.contentDisposition,
+			encoding: options.encoding,
+			headers: options.headers,
+		});
+		return this;
+	}
+
+	/**
+	 * Embed a FILE inline, referenced by `cid:<cid>` in the HTML body (AdonisJS
+	 * `embed`). Read at {@link build} time, like {@link attach}.
+	 */
+	embed(file: string | URL, cid: string, options?: AttachmentOptions): this {
+		const path = file instanceof URL ? fileURLToPath(file) : file;
+		this.#msg.attachments.push({
+			filename: options?.filename ?? basename(path),
+			content: "",
+			path,
+			cid,
+			contentType: options?.contentType,
+			contentDisposition: options?.contentDisposition ?? "inline",
+			encoding: options?.encoding,
+			headers: options?.headers,
+		});
 		return this;
 	}
 
 	/**
-	 * Embed inline content referenced by a Content-ID. Use `cid:<cid>` inside the
-	 * HTML body to reference it. Content-based (rover is agnostic / no-fs): the
-	 * path-based `embed(file, cid)` form from `@adonisjs/mail` is a deliberate
-	 * divergence — pass the bytes directly instead.
+	 * Embed bytes you already hold, referenced by `cid:<cid>` in the HTML body
+	 * (AdonisJS `embedData`).
 	 */
-	embedData(content: Buffer | string, cid: string, contentType?: string): this {
-		this.#msg.attachments.push({ filename: cid, content, contentType, cid });
+	embedData(
+		content: Buffer | string,
+		cid: string,
+		options?: AttachmentOptions,
+	): this {
+		this.#msg.attachments.push({
+			filename: options?.filename ?? cid,
+			content,
+			cid,
+			contentType: options?.contentType,
+			contentDisposition: options?.contentDisposition ?? "inline",
+			encoding: options?.encoding,
+			headers: options?.headers,
+		});
 		return this;
 	}
 
@@ -146,6 +565,105 @@ export class MessageBuilder {
 		return this;
 	}
 
+	/**
+	 * Body transfer encoding (AdonisJS `encoding`) — `7bit`, `base64`,
+	 * `quoted-printable`… SMTP only: the provider HTTP APIs encode the payload
+	 * themselves and expose no equivalent.
+	 */
+	encoding(encoding: string): this {
+		this.#msg.encoding = encoding;
+		return this;
+	}
+
+	// ── RFC 2369 List-* headers ───────────────────────────────────────────
+
+	/**
+	 * Define a `List-<key>` header (AdonisJS `addListHeader`). `key` carries no
+	 * `List-` prefix — `addListHeader('archive', url)` emits `List-Archive`.
+	 * Calling it again for the same key replaces the value.
+	 */
+	addListHeader(
+		key: string,
+		value: ListHeader | ListHeader[] | ListHeader[][],
+	): this {
+		this.#msg.list ??= {};
+		this.#msg.list[key] = value;
+		return this;
+	}
+
+	/**
+	 * `List-Unsubscribe` (AdonisJS `listUnsubscribe`).
+	 *
+	 * `{ oneClick: true }` also emits the RFC 8058 `List-Unsubscribe-Post`
+	 * header. Gmail and Yahoo require BOTH for bulk senders, and only a `https:`
+	 * URL is a valid one-click target — a `mailto:` cannot answer a POST, so
+	 * pairing them is refused rather than silently shipped.
+	 */
+	listUnsubscribe(
+		value: ListHeader | ListHeader[] | ListHeader[][],
+		options?: { oneClick?: boolean },
+	): this {
+		if (options?.oneClick === true) {
+			for (const url of listUrls(value)) {
+				if (!url.toLowerCase().startsWith("http")) {
+					throw new RoverError(
+						"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.",
+						},
+					);
+				}
+			}
+			// A RAW header, not a `List-*` entry: nodemailer wraps every list value
+			// in angle brackets, and `<List-Unsubscribe=One-Click>` is not what
+			// RFC 8058 specifies — receivers would ignore it.
+			this.#msg.headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+		}
+		return this.addListHeader("unsubscribe", value);
+	}
+
+	/** `List-Subscribe` (AdonisJS `listSubscribe`). */
+	listSubscribe(value: ListHeader | ListHeader[] | ListHeader[][]): this {
+		return this.addListHeader("subscribe", value);
+	}
+
+	/** `List-Help` (AdonisJS `listHelp`). */
+	listHelp(value: ListHeader | ListHeader[] | ListHeader[][]): this {
+		return this.addListHeader("help", value);
+	}
+
+	// ── Calendar invitations ──────────────────────────────────────────────
+
+	/**
+	 * Attach a calendar invitation from an ICS string (AdonisJS `icalEvent`).
+	 *
+	 * Named deviation: upstream also accepts a `(calendar: ICalCalendar) => void`
+	 * builder, which is `ical-generator`'s API. rover carries no such
+	 * dependency, so it takes the ICS text — produced by whichever generator you
+	 * prefer. {@link icalEventFromFile} and {@link icalEventFromUrl} are the
+	 * other two upstream forms, unchanged.
+	 */
+	icalEvent(contents: string, options?: CalendarEventOptions): this {
+		this.#msg.icalEvent = { ...options, content: contents };
+		return this;
+	}
+
+	/** Calendar invitation read from a file at {@link build} time (AdonisJS `icalEventFromFile`). */
+	icalEventFromFile(file: string | URL, options?: CalendarEventOptions): this {
+		this.#msg.icalEvent = {
+			...options,
+			path: file instanceof URL ? fileURLToPath(file) : file,
+		};
+		return this;
+	}
+
+	/** Calendar invitation the transport fetches from a URL (AdonisJS `icalEventFromUrl`). */
+	icalEventFromUrl(url: string, options?: CalendarEventOptions): this {
+		this.#msg.icalEvent = { ...options, href: url };
+		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
@@ -172,6 +690,38 @@ export class MessageBuilder {
 			);
 			this.#pendingView = null;
 		}
+		if (this.#pendingTextView !== null) {
+			this.#msg.text = await renderTemplateFile(
+				this.#pendingTextView.path,
+				this.#pendingTextView.data,
+				undefined,
+				viewsRoot,
+			);
+			this.#pendingTextView = null;
+		}
+		// Path-based attachments and invitations are read here, not when they were
+		// declared, so the fluent chain stays synchronous. A read failure raises:
+		// an attachment the recipient expects must never ship as an empty part.
+		for (const attachment of this.#msg.attachments) {
+			if (attachment.path === undefined) continue;
+			attachment.content = await readAttachment(
+				attachment.path,
+				attachment.filename,
+			);
+		}
+		const ical = this.#msg.icalEvent;
+		if (ical?.path !== undefined && ical.content === undefined) {
+			ical.content = (
+				await readAttachment(ical.path, "the calendar event")
+			).toString("utf8");
+		}
+		// `List-*` headers are rendered here, once, rather than in each transport:
+		// every transport already forwards `headers`, and only nodemailer has a
+		// structured `list` field. `#msg.list` stays as the structured record the
+		// `hasListHeader` inspection reads.
+		for (const [key, value] of Object.entries(this.#msg.list ?? {})) {
+			this.#msg.headers[`List-${titleCaseKey(key)}`] = renderListHeader(value);
+		}
 		return this.#msg;
 	}
 }

package/src/RoverProvider.ts

@@ -9,7 +9,7 @@ import { setMail } from "./services/main.js";
  */
 interface RoverContainer {
 	singleton(token: unknown, factory: () => unknown): void;
-	resolve<T = unknown>(token: unknown): T;
+	resolve<T = unknown>(token: unknown): Promise<T>;
 }
 interface RoverConfigStore {
 	get<T = unknown>(key: string): T | undefined;
@@ -23,7 +23,7 @@ export default class RoverProvider {
 	constructor(protected app: RoverAppContext) {}
 
 	register() {
-		this.app.container.singleton(Mail, () => {
+		this.app.container.singleton(Mail, async () => {
 			const config = this.app.config.get<MailConfig>("mail");
 			return new Mail(
 				config ?? {
@@ -36,10 +36,10 @@ export default class RoverProvider {
 					// `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"),
+					queue: await 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"),
+					emitter: await tryResolve<EmitterLike>(this.app, "Emitter"),
 				},
 			);
 		});
@@ -52,7 +52,7 @@ export default class RoverProvider {
 		// 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));
+		setMail(await this.app.container.resolve<Mail>(Mail));
 	}
 
 	async shutdown() {}
@@ -63,9 +63,12 @@ export default class RoverProvider {
  * 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 {
+async function tryResolve<T>(
+	app: RoverAppContext,
+	token: string,
+): Promise<T | undefined> {
 	try {
-		return app.container.resolve<T>(token);
+		return await app.container.resolve<T>(token);
 	} catch {
 		return undefined;
 	}