void 0.10.13 → 0.20.0

package/dist/runtime/email/testing.mjs

@@ -0,0 +1,283 @@
+import { i as normalizeEmail, r as buildMime } from "../../mime-BJD7d_qL.mjs";
+import { y as registerEmailSink } from "../../dev-inbox-DkgRWLkW.mjs";
+import { n as compileEmailPattern, t as compareEmailRoutes } from "../../email-Ce6SQq-i.mjs";
+import { i as createMessageProxy, n as MAX_INBOUND_HEADERS, t as MAX_INBOUND_BYTES } from "../../inbound-CNKxb3FY.mjs";
+//#region src/runtime/email/testing.ts
+/**
+* Test harnesses for void/email.
+*
+*   createEmailTestHarness    — captures outbound `sendEmail` calls.
+*   createInboundTestHarness  — delivers a synthesized message through your
+*                                inbound route table and captures any
+*                                replies / forwards / rejects.
+*
+*   import { createEmailTestHarness } from "void/email/testing";
+*   const harness = createEmailTestHarness();
+*   await sendEmail({ from: "a@x.dev", to: "b@y.dev", subject: "hi", text: "yo" });
+*   expect(harness.messages[0].subject).toBe("hi");
+*   harness.dispose();
+*
+*   import { createInboundTestHarness } from "void/email/testing";
+*   const inbound = createInboundTestHarness({
+*     routes: { "support+[ticket]": supportHandler, _default: catchAll },
+*   });
+*   const result = await inbound.deliver({
+*     from: "user@example.com",
+*     // The WIRE address: `<slug>+<tag>@<domain>`, as the platform delivers
+*     // it. The harness strips `<slug>+` before matching, so passing the
+*     // user-facing "support+abc-1@app.dev" would read `support` as the slug.
+*     to: "myslug+support+abc-1@app.dev",
+*     subject: "help",
+*     text: "thanks",
+*   });
+*   expect(result.handler).toBe("support+[ticket]");
+*   expect(result.params).toEqual({ ticket: "abc-1" });
+*/
+function createEmailTestHarness() {
+	const messages = [];
+	const unregister = registerEmailSink((m) => {
+		messages.push(m);
+	});
+	return {
+		get messages() {
+			return messages;
+		},
+		clear() {
+			messages.length = 0;
+		},
+		dispose() {
+			unregister();
+			messages.length = 0;
+		}
+	};
+}
+function compileRoutes(routes) {
+	const compiled = [];
+	let defaultHandler;
+	for (const [key, handler] of Object.entries(routes)) {
+		if (key === "_default") {
+			defaultHandler = handler;
+			continue;
+		}
+		const pattern = compileEmailPattern(key);
+		if (!pattern) throw new Error(`createInboundTestHarness: route key ${JSON.stringify(key)} is not a valid email pattern. Use shapes like "support", "support+[ticket]", "[user]", "[user]+[tag]", or the reserved key "_default".`);
+		compiled.push({
+			address: key,
+			pattern,
+			handler
+		});
+	}
+	compiled.sort(compareEmailRoutes);
+	return {
+		compiled,
+		defaultHandler
+	};
+}
+async function buildSyntheticRaw(opts) {
+	if (opts.raw !== void 0) return typeof opts.raw === "string" ? new TextEncoder().encode(opts.raw) : opts.raw;
+	const text = opts.text ?? (opts.html ? void 0 : "(empty)");
+	const normalized = await normalizeEmail({
+		from: opts.from,
+		to: opts.to,
+		subject: opts.subject ?? "",
+		text,
+		html: opts.html,
+		headers: opts.headers
+	});
+	return buildMime(normalized).raw;
+}
+/**
+* Thrown by `parseHeaderBlock` at the first distinct name past its cap —
+* the router's `InboundTooManyHeadersError` (`email-router.ts`).
+*/
+var InboundTooManyHeadersError = class extends Error {};
+/**
+* Headers of a raw MIME message, up to the first blank line.
+*
+* Unfolds continuation lines (RFC 5322 §2.2.3: a line starting with WSP
+* continues the one before it). Anything it cannot parse is skipped rather
+* than thrown, because a test may deliver deliberately malformed bytes.
+*
+* `maxDistinct` is the router's header-count admission (`buildEnvelope` in
+* `email-router.ts`): it walks the bag Cloudflare built from the wire and
+* refuses at the cap, BEFORE any entry past it is materialized. That bag is
+* a `Headers`, so the unit is the DISTINCT, case-insensitive name — a
+* repeated `Received:` is one entry, and a continuation line is part of the
+* one before it, never its own. The check sits in the same walk, checked
+* before the `set`, so an over-cap message costs this harness the same
+* `maxDistinct + 1` names it costs the router. A name a `Headers` refuses
+* is not in the bag on either side, so it does not count.
+*/
+function parseHeaderBlock(raw, maxDistinct) {
+	const headers = new Headers();
+	const text = new TextDecoder().decode(raw);
+	const end = text.indexOf("\r\n\r\n");
+	const block = end === -1 ? text : text.slice(0, end);
+	let distinct = 0;
+	let current = "";
+	const commit = () => {
+		const colon = current.indexOf(":");
+		if (colon > 0) {
+			const name = current.slice(0, colon).trim();
+			let known;
+			try {
+				known = headers.has(name);
+			} catch {
+				current = "";
+				return;
+			}
+			if (!known && distinct >= maxDistinct) throw new InboundTooManyHeadersError();
+			try {
+				headers.set(name, current.slice(colon + 1).trim());
+				if (!known) distinct++;
+			} catch {}
+		}
+		current = "";
+	};
+	for (let pos = 0; pos <= block.length;) {
+		const nl = block.indexOf("\r\n", pos);
+		const line = nl === -1 ? block.slice(pos) : block.slice(pos, nl);
+		pos = nl === -1 ? block.length + 1 : nl + 2;
+		if (line === "") break;
+		if (/^[ \t]/.test(line) && current !== "") {
+			current += ` ${line.trim()}`;
+			continue;
+		}
+		commit();
+		current = line;
+	}
+	commit();
+	return headers;
+}
+function createInboundTestHarness(opts) {
+	const { compiled, defaultHandler } = compileRoutes(opts.routes);
+	const env = opts.env ?? {};
+	const replies = [];
+	const forwards = [];
+	const rejects = [];
+	const deliveries = [];
+	async function deliver(input) {
+		const raw = await buildSyntheticRaw(input);
+		let headers;
+		if (opts.slug === null) headers = parseHeaderBlock(raw, Infinity);
+		else {
+			const at = input.to.indexOf("@");
+			const label = at === -1 ? "void email" : input.to.slice(at + 1).toLowerCase() || "void email";
+			if (raw.byteLength > 10485760) return refuse(`${label}: message too large (max ${MAX_INBOUND_BYTES} bytes)`);
+			try {
+				headers = parseHeaderBlock(raw, MAX_INBOUND_HEADERS);
+			} catch (e) {
+				if (e instanceof InboundTooManyHeadersError) return refuse(`${label}: too many headers (max ${MAX_INBOUND_HEADERS})`);
+				throw e;
+			}
+		}
+		for (const [k, v] of new Headers(input.headers ?? {})) headers.set(k, v);
+		if (!headers.has("Subject") && input.subject) headers.set("Subject", input.subject);
+		if (!headers.has("From")) headers.set("From", input.from);
+		if (!headers.has("To")) headers.set("To", input.to);
+		const slug = (() => {
+			if (opts.slug === null) return;
+			if (opts.slug) return opts.slug;
+			const local = input.to.split("@")[0] ?? "";
+			const plus = local.indexOf("+");
+			return plus === -1 ? void 0 : local.slice(0, plus);
+		})();
+		const { message, getActions } = createMessageProxy({
+			from: input.from,
+			to: input.to,
+			headers: Object.fromEntries(headers),
+			raw,
+			rawSize: raw.byteLength
+		}, { slug });
+		const ctx = {
+			waitUntil() {},
+			passThroughOnException() {}
+		};
+		const fullLocal = input.to.split("@")[0] ?? "";
+		const plus = fullLocal.indexOf("+");
+		const local = opts.slug === null ? fullLocal : plus === -1 ? "" : fullLocal.slice(plus + 1);
+		async function dispatch() {
+			for (const route of compiled) {
+				const m = new RegExp(route.pattern.regexSource, "i").exec(local);
+				if (!m) continue;
+				const params = {};
+				for (let i = 0; i < route.pattern.paramNames.length; i++) params[route.pattern.paramNames[i]] = m[i + 1];
+				const info = { params };
+				await route.handler(message, env, ctx, info);
+				return {
+					handler: route.address,
+					params
+				};
+			}
+			if (defaultHandler) {
+				await defaultHandler(message, env, ctx, { params: {} });
+				return {
+					handler: "_default",
+					params: {}
+				};
+			}
+			message.setReject(`no handler matched recipient "${input.to}" — add email/_default.ts to handle unmatched mail`);
+			return {
+				handler: void 0,
+				params: {}
+			};
+		}
+		const result = await dispatch();
+		record(getActions());
+		deliveries.push(result);
+		return result;
+	}
+	function refuse(reason) {
+		record([{
+			type: "reject",
+			reason
+		}]);
+		const result = {
+			handler: void 0,
+			params: {}
+		};
+		deliveries.push(result);
+		return result;
+	}
+	function record(actions) {
+		for (const action of actions) switch (action.type) {
+			case "reject":
+				rejects.push(action.reason);
+				break;
+			case "forward":
+				forwards.push({
+					to: action.to,
+					...action.headers ? { headers: new Headers(action.headers) } : {}
+				});
+				break;
+			case "reply": replies.push({
+				from: action.from,
+				to: action.to,
+				raw: action.raw
+			});
+		}
+	}
+	return {
+		get replies() {
+			return replies;
+		},
+		get forwards() {
+			return forwards;
+		},
+		get rejects() {
+			return rejects;
+		},
+		get deliveries() {
+			return deliveries;
+		},
+		deliver,
+		clear() {
+			replies.length = 0;
+			forwards.length = 0;
+			rejects.length = 0;
+			deliveries.length = 0;
+		}
+	};
+}
+//#endregion
+export { createEmailTestHarness, createInboundTestHarness };

package/dist/runtime/email.d.mts

@@ -0,0 +1,30 @@
+/// <reference types="@cloudflare/workers-types" />
+import { C as SendEmailRecipientResult, S as SendEmailOptions, _ as Attachment, a as MessageProxy, b as SendEmailError, c as ParsedEmail, d as defineEmail, f as enactEmailActions, g as Address, h as replyEmail, i as EmailHandlerInfo, l as ReplyEmailOptions, m as parseEmail, n as EmailEnvelope, o as ParseEmailError, p as isForwardableEmailMessage, r as EmailHandler, s as ParseEmailErrorCode, t as EmailAction, u as createMessageProxy, v as NormalizedEmail, w as SendEmailResult, x as SendEmailErrorCode, y as SendEmailDelivery } from "../inbound-BJ70in1n.mjs";
+//#region src/runtime/email/mime.d.ts
+type MimeErrorCode = "INVALID_FROM" | "INVALID_TO" | "MIME_ERROR";
+export declare class MimeError extends Error {
+  code: MimeErrorCode;
+  constructor(code: MimeErrorCode, message: string);
+}
+//#endregion
+//#region src/runtime/email.d.ts
+/**
+ * Send an email via the Void platform proxy.
+ *
+ * During `void dev` the message is captured by the local inbox
+ * (`/__void/inbox`) and never reaches the proxy; an in-process sink
+ * (`void/email/testing`) takes precedence over it. Pass `sendInDev: true` to
+ * override for a single call.
+ */
+export declare function sendEmail(opts: SendEmailOptions): Promise<SendEmailResult>;
+/**
+ * Build a normalized email + raw MIME for advanced callers who want to feed
+ * the message into a custom transport. Throws on invalid input.
+ */
+export declare function createEmail(opts: SendEmailOptions): Promise<{
+  email: NormalizedEmail;
+  raw: Uint8Array;
+  messageId: string;
+}>;
+//#endregion
+export { type Address, type Attachment, type EmailAction, type EmailEnvelope, type EmailHandler, type EmailHandlerInfo, type MessageProxy, type MimeErrorCode, type NormalizedEmail, ParseEmailError, type ParseEmailErrorCode, type ParsedEmail, type ReplyEmailOptions, type SendEmailDelivery, type SendEmailError, type SendEmailErrorCode, type SendEmailOptions, type SendEmailRecipientResult, type SendEmailResult, createMessageProxy, defineEmail, enactEmailActions, isForwardableEmailMessage, parseEmail, replyEmail };