Mail

mkdir -p examples
cp -R node_modules/@db3.ai/app/src/mail/examples/. examples/

npx tsx examples/runMailPreview.ts

import type { MailMessage } from '@db3.ai/app/mail';
import { isEmail } from '@db3.ai/app/validation';

/**
 * Builds an application-owned welcome message with safe plain text and HTML.
 *
 * @param email - Recipient selected by the application, not an arbitrary send API.
 * @param name - Display name rendered as text, never trusted HTML.
 * @returns Message ready for any supported mail transport.
 */
export function welcomeMessage(email: string, name: string): MailMessage {
	if (!isEmail(email)) throw new Error('A valid recipient email is required.');
	const displayName = name.trim();
	if (!displayName || displayName.length > 80 || /[\r\n]/.test(displayName)) throw new Error('Name must be 1–80 characters without line breaks.');
	return {
		to: { email, name: displayName },
		subject: 'Welcome to your notes',
		text: `Hello ${displayName}, your notebook is ready.`,
		html: `<p>Hello ${escapeHtml(displayName)}, your notebook is ready.</p>`,
	};
}

/** Escapes user-controlled text for an HTML text node, not a URL or script. */
function escapeHtml(value: string): string {
	return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#39;');
}

import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { FileMailTransport, Mail } from '@db3.ai/app/mail';
import { welcomeMessage } from './welcomeMessage';

/**
 * Writes, reads and removes a local welcome-email preview without sending email.
 *
 * @returns Selected message contents and the observed validation/recovery outcome.
 */
export async function runMailPreview() {
	const directory = await mkdtemp(join(tmpdir(), 'db3-mail-guide-'));
	try {
		const mail = new Mail({ from: 'Notes <[email protected]>', transport: new FileMailTransport({ directory }) });
		let rejectedEmptyRecipients = false;
		try {
			await mail.send({ to: [], subject: 'Invalid', text: 'This should not be written.' });
		} catch (error) {
			if (!(error instanceof Error) || error.message !== 'Mail requires at least one recipient.') throw error;
			rejectedEmptyRecipients = true;
		}
		const delivery = await mail.send(welcomeMessage('[email protected]', 'Ada & team'));
		if (!delivery.path) throw new Error('The file transport did not return a preview path.');
		const preview = JSON.parse(await readFile(delivery.path, 'utf8'));
		return {
			transport: delivery.transport,
			accepted: delivery.accepted,
			rejectedEmptyRecipients,
			files: (await readdir(directory)).length,
			from: preview.from,
			subject: preview.subject,
			text: preview.text,
			html: preview.html,
		};
	} finally {
		await rm(directory, { recursive: true, force: true });
	}
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
	console.log(JSON.stringify(await runMailPreview(), null, 2));
}

MAIL_TRANSPORT=file
MAIL_FROM="Notes <[email protected]>"
MAIL_FILE_DIRECTORY=storage/mail

# Provider alternatives: set the selected provider and its real server-side key.
# MAIL_TRANSPORT=resend
# RESEND_API_KEY=replace-with-your-key
# MAIL_TRANSPORT=mailgun
# MAILGUN_API_KEY=replace-with-your-key
# MAILGUN_DOMAIN=mg.your-domain.example

import { App } from '@db3.ai/app/server';
import { createMailFromEnv, type Mail } from '@db3.ai/app/mail';

export class Application extends App {
	/** Returns the application-owned mail service, configured once on first use. */
	get mail(): Mail {
		return this.service('mail', () => createMailFromEnv());
	}
}

import { afterEach, expect, it, vi } from 'vitest';
import { createMailFromEnv, Mail, ResendTransport } from '@db3.ai/app/mail';
import { runMailPreview } from '../../examples/runMailPreview';
import { welcomeMessage } from '../../examples/welcomeMessage';

afterEach(() => { vi.unstubAllGlobals(); });

it('rejects invalid recipients before writing, then creates one escaped local preview', async () => {
	expect(await runMailPreview()).toEqual({ transport: 'file', accepted: ['[email protected]'], rejectedEmptyRecipients: true, files: 1, from: 'Notes <[email protected]>', subject: 'Welcome to your notes', text: 'Hello Ada & team, your notebook is ready.', html: '<p>Hello Ada &amp; team, your notebook is ready.</p>' });
	expect(welcomeMessage('[email protected]', '<b>Ada</b>').html).toContain('&lt;b&gt;Ada&lt;/b&gt;');
	expect(() => welcomeMessage('invalid', 'Ada')).toThrow('recipient');
	expect(() => welcomeMessage('[email protected]', 'Ada\nBcc: someone')).toThrow('line breaks');
});

it('reports missing provider configuration without sending, and validates content before HTTP', async () => {
	expect(() => createMailFromEnv({ MAIL_TRANSPORT: 'resend' })).toThrow('RESEND_API_KEY');
	const fetch = vi.fn();
	vi.stubGlobal('fetch', fetch);
	const mail = new Mail({ transport: new ResendTransport({ apiKey: 'test-only' }) });
	await expect(mail.send({ to: '[email protected]', subject: 'Empty' })).rejects.toThrow('text or html');
	expect(fetch).not.toHaveBeenCalled();
});

it('surfaces a provider rejection and allows an explicit successful retry with no automatic retry', async () => {
	const fetch = vi.fn().mockResolvedValueOnce(new Response(JSON.stringify({ message: 'Temporarily unavailable' }), { status: 503 })).mockResolvedValueOnce(new Response(JSON.stringify({ id: 'preview-message' }), { status: 200 }));
	vi.stubGlobal('fetch', fetch);
	const mail = new Mail({ from: 'Notes <[email protected]>', transport: new ResendTransport({ apiKey: 'test-only', baseUrl: 'https://mail-provider.example.test' }) });
	const message = welcomeMessage('[email protected]', 'Ada');
	await expect(mail.send(message)).rejects.toThrow('Temporarily unavailable');
	expect(fetch).toHaveBeenCalledTimes(1);
	expect(await mail.send(message)).toMatchObject({ transport: 'resend', id: 'preview-message', accepted: ['[email protected]'] });
	expect(fetch).toHaveBeenCalledTimes(2);
});

npx vitest run tests/mail/runMailPreview.test.ts
npx tsc --noEmit --target ES2022 --module ESNext --moduleResolution Bundler --types node --skipLibCheck examples/*.ts