ajo-kit-mail 0.1.0

package/dist/index.js

@@ -0,0 +1,236 @@
+import { n as Undelivered, r as classify, t as Refused } from "./chunks/errors-CMUvhZvz.js";
+import { n as encode, r as seal, t as domain } from "./chunks/seal-BORkLlJV.js";
+import { configure as configure$1 } from "ajo-kit/mail";
+//#region packages/ajo-kit-mail/src/adapter.ts
+/** Configures ajo-kit-mail and returns a transport for ajo-kit's mail seam. */
+function adapter(options) {
+	configure(options);
+	return async (mail) => {
+		const outcome = await deliver({
+			to: mail.to,
+			subject: mail.subject,
+			text: mail.text,
+			...mail.html !== void 0 && { html: mail.html }
+		});
+		if (!outcome.ok) throw outcome.error;
+	};
+}
+//#endregion
+//#region packages/ajo-kit-mail/src/index.ts
+var CONCURRENCY = 4;
+var TIMEOUT = 1e4;
+var MAXIMUM_TIMER = 2147483647;
+var CONTROL = /[\u0000-\u001f\u007f]/;
+var configuration;
+var production = () => process.env.NODE_ENV === "production";
+var refuse = (code) => {
+	throw new Refused(code);
+};
+var duration = (value) => {
+	const timeout = value ?? TIMEOUT;
+	if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > MAXIMUM_TIMER) refuse("invalid-config");
+	return timeout;
+};
+var concurrency = (value) => {
+	const limit = value ?? CONCURRENCY;
+	if (!Number.isSafeInteger(limit) || limit <= 0) refuse("invalid-config");
+	return limit;
+};
+var label = (value) => {
+	if (typeof value !== "string") return refuse("invalid-config");
+	return value;
+};
+/**
+* Bounded concurrency with no resident timer: a setTimeout exists only while a
+* send is genuinely waiting and is cleared on both paths. The slot is transferred
+* on release rather than decremented, so the limit cannot be overshot by callers
+* arriving in the same tick.
+*/
+var admit = (limit) => {
+	let active = 0;
+	const waiting = [];
+	return {
+		acquire: (deadline) => new Promise((resolve, reject) => {
+			if (active < limit) {
+				active++;
+				resolve();
+				return;
+			}
+			const timer = setTimeout(() => {
+				const index = waiting.indexOf(entry);
+				if (index >= 0) waiting.splice(index, 1);
+				reject(new Undelivered("busy", true));
+			}, Math.max(0, deadline - Date.now()));
+			const entry = () => {
+				clearTimeout(timer);
+				active++;
+				resolve();
+			};
+			waiting.push(entry);
+		}),
+		release: () => {
+			active--;
+			waiting.shift()?.();
+		}
+	};
+};
+/**
+* Races the transport against the envelope signal. The race rejects the caller.
+* it cannot reclaim a socket a third-party transport leaked, which is why both
+* shipped transports honour the signal and close in finally.
+*/
+var bounded = (work, signal) => new Promise((resolve, reject) => {
+	const stop = () => reject(new Undelivered("timeout", true));
+	if (signal.aborted) return stop();
+	signal.addEventListener("abort", stop, { once: true });
+	work.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop));
+});
+var sanitized = (error) => {
+	try {
+		return classify(error);
+	} catch {
+		return new Undelivered("unknown", false);
+	}
+};
+var elapsed = (started) => Math.max(0, Date.now() - started);
+var receipt = (value, fallback) => {
+	try {
+		const id = value?.id;
+		return typeof id === "string" && id && !CONTROL.test(id) ? id : fallback;
+	} catch {
+		return fallback;
+	}
+};
+var report = (current, mail, outcome, started) => {
+	if (!current.observe) return;
+	const event = {
+		id: outcome.ok ? outcome.id : mail?.id ?? "unknown",
+		kind: mail?.kind ?? "mail",
+		transport: current.label,
+		outcome: outcome.ok ? "sent" : outcome.kind,
+		...!outcome.ok && { code: outcome.code },
+		...!outcome.ok && outcome.kind === "undelivered" && { retryable: outcome.retryable },
+		domain: mail ? domain(mail.to.address) : void 0,
+		ms: elapsed(started)
+	};
+	try {
+		current.observe(event);
+	} catch {}
+};
+var refused = (error) => ({
+	ok: false,
+	kind: "refused",
+	code: error.code,
+	error
+});
+var undelivered = (error) => {
+	const failure = sanitized(error);
+	return {
+		ok: false,
+		kind: "undelivered",
+		code: failure.code,
+		retryable: failure.retryable,
+		error: failure
+	};
+};
+var execute = async (message) => {
+	const started = Date.now();
+	const current = configuration;
+	if (!current) return refused(new Refused("no-transport"));
+	let mail;
+	try {
+		mail = seal(message, current.policy);
+	} catch (error) {
+		const outcome = refused(error instanceof Refused ? error : new Refused("invalid-config"));
+		report(current, void 0, outcome, started);
+		return outcome;
+	}
+	try {
+		await current.gate.acquire(mail.deadline);
+	} catch (error) {
+		const outcome = undelivered(error);
+		report(current, mail, outcome, started);
+		return outcome;
+	}
+	let outcome;
+	try {
+		if (mail.signal.aborted || mail.deadline <= Date.now()) throw new Undelivered("timeout", true);
+		const transport = current.transport;
+		outcome = {
+			ok: true,
+			id: receipt(await bounded(Promise.resolve().then(() => transport(mail)), mail.signal), mail.id),
+			transport: current.label
+		};
+	} catch (error) {
+		outcome = undelivered(error);
+	} finally {
+		current.gate.release();
+	}
+	report(current, mail, outcome, started);
+	return outcome;
+};
+/**
+* Installs the transport process-wide and adapts it into ajo-kit's mail seam, so
+* existing send() call sites gain validation and a deadline without being edited.
+* Pure assignment: no socket, no pool, no timer, safe to re-run on every dev reload.
+*/
+function configure(options) {
+	try {
+		if (!options || typeof options !== "object" || typeof options.transport !== "function") refuse("invalid-config");
+		if (options.transport.dev === true && production()) refuse("invalid-config");
+		if (options.transport.verify !== void 0 && typeof options.transport.verify !== "function") refuse("invalid-config");
+		if (options.observe !== void 0 && typeof options.observe !== "function") refuse("invalid-config");
+		const transport = options.transport;
+		configuration = {
+			transport,
+			label: label(options.label ?? transport.label ?? "mail"),
+			policy: {
+				from: options.from,
+				...options.replyTo !== void 0 && { replyTo: options.replyTo },
+				...options.timeout !== void 0 && { timeout: options.timeout },
+				...options.limit !== void 0 && { limit: options.limit }
+			},
+			gate: admit(concurrency(options.concurrency)),
+			...options.observe && { observe: options.observe }
+		};
+		configure$1(async (mail) => {
+			await send(mail);
+		});
+	} catch (error) {
+		if (error instanceof Refused) throw error;
+		throw new Refused("invalid-config");
+	}
+}
+/** Validates, delivers once inside the deadline, reports the outcome. Never throws. */
+async function deliver(message) {
+	try {
+		return await execute(message);
+	} catch (error) {
+		return undelivered(error);
+	}
+}
+/** Delivers once and resolves to the message id or throws Refused or Undelivered. */
+async function send(message) {
+	const outcome = await deliver(message);
+	if (!outcome.ok) throw outcome.error;
+	return outcome.id;
+}
+/** Runs the transport's optional credential check. Opens a connection only when called. */
+async function probe(timeout) {
+	try {
+		const current = configuration;
+		if (!current) throw new Refused("no-transport");
+		const verify = current.transport.verify;
+		if (!verify) return { ok: true };
+		const signal = AbortSignal.timeout(duration(timeout ?? current.policy.timeout));
+		await bounded(Promise.resolve().then(() => verify.call(current.transport, signal)), signal);
+		return { ok: true };
+	} catch (error) {
+		return {
+			ok: false,
+			error: error instanceof Refused ? error : sanitized(error)
+		};
+	}
+}
+//#endregion
+export { Refused, Undelivered, adapter, classify, configure, deliver, domain, encode, probe, seal, send };

package/dist/smtp.js

@@ -0,0 +1,195 @@
+import { n as Undelivered, t as Refused } from "./chunks/errors-CMUvhZvz.js";
+import { Socket, isIP } from "node:net";
+import { connect } from "node:tls";
+import { createTransport } from "nodemailer";
+//#region packages/ajo-kit-mail/src/smtp.ts
+var CONTROL = /[\u0000-\u001f\u007f]/;
+var VERIFY_TIMEOUT = 1e4;
+var configuration = (options) => {
+	if (!options || typeof options !== "object") throw new Refused("invalid-config");
+	const host = options.host;
+	const port = options.port ?? 587;
+	const implicit = options.implicit ?? false;
+	const user = options.user;
+	const pass = options.pass;
+	const name = options.name;
+	if (typeof host !== "string" || !host || host !== host.trim() || host.length > 253 || CONTROL.test(host) || /\s/.test(host) || !Number.isInteger(port) || port < 1 || port > 65535 || typeof implicit !== "boolean" || user !== void 0 && (typeof user !== "string" || !user) || pass !== void 0 && (typeof pass !== "string" || !pass) || user === void 0 !== (pass === void 0) || name !== void 0 && (typeof name !== "string" || !name || name !== name.trim() || name.length > 253 || CONTROL.test(name) || /\s/.test(name))) throw new Refused("invalid-config");
+	return Object.freeze({
+		host,
+		port,
+		implicit,
+		...user !== void 0 && {
+			user,
+			pass
+		},
+		...name !== void 0 && { name }
+	});
+};
+var connector = (config, own) => (_options, callback) => {
+	let settled = false;
+	let socket;
+	const finish = (error, options) => {
+		if (settled) return;
+		settled = true;
+		callback(error, options);
+	};
+	if (config.implicit) socket = connect({
+		host: config.host,
+		port: config.port,
+		...isIP(config.host) === 0 && { servername: config.host },
+		rejectUnauthorized: true,
+		minVersion: "TLSv1.2"
+	}, () => finish(null, {
+		connection: socket,
+		secured: true
+	}));
+	else {
+		socket = new Socket();
+		socket.connect(config.port, config.host, () => finish(null, { connection: socket }));
+	}
+	own(socket);
+	socket.on("error", () => {
+		if (!settled) finish(Object.assign(/* @__PURE__ */ new Error("SMTP connection failed"), { code: config.implicit ? "ETLS" : "ESOCKET" }));
+	});
+};
+var settings = (config, name, timeout, own) => ({
+	host: config.host,
+	port: config.port,
+	secure: config.implicit,
+	pool: false,
+	requireTLS: !config.implicit,
+	ignoreTLS: false,
+	opportunisticTLS: false,
+	name,
+	...config.user !== void 0 && { auth: {
+		user: config.user,
+		pass: config.pass
+	} },
+	connectionTimeout: timeout,
+	greetingTimeout: timeout,
+	socketTimeout: timeout,
+	dnsTimeout: timeout,
+	tls: {
+		rejectUnauthorized: true,
+		minVersion: "TLSv1.2"
+	},
+	disableFileAccess: true,
+	disableUrlAccess: true,
+	logger: false,
+	debug: false,
+	transactionLog: false,
+	getSocket: connector(config, own)
+});
+var remaining = (deadline) => {
+	const value = Math.ceil(deadline - Date.now());
+	return value > 0 ? Math.min(value, 2147483647) : 0;
+};
+var bounded = (work, signal, close) => new Promise((resolve, reject) => {
+	const stop = () => {
+		close();
+		reject(new Undelivered("timeout", true));
+	};
+	if (signal.aborted) return stop();
+	signal.addEventListener("abort", stop, { once: true });
+	work.then((value) => {
+		signal.removeEventListener("abort", stop);
+		resolve(value);
+	}, (error) => {
+		signal.removeEventListener("abort", stop);
+		reject(error);
+	});
+});
+/** SMTP reply-code mapping. Note the parentheses: this is where a precedence bug hides. */
+var reply = (error) => {
+	const value = error ?? {};
+	const code = typeof value.code === "string" ? value.code : "";
+	const command = typeof value.command === "string" ? value.command : "";
+	const status = typeof value.responseCode === "number" ? value.responseCode : void 0;
+	const hint = status === void 0 ? void 0 : `smtp ${status}`;
+	if (code === "EAUTH" || status === 530 || status === 535) return new Undelivered("auth", false, hint);
+	if (code === "ETLS" || code.startsWith("ERR_TLS") || code.includes("CERT")) return new Undelivered("tls", false);
+	if (code === "ESOCKET" && command === "CONN") return new Undelivered("tls", false);
+	if (code === "ETIMEDOUT" || code === "ECONNECTION" && status === void 0) return new Undelivered("timeout", true);
+	if (status !== void 0 && status >= 400 && status < 500) return new Undelivered("throttled", true, hint);
+	if (status !== void 0 && status >= 500) return new Undelivered("rejected", false, hint);
+	if (code) return new Undelivered("connection", true);
+	return new Undelivered("unknown", false);
+};
+/**
+* Creates a one-connection-per-message SMTP transport with mandatory verified
+* TLS, deadline-derived socket timeouts and sanitized failure classifications.
+*/
+function smtp(options) {
+	const config = configuration(options);
+	const send = async (mail) => {
+		const timeout = remaining(mail.deadline);
+		if (!timeout) throw new Undelivered("timeout", true);
+		let mailer;
+		let socket;
+		let closed = false;
+		const own = (value) => {
+			socket = value;
+			if (closed) value.destroy();
+		};
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			socket?.destroy();
+			mailer?.close();
+		};
+		try {
+			mailer = createTransport(settings(config, config.name ?? mail.from.address.slice(mail.from.address.lastIndexOf("@") + 1), timeout, own));
+			const result = await bounded(mailer.sendMail({
+				from: mail.from,
+				to: mail.to,
+				...mail.replyTo && { replyTo: mail.replyTo },
+				subject: mail.subject,
+				text: mail.text,
+				...mail.html !== void 0 && { html: mail.html },
+				envelope: {
+					from: mail.from.address,
+					to: [mail.to.address]
+				},
+				disableFileAccess: true,
+				disableUrlAccess: true
+			}), mail.signal, close);
+			return typeof result.messageId === "string" && result.messageId ? { id: result.messageId } : void 0;
+		} catch (error) {
+			if (error instanceof Undelivered) throw error;
+			throw reply(error);
+		} finally {
+			close();
+		}
+	};
+	const verify = async (signal) => {
+		if (signal.aborted) throw new Undelivered("timeout", true);
+		let mailer;
+		let socket;
+		let closed = false;
+		const own = (value) => {
+			socket = value;
+			if (closed) value.destroy();
+		};
+		const close = () => {
+			if (closed) return;
+			closed = true;
+			socket?.destroy();
+			mailer?.close();
+		};
+		try {
+			mailer = createTransport(settings(config, config.name ?? config.host, VERIFY_TIMEOUT, own));
+			await bounded(mailer.verify(), signal, close);
+		} catch (error) {
+			if (error instanceof Undelivered) throw error;
+			throw reply(error);
+		} finally {
+			close();
+		}
+	};
+	return Object.assign(send, {
+		label: "smtp",
+		verify
+	});
+}
+//#endregion
+export { smtp };

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "ajo-kit-mail",
+  "version": "0.1.0",
+  "description": "Validated mail contract and pluggable transports for ajo-kit applications",
+  "type": "module",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "kit": {
+    "serverOnly": true
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./http": {
+      "types": "./src/http.ts",
+      "default": "./dist/http.js",
+      "import": "./dist/http.js"
+    },
+    "./smtp": {
+      "types": "./src/smtp.ts",
+      "default": "./dist/smtp.js",
+      "import": "./dist/smtp.js"
+    },
+    "./capture": {
+      "types": "./src/capture.ts",
+      "default": "./dist/capture.js",
+      "import": "./dist/capture.js"
+    }
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^7.0.0",
+    "nodemailer": "^7.0.0",
+    "ajo-kit": "^0.1.2"
+  },
+  "peerDependencies": {
+    "nodemailer": "^7.0.0",
+    "ajo-kit": "^0.1.2"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "keywords": [
+    "ajo",
+    "email",
+    "mail",
+    "security"
+  ],
+  "author": "Cristian Falcone",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cristianfalcone/ajo-kit.git",
+    "directory": "packages/ajo-kit-mail"
+  },
+  "bugs": {
+    "url": "https://github.com/cristianfalcone/ajo-kit/issues"
+  },
+  "homepage": "https://github.com/cristianfalcone/ajo-kit/tree/main/packages/ajo-kit-mail#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm -w exec tsx scripts/package-build.ts ajo-kit-mail",
+    "test": "pnpm -w exec vitest run packages/ajo-kit-mail/tests"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,18 @@
+import type { Transport as KitTransport } from 'ajo-kit/mail'
+import { configure, deliver, type Options } from './index'
+
+/** Configures ajo-kit-mail and returns a transport for ajo-kit's mail seam. */
+export function adapter(options: Options): KitTransport {
+	configure(options)
+
+	return async mail => {
+		const outcome = await deliver({
+			to: mail.to,
+			subject: mail.subject,
+			text: mail.text,
+			...(mail.html !== undefined && { html: mail.html }),
+		})
+
+		if (!outcome.ok) throw outcome.error
+	}
+}

package/src/capture.ts

@@ -0,0 +1,121 @@
+import { Undelivered, type DeliveryCode } from './errors'
+import { domain, type Sealed } from './seal'
+import type { Transport } from './index'
+
+/** In-memory transport for tests and development. Refused in production by configure(). */
+export interface Capture extends Transport {
+	/** Bounded ring: at most `keep` envelopes, oldest dropped. Live reset links do not accumulate. */
+	readonly messages: readonly Sealed[]
+	/** Returns the newest retained envelope. */
+	last(): Sealed | undefined
+	/** Returns the first absolute URL in the last text body that matches the optional pattern. */
+	link(pattern?: RegExp): string | undefined
+	/** Fails the next `times` deliveries with `code`, to drive the failure paths. */
+	fail(code: DeliveryCode, times?: number): void
+	/** Removes retained envelopes and any pending injected failure. */
+	clear(): void
+}
+
+/** Settings for an in-memory capture transport. */
+export interface CaptureOptions {
+	/** Print id, kind and recipient domain only. The body is unreachable from the log path. */
+	log?: boolean
+	/** Retained envelopes. Default 50. */
+	keep?: number
+}
+
+type Failure = {
+	readonly code: DeliveryCode
+	remaining: number
+}
+
+const DELIVERY: ReadonlySet<DeliveryCode> = new Set([
+	'timeout',
+	'busy',
+	'connection',
+	'tls',
+	'auth',
+	'rejected',
+	'throttled',
+	'unavailable',
+	'unknown',
+])
+const RETRYABLE: ReadonlySet<DeliveryCode> = new Set([
+	'timeout',
+	'busy',
+	'connection',
+	'throttled',
+	'unavailable',
+])
+const LINKS = /https?:\/\/[^\s<>"'`]+/g
+
+const count = (value: number | undefined) => {
+	const keep = value ?? 50
+	if (!Number.isSafeInteger(keep) || keep < 0) {
+		throw new RangeError('Capture keep must be a non-negative safe integer')
+	}
+	return keep
+}
+
+const repetitions = (value: number | undefined) => {
+	const times = value ?? 1
+	if (!Number.isSafeInteger(times) || times <= 0) {
+		throw new RangeError('Capture failure count must be a positive safe integer')
+	}
+	return times
+}
+
+const matches = (pattern: RegExp, value: string) => {
+	const lastIndex = pattern.lastIndex
+	pattern.lastIndex = 0
+
+	try {
+		return pattern.test(value)
+	} finally {
+		pattern.lastIndex = lastIndex
+	}
+}
+
+/** Creates a bounded in-memory transport for development and deterministic tests. */
+export function capture(options: CaptureOptions = {}): Capture {
+	const keep = count(options.keep)
+	const messages: Sealed[] = []
+	let failure: Failure | undefined
+
+	const transport = async (mail: Sealed) => {
+		if (failure) {
+			const current = failure
+			current.remaining--
+			if (current.remaining === 0) failure = undefined
+			throw new Undelivered(current.code, RETRYABLE.has(current.code))
+		}
+
+		messages.push(mail)
+		if (messages.length > keep) messages.splice(0, messages.length - keep)
+
+		if (options.log) {
+			console.log(`[mail] ${mail.id} ${mail.kind} @${domain(mail.to.address)} sent 0ms`)
+		}
+
+		return { id: mail.id }
+	}
+
+	return Object.assign(transport, {
+		label: 'capture',
+		dev: true,
+		messages,
+		last: () => messages.at(-1),
+		link: (pattern?: RegExp) => {
+			const links = messages.at(-1)?.text.match(LINKS) ?? []
+			return pattern ? links.find(value => matches(pattern, value)) : links[0]
+		},
+		fail: (code: DeliveryCode, times?: number) => {
+			if (!DELIVERY.has(code)) throw new RangeError('Unknown capture delivery code')
+			failure = { code, remaining: repetitions(times) }
+		},
+		clear: () => {
+			messages.length = 0
+			failure = undefined
+		},
+	})
+}