@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/src/logging/httpBodyCapture.ts

@@ -0,0 +1,393 @@
+import type { HttpBodyLog } from './contracts';
+
+const maximumCapturedProperties = 2_000;
+const maximumCaptureDepth = 12;
+const maximumHeaderValueLength = 4_096;
+const redactedValue = '[Redacted]';
+
+/**
+ * Mutable limits used while producing a bounded JSON-safe body value.
+ */
+interface BodySanitizationState {
+	/** Objects already visited while guarding against circular structures. */
+	seen: WeakSet<object>;
+	/** Remaining object properties or array items allowed in the capture. */
+	remainingProperties: number;
+}
+
+/**
+ * Captures one request or response body without retaining unbounded payloads.
+ *
+ * @param payload - Parsed request body or outgoing Fastify payload.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns Bounded body metadata and an inspectable value when safe.
+ */
+export function captureBody(
+	payload: unknown,
+	contentType: string | undefined,
+	maxBodyBytes: number,
+): HttpBodyLog {
+	if (payload === undefined || payload === null || payload === '') {
+		return {
+			kind: 'empty',
+			contentType,
+		};
+	}
+
+	if (isStreamLike(payload)) {
+		return {
+			kind: 'stream',
+			contentType,
+			note: 'Streaming response body omitted.',
+		};
+	}
+
+	if (Buffer.isBuffer(payload) || payload instanceof Uint8Array) {
+		const buffer = Buffer.from(payload);
+
+		if (!isTextContentType(contentType)) {
+			return {
+				kind: 'binary',
+				contentType,
+				sizeBytes: buffer.byteLength,
+				note: 'Binary body omitted.',
+			};
+		}
+
+		return captureText(buffer.toString('utf8'), contentType, maxBodyBytes);
+	}
+
+	if (typeof payload === 'string') {
+		return captureText(payload, contentType, maxBodyBytes);
+	}
+
+	return captureJson(payload, contentType, maxBodyBytes);
+}
+
+/**
+ * Captures textual content, parsing JSON so nested secrets can be redacted.
+ *
+ * @param value - Original textual payload.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns Text or JSON body capture.
+ */
+function captureText(
+	value: string,
+	contentType: string | undefined,
+	maxBodyBytes: number,
+): HttpBodyLog {
+	if (isFormContentType(contentType)) {
+		return captureJson(formBodyFromText(value), contentType, maxBodyBytes);
+	}
+
+	if (isJsonContentType(contentType) || looksLikeJson(value)) {
+		try {
+			return captureJson(JSON.parse(value), contentType, maxBodyBytes);
+		} catch {
+			// Malformed JSON remains useful as bounded response text.
+		}
+	}
+
+	const sizeBytes = Buffer.byteLength(value);
+
+	return {
+		kind: 'text',
+		contentType,
+		sizeBytes,
+		truncated: sizeBytes > maxBodyBytes,
+		value: truncateUtf8(value, maxBodyBytes),
+	};
+}
+
+/**
+ * Converts URL-encoded form text into a shape that supports field redaction.
+ *
+ * Repeated form keys remain arrays so the inspector does not silently discard
+ * submitted values.
+ *
+ * @param value - URL-encoded request body.
+ * @returns Parsed form object suitable for normal JSON sanitization.
+ */
+function formBodyFromText(value: string): Record<string, string | string[]> {
+	const captured: Record<string, string | string[]> = {};
+
+	for (const [key, item] of new URLSearchParams(value)) {
+		const existing = captured[key];
+
+		if (existing === undefined) {
+			captured[key] = item;
+			continue;
+		}
+
+		captured[key] = Array.isArray(existing)
+			? [...existing, item]
+			: [existing, item];
+	}
+
+	return captured;
+}
+
+/**
+ * Produces a JSON-safe, recursively redacted representation of a payload.
+ *
+ * @param value - Parsed body value.
+ * @param contentType - Media type reported by the HTTP message.
+ * @param maxBodyBytes - Maximum UTF-8 bytes retained in the log record.
+ * @returns JSON body capture.
+ */
+function captureJson(
+	value: unknown,
+	contentType: string | undefined,
+	maxBodyBytes: number,
+): HttpBodyLog {
+	const sanitized = sanitizeBodyValue(value, '', {
+		seen: new WeakSet<object>(),
+		remainingProperties: maximumCapturedProperties,
+	});
+	const serialized = JSON.stringify(sanitized);
+
+	if (serialized === undefined) {
+		return captureText(String(value), contentType, maxBodyBytes);
+	}
+
+	const sizeBytes = Buffer.byteLength(serialized);
+
+	return {
+		kind: 'json',
+		contentType,
+		sizeBytes,
+		truncated: sizeBytes > maxBodyBytes,
+		value: sizeBytes > maxBodyBytes
+			? truncateUtf8(serialized, maxBodyBytes)
+			: sanitized,
+	};
+}
+
+/**
+ * Recursively removes sensitive fields and bounds complex object traversal.
+ *
+ * @param value - Current body value.
+ * @param key - Owning object key used for sensitive-name detection.
+ * @param state - Shared circular-reference and property-count state.
+ * @param depth - Current traversal depth.
+ * @returns JSON-safe value suitable for structured logging.
+ */
+function sanitizeBodyValue(
+	value: unknown,
+	key: string,
+	state: BodySanitizationState,
+	depth = 0,
+): unknown {
+	if (isSensitiveName(key)) return redactedValue;
+	if (value === null || value === undefined) return value;
+	if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+		return value;
+	}
+	if (typeof value === 'bigint') return value.toString();
+	if (typeof value !== 'object') return String(value);
+	if (state.seen.has(value)) return '[Circular]';
+	if (depth >= maximumCaptureDepth) return '[Maximum depth reached]';
+
+	state.seen.add(value);
+
+	if (value instanceof Date) return value.toISOString();
+	if (value instanceof Error) {
+		return {
+			name: value.name,
+			message: value.message,
+			stack: value.stack,
+		};
+	}
+	if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+		return `[Binary ${value.byteLength} bytes]`;
+	}
+
+	if (Array.isArray(value)) {
+		const captured: unknown[] = [];
+
+		for (const item of value) {
+			if (state.remainingProperties <= 0) {
+				captured.push('[Capture limit reached]');
+				break;
+			}
+
+			state.remainingProperties -= 1;
+			captured.push(sanitizeBodyValue(item, '', state, depth + 1));
+		}
+
+		return captured;
+	}
+
+	const captured: Record<string, unknown> = {};
+
+	for (const [childKey, childValue] of Object.entries(value)) {
+		if (state.remainingProperties <= 0) {
+			captured['[capture]'] = 'Property limit reached';
+			break;
+		}
+
+		state.remainingProperties -= 1;
+		captured[childKey] = sanitizeBodyValue(childValue, childKey, state, depth + 1);
+	}
+
+	return captured;
+}
+
+/**
+ * Redacts credential-bearing headers before a record reaches Pino.
+ *
+ * @param headers - Fastify request or response header collection.
+ * @returns Header object safe for local request inspection.
+ */
+export function redactHeaders(
+	headers: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+	const captured: Record<string, unknown> = {};
+
+	for (const [name, value] of Object.entries(headers)) {
+		captured[name] = isSensitiveName(name)
+			? redactedValue
+			: boundedHeaderValue(value);
+	}
+
+	return captured;
+}
+
+/**
+ * Bounds one response or request header value.
+ *
+ * @param value - Original Fastify header value.
+ * @returns Original scalar shape with long strings shortened.
+ */
+function boundedHeaderValue(value: unknown): unknown {
+	if (typeof value === 'string') {
+		return value.length > maximumHeaderValueLength
+			? `${value.slice(0, maximumHeaderValueLength)}…`
+			: value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(item => boundedHeaderValue(item));
+	}
+
+	return value;
+}
+
+/**
+ * Detects common credential and session field names.
+ *
+ * @param name - Header or JSON property name.
+ * @returns True when the value must be removed from the capture.
+ */
+function isSensitiveName(name: string): boolean {
+	const normalized = name.toLowerCase().replace(/[-_]/g, '');
+
+	return normalized === 'authorization'
+		|| normalized === 'proxyauthorization'
+		|| normalized === 'cookie'
+		|| normalized === 'setcookie'
+		|| normalized === 'password'
+		|| normalized === 'passphrase'
+		|| normalized === 'secret'
+		|| normalized === 'token'
+		|| normalized === 'accesstoken'
+		|| normalized === 'refreshtoken'
+		|| normalized === 'apikey'
+		|| normalized === 'xapikey';
+}
+
+/**
+ * Converts a Fastify header into one displayable content-type string.
+ *
+ * @param value - Request or response content-type header.
+ * @returns First string value when present.
+ */
+export function headerValue(value: unknown): string | undefined {
+	if (typeof value === 'string') return value;
+	if (Array.isArray(value) && typeof value[0] === 'string') return value[0];
+
+	return undefined;
+}
+
+/**
+ * Identifies payloads that Fastify will stream instead of serialize.
+ *
+ * @param value - Candidate outgoing response payload.
+ * @returns True when the value exposes the Node stream pipe contract.
+ */
+function isStreamLike(value: unknown): boolean {
+	return typeof value === 'object'
+		&& value !== null
+		&& 'pipe' in value
+		&& typeof value.pipe === 'function';
+}
+
+/**
+ * Identifies media types that are safe to decode as UTF-8 text.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True for JSON and common textual media types.
+ */
+function isTextContentType(contentType: string | undefined): boolean {
+	const normalized = (contentType || '').toLowerCase();
+
+	return normalized.startsWith('text/')
+		|| normalized.includes('json')
+		|| normalized.includes('xml')
+		|| normalized.includes('javascript')
+		|| normalized.includes('x-www-form-urlencoded')
+		|| normalized.includes('svg');
+}
+
+/**
+ * Identifies JSON media types.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True when the media type uses JSON.
+ */
+function isJsonContentType(contentType: string | undefined): boolean {
+	return (contentType || '').toLowerCase().includes('json');
+}
+
+/**
+ * Identifies URL-encoded form media types requiring field-level redaction.
+ *
+ * @param contentType - HTTP content type.
+ * @returns True when the body uses URL-encoded form syntax.
+ */
+function isFormContentType(contentType: string | undefined): boolean {
+	return (contentType || '').toLowerCase().includes('x-www-form-urlencoded');
+}
+
+/**
+ * Detects likely JSON text when a content type was omitted or incorrect.
+ *
+ * @param value - Textual payload.
+ * @returns True when the trimmed body begins with a JSON container.
+ */
+function looksLikeJson(value: string): boolean {
+	const trimmed = value.trim();
+
+	return (trimmed.startsWith('{') && trimmed.endsWith('}'))
+		|| (trimmed.startsWith('[') && trimmed.endsWith(']'));
+}
+
+/**
+ * Truncates text by UTF-8 byte length rather than JavaScript character count.
+ *
+ * @param value - Original text.
+ * @param maxBytes - Maximum bytes to retain.
+ * @returns Original or shortened UTF-8 text.
+ */
+function truncateUtf8(value: string, maxBytes: number): string {
+	const buffer = Buffer.from(value);
+
+	if (buffer.byteLength <= maxBytes) return value;
+
+	const marker = '…';
+	const contentBytes = Math.max(0, maxBytes - Buffer.byteLength(marker));
+
+	return `${buffer.subarray(0, contentBytes).toString('utf8')}…`;
+}

package/src/logging/index.ts

@@ -1,3 +1,5 @@
 export * from './contracts';
 export * from './drivers';
 export * from './Log';
+export * from './DevelopmentConsole';
+export * from './registerHttpExchangeMonitor';

package/src/logging/redactLogEmail.ts

@@ -0,0 +1,12 @@
+/** Redacts common credential forms while preserving exception wording and stack locations. */
+export function redactLogEmail(text: string): string {
+	return text
+		.replace(/\b(?:Bearer|Basic)\s+[^\s"',;]+/gi, '[REDACTED authorization]')
+		.replace(/\b(?:sk-|sk_|rk_|ghp_|github_pat_)[A-Za-z0-9_-]+/g, '[REDACTED key]')
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[REDACTED token]')
+		.replace(/(["']?(?:password|passwd|api[_-]?key|access[_-]?token|refresh[_-]?token|client[_-]?secret|authorization|token|secret)["']?\s*[:=]\s*)(?:"[^"\n]*"|'[^'\n]*'|[^\s,;]+)/gi, '$1[REDACTED]')
+		.replace(/((?:set-cookie|cookie)\s*:\s*)[^\r\n]+/gi, '$1[REDACTED]')
+		.replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s<>"']+/gi, url => url
+			.replace(/(\/\/)[^/@\s]+@/, '$1[REDACTED]@')
+			.replace(/[?#].*$/, '?[REDACTED parameters]'));
+}

package/src/logging/registerHttpExchangeMonitor.ts

@@ -0,0 +1,45 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { isInteractiveDevelopmentEnvironment } from '../devtools';
+import { captureBody, headerValue, redactHeaders } from './httpBodyCapture';
+import type * as logging from './contracts';
+
+/**
+ * Captures bounded, redacted payloads for grouped console logs and devtools.
+ * Register before routes on a Fastify host using app.log.logger. Fastify's own
+ * arrival/completion records provide lifecycle timing; streams are never consumed.
+ * @param server - Caller-owned HTTP server.
+ * @param options - Development capture and private-route exclusion policy.
+ */
+export function registerHttpExchangeMonitor(server: FastifyInstance, options: logging.HttpExchangeMonitorOptions = {}): void {
+	if (options.enabled === false || !isInteractiveDevelopmentEnvironment(options.environment ?? process.env.NODE_ENV)) return;
+	const configured = options.maxBodyBytes;
+	const maxBodyBytes = configured && Number.isFinite(configured) && configured > 0 ? Math.min(65536, Math.floor(configured)) : 16384;
+	const ended = new WeakSet<FastifyRequest>();
+
+	/** Reports one terminal interruption even if timeout and socket close both fire. */
+	function interrupted(request: FastifyRequest, message: string): void {
+		if (ended.has(request)) return;
+		ended.add(request);
+		request.log.warn(message);
+	}
+
+	server.addHook('onRequest', (request, reply, done) => {
+		reply.raw.once('close', () => {
+			if (!reply.raw.writableFinished) interrupted(request, 'request aborted');
+		});
+		done();
+	});
+	server.addHook('onTimeout', (request, _reply, done) => { interrupted(request, 'request timed out'); done(); });
+	server.addHook('onRequestAbort', (request, done) => { interrupted(request, 'request aborted'); done(); });
+	server.addHook('onResponse', (request, _reply, done) => { ended.add(request); done(); });
+	server.addHook('onSend', (request, reply, payload, done) => {
+		if (!options.exclude?.(request)) {
+			const httpExchange: logging.HttpExchangeLog = {
+				request: { method: request.method, url: request.url, headers: redactHeaders(request.headers), body: captureBody(request.body, headerValue(request.headers['content-type']), maxBodyBytes) },
+				response: { statusCode: reply.statusCode, headers: redactHeaders(reply.getHeaders()), body: captureBody(payload, headerValue(reply.getHeader('content-type')), maxBodyBytes) },
+			};
+			request.log.info({ httpExchange }, 'request exchange');
+		}
+		done(null, payload);
+	});
+}

package/src/logging/transports/EmailLogTransport.ts

@@ -0,0 +1,46 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Mail } from '../../mail';
+import type { EmailLogOptions } from '../contracts';
+import { formatLogEmail } from '../formatLogEmail';
+
+const deliveringEmail = new AsyncLocalStorage<boolean>();
+
+/**
+ * Sends each serialized error/fatal log through Mail once, in arrival order.
+ * Pending sends live in memory; flush/close drains them. Provider failures go to
+ * stderr without recursive logging, retry, cooldown, grouping or suppression of later records.
+ */
+export class EmailLogTransport {
+	#pending: Promise<void> = Promise.resolve();
+
+	/** Resolves Mail lazily so constructing an application logger does not initialize mail providers. */
+	constructor(readonly options: EmailLogOptions, readonly mail: () => Mail) {}
+
+	/** Accepts Pino JSON lines after serialization and configured field redaction. */
+	write(line: string): void {
+		if (deliveringEmail.getStore()) return;
+		try {
+			const record = JSON.parse(line) as Record<string, unknown>;
+			const message = formatLogEmail(record, this.options);
+			this.#pending = this.#pending.then(() => deliveringEmail.run(true, async () => {
+				try {
+					await this.mail().send(message);
+				} catch {
+					// Never include provider errors here: they can contain credentials or request bodies.
+					process.stderr.write('[logging] Error email delivery failed; original record remains in configured log destinations.\n');
+				}
+			}));
+		} catch {
+			process.stderr.write('[logging] Error email formatting failed; original record remains in configured log destinations.\n');
+		}
+	}
+
+	/** Waits for all accepted sends, including records appended while a flush is in progress. */
+	async flush(): Promise<void> {
+		let pending: Promise<void>;
+		do {
+			pending = this.#pending;
+			await pending;
+		} while (pending !== this.#pending);
+	}
+}

package/src/mail/Mail.ts

@@ -26,6 +26,8 @@ export interface MailMessage {
 	html?: string;
 	/** Extra message headers; File and Resend preserve them, Mailgun currently does not. */
 	headers?: Record<string, string>;
+	/** Stable request identity for provider retries. Resend deduplicates identical requests for 24 hours; other built-in transports ignore this value. */
+	idempotencyKey?: string;
 }
 
 /** Transport input with a default sender resolved and recipients normalized to an array. */
@@ -83,6 +85,9 @@ export class Mail {
 
 	/** Resolves the sender and recipient list without changing application content. */
 	private resolveMessage(message: MailMessage): ResolvedMailMessage {
+		if (message.idempotencyKey !== undefined && !/^[\x21-\x7e]{1,256}$/.test(message.idempotencyKey)) {
+			throw new Error('Mail idempotencyKey must contain 1 to 256 printable non-space ASCII characters.');
+		}
 		const to = Array.isArray(message.to) ? message.to : [message.to];
 
 		if (to.length === 0) {

package/src/mail/MailDeliveryError.ts

@@ -0,0 +1,8 @@
+/** Structured provider refusal; consumers decide retry policy without parsing diagnostic messages. */
+export class MailDeliveryError extends Error {
+	/** Creates a refusal retaining the provider code, HTTP status and optional validated retry time. */
+	constructor(message: string, readonly provider: string, readonly status: number, readonly code: string | null, readonly retryAt: Date | null = null) {
+		super(message);
+		this.name = 'MailDeliveryError';
+	}
+}

package/src/mail/README.md

@@ -177,7 +177,7 @@ The framework does not retry a failed send or persist an outbox. Dispatch a
 dedicated queued job when the application needs retry policy, idempotency, or
 delivery that survives process shutdown.
 
-Queue retry alone does not prevent duplicate email. A timeout can follow provider acceptance. These built-in HTTP transports do not expose provider idempotency keys or an outbox transaction; a message header is not an API idempotency key. Make that business decision explicitly.
+Queue retry alone does not prevent duplicate email. A timeout can follow provider acceptance. Set `MailMessage.idempotencyKey` to a stable request identity when using Resend. The transport forwards it as the API `Idempotency-Key` header, separately from email headers. Resend deduplicates identical requests for 24 hours; applications must preserve the exact payload and manage retries within that window. Keys accept 1–256 printable non-space ASCII characters. File and Mailgun transports ignore this field. Mail does not persist an outbox or promise exactly-once delivery across all transports. See [Resend idempotency](https://resend.com/docs/dashboard/emails/idempotency-keys).
 
 `accepted` means transport/provider acceptance, not inbox delivery. The built-ins have no attachments, CC/BCC, delivery tracking, scheduled sending or explicit request timeout. File and Resend preserve custom `headers`; Mailgun currently does not forward them. `App` has no built-in `mail` getter, and Mail has no close method. Own any resources introduced by your custom transport.
 
@@ -204,3 +204,13 @@ External mail APIs are controlled through the injectable transport or a stubbed
 in [`Mail.ts`](./Mail.ts) and [`transports/`](./transports). Behavioural tests
 live at `packages/app/src/mail/tests/` in the source repository and are not
 included in the installed runtime package.
+
+Resend and Mailgun HTTP submissions now reject redirects and have a 15-second
+request timeout. A timeout may follow provider acceptance, so callers must still
+use stable idempotency identities and tolerate at-least-once delivery.
+
+Resend refusals throw the exported `MailDeliveryError`, retaining `provider`,
+HTTP `status`, a bounded machine-readable `code`, and an optional validated
+`retryAt` parsed from `Retry-After` seconds or an HTTP date. Missing, malformed or
+past timing is `null`. `Mail` submits once and leaves retry policy to consumers;
+error messages remain diagnostic content rather than classification signals.

package/src/mail/index.ts

@@ -2,3 +2,4 @@ export * from './Mail.js';
 export * from './transports/FileMailTransport.js';
 export * from './transports/MailgunTransport.js';
 export * from './transports/ResendTransport.js';
+export * from './MailDeliveryError.js';

package/src/mail/transports/MailgunTransport.ts

@@ -57,6 +57,8 @@ export class MailgunTransport implements MailTransport {
 
 		const response = await fetch(`${this.baseUrl}/${this.domain}/messages`, {
 			method: 'POST',
+			signal: AbortSignal.timeout(15000),
+			redirect: 'error',
 			headers: {
 				authorization: `Basic ${Buffer.from(`api:${this.apiKey}`).toString('base64')}`,
 			},

package/src/mail/transports/ResendTransport.ts

@@ -1,35 +1,25 @@
-import {
-	formatMailAddress,
-	mailAddressEmail,
-	type MailDelivery,
-	type MailTransport,
-	type ResolvedMailMessage,
-} from '../Mail.js';
+import { MailDeliveryError } from '../MailDeliveryError.js';
+import { formatMailAddress, mailAddressEmail, type MailDelivery, type MailTransport, type ResolvedMailMessage } from '../Mail.js';
 
 export interface ResendTransportOptions {
 	apiKey: string;
 	baseUrl?: string;
 }
 
-class ResendTransportError extends Error {
-	constructor(message: string) {
-		super(message);
-		this.name = 'ResendTransportError';
-	}
-}
-
 /**
  * Resend API transport.
  */
 export class ResendTransport implements MailTransport {
-	private readonly apiKey: string;
-	private readonly baseUrl: string;
+	readonly #apiKey: string;
+	readonly #baseUrl: string;
 
+	/** Creates a bounded Resend transport; credentials remain private to this instance. */
 	constructor(options: ResendTransportOptions) {
-		this.apiKey = options.apiKey;
-		this.baseUrl = (options.baseUrl || 'https://api.resend.com').replace(/\/+$/, '');
+		this.#apiKey = options.apiKey;
+		this.#baseUrl = (options.baseUrl || 'https://api.resend.com').replace(/\/+$/, '');
 	}
 
+	/** Sends one message, forwarding a stable retry identity as an API header rather than an email header. */
 	async send(message: ResolvedMailMessage): Promise<MailDelivery> {
 		const payload: Record<string, unknown> = {
 			from: formatMailAddress(message.from),
@@ -49,17 +39,21 @@ export class ResendTransport implements MailTransport {
 			payload.headers = message.headers;
 		}
 
-		const response = await fetch(`${this.baseUrl}/emails`, {
+		const response = await fetch(`${this.#baseUrl}/emails`, {
 			method: 'POST',
+			signal: AbortSignal.timeout(15000),
+			redirect: 'error',
 			headers: {
-				authorization: `Bearer ${this.apiKey}`,
+				authorization: `Bearer ${this.#apiKey}`,
 				'content-type': 'application/json',
+				...(message.idempotencyKey ? { 'Idempotency-Key': message.idempotencyKey } : {}),
 			},
 			body: JSON.stringify(payload),
 		});
 		const result = await response.json().catch(() => null) as {
 			id?: unknown;
 			message?: unknown;
+			name?: unknown;
 		} | null;
 
 		if (!response.ok) {
@@ -67,7 +61,8 @@ export class ResendTransport implements MailTransport {
 				? result.message
 				: response.statusText;
 
-			throw new ResendTransportError(`Resend rejected the message: ${detail}`);
+			const code = typeof result?.name === 'string' && /^[a-z_]{1,100}$/.test(result.name) ? result.name : null;
+			throw new MailDeliveryError(`Resend rejected the message: ${detail}`, 'resend', response.status, code, retryTime(response.headers.get('retry-after')));
 		}
 
 		return {
@@ -77,4 +72,11 @@ export class ResendTransport implements MailTransport {
 			rejected: [],
 		};
 	}
-}
+}
+
+/** Parses standard Retry-After seconds or HTTP dates, ignoring malformed, overflowing and past values. */
+function retryTime(value: string | null): Date | null {
+	if (!value) return null;
+	const milliseconds = /^\d+$/.test(value) ? Date.now() + Number(value) * 1000 : Date.parse(value);
+	return Number.isFinite(milliseconds) && milliseconds > Date.now() && milliseconds <= 8640000000000000 ? new Date(milliseconds) : null;
+}