ajo-kit-mail 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2022-2026, Cristian Falcone
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# ajo-kit-mail
+
+Validated mail contract and pluggable transports for `ajo-kit` apps.
+
+Includes:
+
+- one validation boundary: every message is sealed before any transport sees it
+- delivery with a hard deadline, bounded concurrency and a single attempt
+- transports: SMTP (mandatory verified TLS), JSON HTTP providers, in-memory capture
+- sanitized failures: classified codes and retry verdicts, never provider prose
+- credential-free delivery events for observability
+- integration with `ajo-kit`'s mail seam, so existing `send()` call sites gain
+  validation without being edited
+
+## Install
+
+```bash
+pnpm add ajo-kit-mail
+```
+
+`ajo-kit-mail` requires `ajo-kit` as a peer dependency.
+
+`nodemailer` is an optional peer used only by the SMTP transport. HTTP and
+capture consumers do not install it:
+
+```bash
+pnpm add nodemailer # only when using smtp()
+```
+
+## Setup
+
+Configure a transport once during app boot. `configure()` also adapts the
+package into `ajo-kit`'s mail seam, so code importing `send` from
+`ajo-kit/mail` delivers through it with validation and a deadline.
+
+```ts
+import { configure } from 'ajo-kit-mail'
+import { smtp } from 'ajo-kit-mail/smtp'
+
+configure({
+	transport: smtp({ host: 'smtp.example.com', user: 'apikey', pass: process.env.SMTP_PASS }),
+	from: 'Ajo <noreply@example.com>',
+})
+```
+
+Development uses `capture()`; `configure()` refuses dev transports when
+`NODE_ENV` is `production`.
+
+## Sending
+
+```ts
+import { deliver, send } from 'ajo-kit-mail'
+
+// Resolves to the message id, throws Refused or Undelivered.
+await send({ to: 'user@example.com', subject: 'Reset', text: body })
+
+// Never throws: a discriminated Outcome for code that branches on failure.
+const outcome = await deliver({
+	to: { address: 'user@example.com', name: 'User' },
+	subject: 'Reset your password',
+	text: body,
+	kind: 'reset',           // label for events: 'reset', 'verify', 'invite'
+	key: token.id,           // idempotency key, forwarded to providers that accept one
+	expires: token.expires,  // hard deadline: nothing is attempted past it
+})
+
+if (!outcome.ok && outcome.kind === 'undelivered' && outcome.retryable) retry()
+```
+
+A message has exactly one recipient — credential mail must not fan out. The
+sealed envelope carries an absolute deadline (default 10 s, capped by
+`expires`) and an `AbortSignal` transports must honour.
+
+`probe()` runs the transport's optional credential check without sending:
+
+```ts
+const status = await probe() // { ok: true } | { ok: false, error }
+```
+
+## Transports
+
+### `smtp(options)`
+
+One connection per message over nodemailer, with mandatory verified TLS:
+STARTTLS is required on port 587 (`implicit: true` for 465), the certificate
+is verified, and the floor is TLS 1.2. None of that is configurable, and
+there is no credential URL form — discrete `host`/`user`/`pass` fields only.
+Local development uses `capture()` instead of an insecure flag.
+
+### `http(options)`
+
+A JSON provider over global `fetch`. The body mapping is the only
+provider-specific code an app writes:
+
+```ts
+import { http } from 'ajo-kit-mail/http'
+
+const transport = http({
+	url: 'https://api.provider.example/send',
+	headers: () => ({ Authorization: `Bearer ${read()}` }), // factory: read per send
+	body: mail => ({ from: mail.from.address, to: mail.to.address, subject: mail.subject, text: mail.text }),
+	id: payload => (payload as { id?: string }).id,
+})
+```
+
+The message `key` is forwarded as `Idempotency-Key`. Success bodies are read
+up to 64 KiB; failure bodies are cancelled unread.
+
+### `capture(options?)`
+
+Bounded in-memory transport for tests and development — refused in
+production:
+
+```ts
+import { capture } from 'ajo-kit-mail/capture'
+
+const mailbox = capture()
+configure({ transport: mailbox, from: 'noreply@example.com' })
+
+await send({ to: 'user@example.com', subject: 'Reset', text: `Open ${url}` })
+mailbox.link(/\/reset\//)          // first matching URL in the last body
+mailbox.fail('throttled', 2)       // drive the failure paths deterministically
+```
+
+### Custom transports
+
+A transport is a function from a `Sealed` envelope to an optional `Receipt`.
+It can only receive validated input — `seal()` is the sole constructor of
+`Sealed`. Reuse `classify()` so failures inherit the sanitization guarantee:
+
+```ts
+import { classify, type Transport } from 'ajo-kit-mail'
+
+const transport: Transport = async mail => {
+	try {
+		await provider.send(/* ... */)
+	} catch (error) {
+		throw classify(error) // shape only: never message, cause or response bodies
+	}
+}
+```
+
+## Outcomes and errors
+
+`Refused` means the message or configuration was rejected before any network
+work: `invalid-recipient`, `empty-body`, `too-large`, `expired`, and friends.
+`Undelivered` means a transport accepted the envelope and the attempt failed,
+with a classification (`timeout`, `auth`, `tls`, `throttled`, `rejected`, …),
+a `retryable` verdict and at most a protocol status hint (`smtp 451`). Both
+extend `ajo-kit`'s `Failure`; neither ever echoes an address, a subject, a
+body or provider prose.
+
+Validation limits: subject ≤ 255 bytes, body ≤ 256 KiB (hard maximum),
+control characters rejected everywhere — the boundary that stops header
+injection.
+
+## Observability
+
+```ts
+configure({
+	transport,
+	from: 'noreply@example.com',
+	concurrency: 4, // backpressure, not throughput
+	observe: delivery => log(delivery), // { id, kind, transport, outcome, code?, retryable?, domain?, ms }
+})
+```
+
+Events are body-free by construction: the recipient appears as its domain
+only, and no field can hold a credential. A throwing observer never changes
+delivery semantics.

package/dist/capture.js

@@ -0,0 +1,82 @@
+import { n as Undelivered } from "./chunks/errors-CMUvhZvz.js";
+import { t as domain } from "./chunks/seal-BORkLlJV.js";
+//#region packages/ajo-kit-mail/src/capture.ts
+var DELIVERY = new Set([
+	"timeout",
+	"busy",
+	"connection",
+	"tls",
+	"auth",
+	"rejected",
+	"throttled",
+	"unavailable",
+	"unknown"
+]);
+var RETRYABLE = new Set([
+	"timeout",
+	"busy",
+	"connection",
+	"throttled",
+	"unavailable"
+]);
+var LINKS = /https?:\/\/[^\s<>"'`]+/g;
+var count = (value) => {
+	const keep = value ?? 50;
+	if (!Number.isSafeInteger(keep) || keep < 0) throw new RangeError("Capture keep must be a non-negative safe integer");
+	return keep;
+};
+var repetitions = (value) => {
+	const times = value ?? 1;
+	if (!Number.isSafeInteger(times) || times <= 0) throw new RangeError("Capture failure count must be a positive safe integer");
+	return times;
+};
+var matches = (pattern, value) => {
+	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. */
+function capture(options = {}) {
+	const keep = count(options.keep);
+	const messages = [];
+	let failure;
+	const transport = async (mail) => {
+		if (failure) {
+			const current = failure;
+			current.remaining--;
+			if (current.remaining === 0) failure = void 0;
+			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) => {
+			const links = messages.at(-1)?.text.match(LINKS) ?? [];
+			return pattern ? links.find((value) => matches(pattern, value)) : links[0];
+		},
+		fail: (code, times) => {
+			if (!DELIVERY.has(code)) throw new RangeError("Unknown capture delivery code");
+			failure = {
+				code,
+				remaining: repetitions(times)
+			};
+		},
+		clear: () => {
+			messages.length = 0;
+			failure = void 0;
+		}
+	});
+}
+//#endregion
+export { capture };

package/dist/chunks/errors-CMUvhZvz.js

@@ -0,0 +1,97 @@
+import { Failure } from "ajo-kit";
+//#region packages/ajo-kit-mail/src/errors.ts
+var CONFIGURATION = new Set([
+	"no-transport",
+	"invalid-config",
+	"invalid-sender"
+]);
+var DELIVERY = new Set([
+	"timeout",
+	"busy",
+	"connection",
+	"tls",
+	"auth",
+	"rejected",
+	"throttled",
+	"unavailable",
+	"unknown"
+]);
+var RETRYABLE = new Set([
+	"timeout",
+	"busy",
+	"connection",
+	"throttled",
+	"unavailable"
+]);
+/**
+* The message or the configuration was rejected. Nothing was sent and no provider
+* was contacted. Extends Failure with a deliberate status so normalize() cannot
+* inherit a provider status and server.tsx never console.error()s the object.
+* The message is the code and never echoes an input value.
+*/
+var Refused = class extends Failure {
+	code;
+	constructor(code) {
+		super(CONFIGURATION.has(code) ? 500 : 422, `Mail refused: ${code}`);
+		this.name = "Refused";
+		this.code = code;
+		if (CONFIGURATION.has(code)) console.error(`[mail] refused: ${code}`);
+	}
+};
+/**
+* A transport accepted the envelope and the attempt failed. Carries a
+* classification, a retry verdict and at most a protocol status. Never provider
+* prose, never a recipient, never a subject, never a body, never a cause.
+*/
+var Undelivered = class extends Failure {
+	code;
+	retryable;
+	/** Protocol status only: 'smtp 451', 'status 429'. */
+	hint;
+	constructor(code, retryable, hint) {
+		super(502, `Mail delivery failed: ${code}`);
+		this.name = "Undelivered";
+		this.code = code;
+		this.retryable = retryable;
+		this.hint = hint;
+	}
+};
+var protocol = (value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599 ? value : void 0;
+/**
+* Reduces any thrown value to an Undelivered by reading shape only: name, code,
+* responseCode/status/statusCode. Never .message, never .cause, never .response,
+* never .envelope. Exported so a third-party transport inherits the guarantee
+* instead of reimplementing it.
+*/
+function classify(error) {
+	const value = error !== null && (typeof error === "object" || typeof error === "function") ? error : {};
+	const rawName = value.name;
+	const rawCode = value.code;
+	const rawResponseCode = value.responseCode;
+	const rawStatus = value.status;
+	const rawStatusCode = value.statusCode;
+	const name = typeof rawName === "string" ? rawName : "";
+	const code = typeof rawCode === "string" ? rawCode : "";
+	const responseCode = protocol(rawResponseCode);
+	const directStatus = protocol(rawStatus);
+	const statusCode = protocol(rawStatusCode);
+	const status = responseCode ?? directStatus ?? statusCode;
+	const hint = status === void 0 ? void 0 : `${responseCode === void 0 ? "status" : "smtp"} ${status}`;
+	const undelivered = (delivery, retryable, detail) => new Undelivered(delivery, retryable, detail);
+	if (name === "Undelivered" && DELIVERY.has(code)) {
+		const delivery = code;
+		return undelivered(delivery, RETRYABLE.has(delivery));
+	}
+	if (code === "EAUTH" || responseCode === 530 || responseCode === 535 || responseCode === void 0 && (status === 401 || status === 403)) return undelivered("auth", false, hint);
+	if (code === "ETLS" || code.startsWith("ERR_TLS") || code.includes("CERT")) return undelivered("tls", false);
+	if (name === "AbortError" || name === "TimeoutError" || code === "ETIMEDOUT" || code === "ECONNECTION" && status === void 0 || responseCode === void 0 && status === 408) return undelivered("timeout", true);
+	if (responseCode !== void 0 && responseCode >= 400 && responseCode < 500) return undelivered("throttled", true, hint);
+	if (responseCode !== void 0 && responseCode >= 500) return undelivered("rejected", false, hint);
+	if (status === 429) return undelivered("throttled", true, hint);
+	if (status !== void 0 && status >= 500) return undelivered("unavailable", true, hint);
+	if (status !== void 0 && status >= 400) return undelivered("rejected", false, hint);
+	if (code) return undelivered("connection", true);
+	return undelivered("unknown", false);
+}
+//#endregion
+export { Undelivered as n, classify as r, Refused as t };

package/dist/chunks/seal-BORkLlJV.js

@@ -0,0 +1,117 @@
+import { t as Refused } from "./errors-CMUvhZvz.js";
+import { randomUUID } from "node:crypto";
+import { Buffer } from "node:buffer";
+//#region packages/ajo-kit-mail/src/seal.ts
+var CONTROL = /[\u0000-\u001f\u007f]/;
+var ADDRESS = /^(?=.{3,254}$)[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i;
+var NAME = /^[^"<>,;:\\\u0000-\u001f\u007f]{1,128}$/;
+var KEY = /^[A-Za-z0-9._:-]{1,128}$/;
+var KIND = /^[a-z][a-z0-9-]{0,31}$/;
+var ADDRESS_BYTES = 254;
+var SUBJECT_BYTES = 255;
+var NAME_BYTES = 128;
+var KEY_BYTES = 128;
+var KIND_BYTES = 32;
+var BODY_BYTES = 262144;
+var TIMEOUT = 1e4;
+var WORD_BYTES = 45;
+var bytes = (value) => Buffer.byteLength(value, "utf8");
+var refusal = (code) => {
+	throw new Refused(code);
+};
+var mailbox = (recipient, code) => {
+	const address = typeof recipient === "string" ? recipient : recipient?.address;
+	const name = typeof recipient === "string" ? void 0 : recipient?.name;
+	if (typeof address !== "string") refusal(code);
+	if (CONTROL.test(address) || !ADDRESS.test(address) || bytes(address) > ADDRESS_BYTES) refusal(code);
+	if (name !== void 0) {
+		if (typeof name !== "string" || CONTROL.test(name) || !NAME.test(name) || bytes(name) > NAME_BYTES) refusal("invalid-name");
+	}
+	return Object.freeze({
+		address,
+		...name !== void 0 && { name }
+	});
+};
+var duration = (value) => {
+	const timeout = value ?? TIMEOUT;
+	if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 2147483647) refusal("invalid-config");
+	return timeout;
+};
+var bodyLimit = (value) => {
+	const limit = value ?? BODY_BYTES;
+	if (!Number.isSafeInteger(limit) || limit <= 0 || limit > BODY_BYTES) refusal("invalid-config");
+	return limit;
+};
+var expiry = (value) => {
+	if (value === void 0) return Infinity;
+	const time = value instanceof Date ? value.getTime() : value;
+	return typeof time === "number" && Number.isFinite(time) ? time : refusal("expired");
+};
+/** Validates once, on the way in. Every later stage consumes only the result. */
+function seal(message, policy) {
+	if (!message || typeof message !== "object" || !policy || typeof policy !== "object") refusal("invalid-config");
+	const toRecipient = message.to;
+	const subject = message.subject;
+	const text = message.text;
+	const html = message.html;
+	const fromRecipient = message.from;
+	const messageReply = message.replyTo;
+	const rawKind = message.kind;
+	const key = message.key;
+	const expires = message.expires;
+	const policyFrom = policy.from;
+	const policyReply = policy.replyTo;
+	const policyTimeout = policy.timeout;
+	const policyLimit = policy.limit;
+	const deadline = Math.min(Date.now() + duration(policyTimeout), expiry(expires));
+	const limit = bodyLimit(policyLimit);
+	const from = mailbox(fromRecipient ?? policyFrom, "invalid-sender");
+	const to = mailbox(toRecipient, "invalid-recipient");
+	const replyRecipient = messageReply ?? policyReply;
+	const replyTo = replyRecipient === void 0 ? void 0 : mailbox(replyRecipient, "invalid-recipient");
+	const kind = rawKind ?? "mail";
+	if (typeof subject !== "string" || !subject || CONTROL.test(subject) || bytes(subject) > SUBJECT_BYTES) refusal("invalid-subject");
+	if (typeof kind !== "string" || CONTROL.test(kind) || !KIND.test(kind) || bytes(kind) > KIND_BYTES) refusal("invalid-kind");
+	if (key !== void 0 && (typeof key !== "string" || CONTROL.test(key) || !KEY.test(key) || bytes(key) > KEY_BYTES)) refusal("invalid-key");
+	if (typeof text !== "string" || html !== void 0 && typeof html !== "string" || !text && !html) refusal("empty-body");
+	if (bytes(text) + bytes(html ?? "") > limit) refusal("too-large");
+	if (deadline <= Date.now()) refusal("expired");
+	const signal = AbortSignal.timeout(Math.max(0, Math.ceil(deadline - Date.now())));
+	return Object.freeze({
+		id: randomUUID(),
+		kind,
+		from,
+		to,
+		...replyTo && { replyTo },
+		subject,
+		text,
+		...html !== void 0 && { html },
+		...key !== void 0 && { key },
+		deadline,
+		signal
+	});
+}
+/** Returns the recipient domain, the only address part safe for logs. */
+function domain(address) {
+	return address.slice(address.lastIndexOf("@") + 1).toLowerCase();
+}
+/** Encodes and folds a value into RFC 2047 encoded-words of at most 75 characters. */
+function encode(value) {
+	const chunks = [];
+	let chunk = "";
+	let size = 0;
+	for (const character of value) {
+		const width = bytes(character);
+		if (size + width > WORD_BYTES && chunk) {
+			chunks.push(chunk);
+			chunk = "";
+			size = 0;
+		}
+		chunk += character;
+		size += width;
+	}
+	chunks.push(chunk);
+	return chunks.map((part) => `=?UTF-8?B?${Buffer.from(part, "utf8").toString("base64")}?=`).join("\r\n ");
+}
+//#endregion
+export { encode as n, seal as r, domain as t };

package/dist/http.js

@@ -0,0 +1,65 @@
+import { r as classify } from "./chunks/errors-CMUvhZvz.js";
+//#region packages/ajo-kit-mail/src/http.ts
+var RESPONSE_BYTES = 65536;
+var payload = async (response) => {
+	if (!response.body) return;
+	const reader = response.body.getReader();
+	const bytes = new Uint8Array(RESPONSE_BYTES);
+	let size = 0;
+	let complete = false;
+	try {
+		while (size < RESPONSE_BYTES) {
+			const chunk = await reader.read();
+			if (chunk.done) {
+				complete = true;
+				break;
+			}
+			const length = Math.min(chunk.value.byteLength, RESPONSE_BYTES - size);
+			bytes.set(chunk.value.subarray(0, length), size);
+			size += length;
+		}
+	} finally {
+		if (complete) reader.releaseLock();
+		else await reader.cancel().catch(() => {});
+	}
+	if (!size) return;
+	return JSON.parse(new TextDecoder().decode(bytes.subarray(0, size)));
+};
+/**
+* Creates a provider transport over global fetch. Non-success bodies are
+* cancelled unread, while success bodies are retained only up to 64 KiB.
+*/
+function http(options) {
+	const transport = async (mail) => {
+		let response;
+		try {
+			const configured = typeof options.headers === "function" ? options.headers() : options.headers;
+			const headers = new Headers(configured);
+			if (!headers.has("Content-Type")) headers.set("Content-Type", "application/json");
+			headers.delete("Idempotency-Key");
+			if (mail.key !== void 0) headers.set("Idempotency-Key", mail.key);
+			response = await fetch(options.url, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(options.body(mail)),
+				signal: mail.signal
+			});
+		} catch (error) {
+			throw classify(error);
+		}
+		if (!response.ok) {
+			await response.body?.cancel().catch(() => {});
+			throw classify({ status: response.status });
+		}
+		try {
+			const result = await payload(response);
+			const id = options.id?.(result);
+			return id === void 0 ? void 0 : { id };
+		} catch (error) {
+			throw classify(error);
+		}
+	};
+	return Object.assign(transport, { label: options.label ?? "http" });
+}
+//#endregion
+export { http };