@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1305

package/database/stand-in.d.mts

@@ -0,0 +1,99 @@
+import { t as Built } from "../build-SQ44jwSa.mjs";
+import { d as Row, i as FunctionReference, r as FunctionKind, u as RegisteredFunction } from "../server-C7O7CICU.mjs";
+//#region src/database/stand-in.d.ts
+/** A Database as its client reaches it: by function name or reference. A refusal throws `DatabaseError`. */
+interface DatabaseClient {
+  query(fn: string | FunctionReference, args?: unknown): Promise<unknown>;
+  /** `tag` identifies the call: sent again under it, the mutation applies once. */
+  mutation(fn: string | FunctionReference, args?: unknown, options?: {
+    readonly tag?: string;
+  }): Promise<unknown>;
+  /** `tag` identifies the call, as a mutation's does; a server that keeps results runs it once for it. */
+  action(fn: string | FunctionReference, args?: unknown, options?: {
+    readonly tag?: string;
+  }): Promise<unknown>;
+  /** Gives `onValue` the query's value now and again after every change it sees; returns a stop. */
+  watch(fn: string | FunctionReference, args: unknown, onValue: (value: unknown) => void): () => void;
+  /** The same client for a signed-in caller, by the Project's sign-in's subject. */
+  as(subject: string): DatabaseClient;
+  /** A new call identity. */
+  tag(): Promise<string>;
+}
+/** A build's functions, loaded: each by its name, with the schema's tables and indexes. */
+interface Loaded {
+  readonly functions: ReadonlyMap<string, RegisteredFunction>;
+  readonly tables: Built["tables"];
+  readonly indexes: Built["indexes"];
+}
+interface StandIn {
+  /** Serves `loaded`'s functions from now on. The rows stay. */
+  serve(loaded: Loaded): void;
+  /**
+   * Runs `work` between mutations, in their order: none commits while it runs, so what it reads of
+   * the rows stays true until it ends (checking rows against a schema, then serving it). `work`
+   * must not run a mutation itself.
+   */
+  exclusive<T>(work: () => T | Promise<T>): Promise<T>;
+  /** A client with no signed-in caller. */
+  readonly client: DatabaseClient;
+  /**
+   * A client for any caller: `user` signed in, or the server's own code (`server`), with
+   * `internal` functions too. What a Database Key or a run by hand calls as.
+   */
+  caller(caller: Caller): DatabaseClient;
+  /** What kind of function `name` is, or undefined when there is none: the wire sends actions as mutations. */
+  kind(name: string): FunctionKind | undefined;
+  /** Every row, by table and id. */
+  rows(): Record<string, Record<string, Row>>;
+  /**
+   * Commits what `write` returns, between mutations, as one commit of its own as a mutation's would
+   * be: told to `committed` and seen by every watch. `write` is given the rows as they are then, and
+   * may throw to commit nothing. How a Database's rows are put back as a restore point held them.
+   */
+  commit(write: (rows: Record<string, Record<string, Stored>>) => ReadonlyArray<Change>): Promise<ReadonlyArray<Change>>;
+  /** Stops the scheduler's timers. */
+  close(): void;
+}
+/**
+ * Writes a build's files under `folder` and loads them, each import of the surface naming this SDK's
+ * `server.ts`. They reach it through a shim beside them, `_generated/server.mjs`, that re-exports the
+ * module loaded here: a file on disk can't import one inside a compiled CLI, where this SDK's files
+ * live only in the binary. Each load is a folder of its own, so a module loaded before never stands in
+ * for a newer one.
+ */
+declare function loadDatabase(built: Built, folder: string): Promise<Loaded>;
+/** A row as the Stand-in keeps it: its fields and its version, which counts its writes. */
+type Stored = Row & {
+  readonly _version: number;
+};
+/** One row a mutation changed: its table, its id and what it is now, null when deleted. */
+interface Change {
+  readonly table: string;
+  readonly id: string;
+  readonly row: Stored | null;
+}
+interface Caller {
+  readonly user: string | null;
+  readonly server: boolean;
+  readonly internal: boolean;
+}
+/** Orders index keys as the Database does: by type (null, numbers, strings, booleans), then by value. */
+declare function compare(a: unknown, b: unknown): number;
+/**
+ * `rows` are the rows it starts with, as `rows()` gave them (a branch's, from its parent);
+ * `committed` is told every mutation's changes as it commits them, in order. `admits` is asked as a
+ * mutation starts, and what it returns is asked in the same step as the mutation commits, with nothing
+ * between: so the commit can require what held at the start (a Database's lifecycle version). A reason
+ * refuses the commit, and the mutation is refused as `unavailable` with nothing it wrote kept.
+ * `read` is told how many rows each read gave a function, a mutation's own writes included.
+ */
+declare function databaseStandIn(options?: {
+  readonly clock?: () => number;
+  readonly random?: (bytes: number) => Uint8Array;
+  readonly rows?: Readonly<Record<string, Readonly<Record<string, Stored>>>>;
+  readonly committed?: (changes: ReadonlyArray<Change>) => void;
+  readonly admits?: () => () => string | null;
+  readonly read?: (rows: number) => void;
+}): StandIn;
+//#endregion
+export { Caller, Change, DatabaseClient, Loaded, StandIn, Stored, compare, databaseStandIn, loadDatabase };

package/database/stand-in.mjs

@@ -0,0 +1,430 @@
+import { a as shapeError, i as indexFields } from "../schema-BF-Y1EVu.mjs";
+import { InsufficientError, NotFoundError, Refusal, isFunction } from "./server.mjs";
+import { DatabaseError } from "./errors.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/database/stand-in.ts
+/**
+* The Database's Stand-in, for `midsummer dev`: a Project's own `db/` functions run in memory, with
+* the Database's meaning. Mutations run one at a time, each writing all of what it wrote or none of
+* it; a mutation sent again under the same tag applies once; arguments, results and writes are
+* checked against their shapes; a watched query is given its value again after every change; the
+* scheduler runs what it is given. It passes the Database's contract
+* (`@midsummer-ai/sdk/database/contract`) except durability and scale, and holds no engine code.
+*
+*   const built = buildDatabase(sources, strip)
+*   const database = databaseStandIn()
+*   database.serve(await loadDatabase(built, folder))
+*   const id = await database.client.as("ada").mutation("messages.send", { channel: "a", body: "hi" })
+*
+* The Project's code runs in this process, as it does on its author's machine. Crons do not run
+* here yet.
+*/
+const SURFACE = /(\bfrom\s*)(["'])(@midsummer(?:-ai)?\/sdk\/server|\.\/_generated\/server(?:\.m?js)?)\2/gu;
+/** Where the loaded surface waits for the shim each load imports it through. */
+const HELD = Symbol.for("midsummer.database.surface");
+let loads = 0;
+/**
+* Writes a build's files under `folder` and loads them, each import of the surface naming this SDK's
+* `server.ts`. They reach it through a shim beside them, `_generated/server.mjs`, that re-exports the
+* module loaded here: a file on disk can't import one inside a compiled CLI, where this SDK's files
+* live only in the binary. Each load is a folder of its own, so a module loaded before never stands in
+* for a newer one.
+*/
+async function loadDatabase(built, folder) {
+	const surface = await import("./server.mjs");
+	globalThis[HELD] = surface;
+	const names = Object.keys(surface).filter((name) => name !== "default" && /^[A-Za-z_$][\w$]*$/.test(name));
+	const dir = join(folder, `load-${process.pid}-${loads += 1}`);
+	await mkdir(join(dir, "_generated"), { recursive: true });
+	await writeFile(join(dir, "_generated", "api.mjs"), built.generated["api.mjs"]);
+	await writeFile(join(dir, "_generated", "server.mjs"), `const surface = globalThis[Symbol.for("midsummer.database.surface")];\nexport const { ${names.join(", ")} } = surface;\n`);
+	for (const [name, text] of Object.entries(built.files)) await writeFile(join(dir, name), text.replace(SURFACE, (_all, from, quote) => `${from}${quote}./_generated/server.mjs${quote}`));
+	const functions = /* @__PURE__ */ new Map();
+	for (const fn of built.functions) {
+		const exported = (await import(pathToFileURL(join(dir, fn.file)).href))[fn.export];
+		if (!isFunction(exported)) throw new Error(`${built.from[fn.file]}: ${fn.export} is not a function`);
+		functions.set(fn.name, exported);
+	}
+	return {
+		functions,
+		tables: built.tables,
+		indexes: built.indexes
+	};
+}
+/** A value as the wire carries it: JSON, `undefined` gone. */
+const wire = (value) => value === void 0 ? null : JSON.parse(JSON.stringify(value));
+const hex = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+const nameOf = (fn) => typeof fn === "string" ? fn : fn.name;
+/** Orders index keys as the Database does: by type (null, numbers, strings, booleans), then by value. */
+function compare(a, b) {
+	const rank = (x) => x === null || x === void 0 ? 0 : typeof x === "number" ? 1 : typeof x === "string" ? 2 : typeof x === "boolean" ? 3 : 4;
+	const ra = rank(a), rb = rank(b);
+	if (ra !== rb) return ra - rb;
+	if (ra === 4) return 0;
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Why a call was refused, as the client carries it. */
+function refusalOf(error) {
+	if (error instanceof DatabaseError) return error;
+	if (error instanceof Refusal) return new DatabaseError(error.why, error.message, error.detail);
+	if (error instanceof InsufficientError) return new DatabaseError("short", error.message, error.detail);
+	if (error instanceof NotFoundError) return new DatabaseError("notfound", error.message, error.detail);
+	return new DatabaseError("refused", error instanceof Error ? error.message : String(error));
+}
+/**
+* `rows` are the rows it starts with, as `rows()` gave them (a branch's, from its parent);
+* `committed` is told every mutation's changes as it commits them, in order. `admits` is asked as a
+* mutation starts, and what it returns is asked in the same step as the mutation commits, with nothing
+* between: so the commit can require what held at the start (a Database's lifecycle version). A reason
+* refuses the commit, and the mutation is refused as `unavailable` with nothing it wrote kept.
+* `read` is told how many rows each read gave a function, a mutation's own writes included.
+*/
+function databaseStandIn(options = {}) {
+	const clock = options.clock ?? Date.now;
+	const random = options.random ?? ((bytes) => crypto.getRandomValues(new Uint8Array(bytes)));
+	const tables = new Map(Object.entries(options.rows ?? {}).map(([name, rows]) => [name, new Map(Object.entries(rows))]));
+	const answers = /* @__PURE__ */ new Map();
+	const watchers = /* @__PURE__ */ new Set();
+	const scheduled = /* @__PURE__ */ new Map();
+	let loaded = null;
+	let turn = Promise.resolve();
+	const tableOf = (name) => {
+		let table = tables.get(name);
+		if (!table) tables.set(name, table = /* @__PURE__ */ new Map());
+		return table;
+	};
+	/**
+	* The rows a function reads: the committed ones, and those `overlay` wrote, which a mutation's own
+	* reads see. Each is a copy, so a function that changes a value it read changes only its copy: a
+	* kept row changes only by a write that commits, and so does every Database or branch sharing it.
+	*/
+	function reading(overlay) {
+		const get = (table, id) => {
+			const written = overlay?.get(table);
+			const row = written?.has(id) ? written.get(id) : tables.get(table)?.get(id);
+			return row ? structuredClone(row) : null;
+		};
+		const counted = (table, id) => {
+			const row = get(table, id);
+			if (row) options.read?.(1);
+			return row;
+		};
+		const range = (table, index, bounds) => {
+			const rows = [.../* @__PURE__ */ new Set([...tables.get(table)?.keys() ?? [], ...overlay?.get(table)?.keys() ?? []])].flatMap((id) => {
+				const row = get(table, id);
+				return row ? [{
+					...row,
+					_id: id
+				}] : [];
+			});
+			let fields = [];
+			if (index !== "_id") {
+				const declared = loaded?.indexes?.[table]?.[index];
+				if (declared === void 0) throw new Refusal("invalid", `${table} has no index ${index}`);
+				fields = indexFields(declared);
+			}
+			const keyOf = (row) => index === "_id" ? [row._id] : [...fields.map((field) => row[field]), row._id];
+			const eq = bounds.eq ?? [];
+			const at = eq.length;
+			const kept = rows.filter((row) => {
+				const key = keyOf(row);
+				if (eq.some((value, k) => compare(key[k], value) !== 0)) return false;
+				const next = key[at];
+				if (bounds.gte !== void 0 && compare(next, bounds.gte) < 0) return false;
+				if (bounds.gt !== void 0 && compare(next, bounds.gt) <= 0) return false;
+				if (bounds.lte !== void 0 && compare(next, bounds.lte) > 0) return false;
+				if (bounds.lt !== void 0 && compare(next, bounds.lt) >= 0) return false;
+				return true;
+			});
+			kept.sort((a, b) => {
+				const ka = keyOf(a), kb = keyOf(b);
+				for (let k = 0; k < ka.length; k += 1) {
+					const c = compare(ka[k], kb[k]);
+					if (c) return c;
+				}
+				return 0;
+			});
+			if (bounds.order === "desc") kept.reverse();
+			const page = kept.slice(0, bounds.limit);
+			options.read?.(page.length);
+			return page;
+		};
+		return {
+			get: counted,
+			range,
+			peek: get
+		};
+	}
+	function schedule(ms, name, args) {
+		const id = `s${hex(random(8))}`;
+		const entry = {
+			name,
+			args: wire(args),
+			due: clock() + ms,
+			state: "pending"
+		};
+		scheduled.set(id, entry);
+		entry.timer = setTimeout(() => {
+			if (entry.state !== "pending") return;
+			entry.state = "running";
+			invoke(name, entry.args, {
+				user: null,
+				server: true,
+				internal: true
+			}).then(() => {
+				entry.state = "success";
+			}, (error) => {
+				entry.state = "failed";
+				entry.error = refusalOf(error).message;
+			});
+		}, ms);
+		return id;
+	}
+	const scheduledRow = (id) => {
+		const entry = scheduled.get(id);
+		return entry ? {
+			name: entry.name,
+			args: entry.args,
+			due: entry.due,
+			state: entry.state,
+			...entry.error ? { error: entry.error } : {}
+		} : null;
+	};
+	const cancelScheduled = (id) => {
+		const entry = scheduled.get(id);
+		if (!entry || entry.state !== "pending") return false;
+		clearTimeout(entry.timer);
+		entry.state = "canceled";
+		return true;
+	};
+	function functionFor(name, kind, caller) {
+		const fn = loaded?.functions.get(name);
+		if (!fn) throw new DatabaseError("no function", `no function ${name}`);
+		if (fn.options.kind !== kind) throw new DatabaseError("no function", `no ${kind} ${name} (it is a ${fn.options.kind})`);
+		if (fn.options.internal && !caller.internal) throw new DatabaseError("internal", `${name} is internal: no client may call it`);
+		return fn;
+	}
+	function checked(fn, args) {
+		if (fn.options.args) {
+			const why = shapeError(fn.options.args, args ?? {}, "args");
+			if (why) throw new DatabaseError("invalid", why);
+		}
+	}
+	function answered(fn, value) {
+		if (fn.options.returns) {
+			const why = shapeError(fn.options.returns, value, "returns");
+			if (why) throw new DatabaseError("invalid", why);
+		}
+		return wire(value);
+	}
+	const refusedRows = (what) => () => {
+		throw new DatabaseError("refused", `a query ${what}: only a mutation writes`);
+	};
+	async function runQuery(fn, args, caller) {
+		const { get, range } = reading();
+		const rows = {
+			get,
+			range,
+			set: refusedRows("writes"),
+			delete: refusedRows("deletes"),
+			now: clock(),
+			user: caller.user,
+			server: caller.server,
+			issuer: null,
+			internal: caller.internal,
+			schema: loaded?.tables ?? null,
+			runAfter: refusedRows("schedules"),
+			scheduledRow,
+			cancelScheduled: refusedRows("cancels")
+		};
+		return answered(fn, await fn.handler(rows, args));
+	}
+	function runMutation(fn, args, caller, tag) {
+		const run = async () => {
+			const admitted = options.admits?.();
+			if (tag !== void 0) {
+				const had = answers.get(tag);
+				if (had) {
+					if (had.error) throw had.error;
+					return had.value;
+				}
+			}
+			const overlay = /* @__PURE__ */ new Map();
+			const later = [];
+			const { get, range, peek } = reading(overlay);
+			const written = (table) => {
+				let map = overlay.get(table);
+				if (!map) overlay.set(table, map = /* @__PURE__ */ new Map());
+				return map;
+			};
+			const rows = {
+				get,
+				range,
+				now: clock(),
+				user: caller.user,
+				server: caller.server,
+				issuer: null,
+				internal: caller.internal,
+				call: tag ?? `c${hex(random(8))}`,
+				schema: loaded?.tables ?? null,
+				set: (table, id, fields) => written(table).set(id, structuredClone({
+					...fields,
+					_version: (peek(table, id)?._version ?? 0) + 1
+				})),
+				delete: (table, id) => written(table).set(id, null),
+				runAfter: (ms, name, args) => {
+					const id = `s${hex(random(8))}`;
+					later.push({
+						ms,
+						name,
+						args
+					});
+					return id;
+				},
+				scheduledRow,
+				cancelScheduled
+			};
+			try {
+				const value = answered(fn, await fn.handler(rows, args));
+				const refused = admitted?.() ?? null;
+				if (refused !== null) throw new DatabaseError("unavailable", refused);
+				const changes = [];
+				for (const [table, changed] of overlay) for (const [id, row] of changed) {
+					if (row) tableOf(table).set(id, row);
+					else tables.get(table)?.delete(id);
+					changes.push({
+						table,
+						id,
+						row
+					});
+				}
+				if (changes.length) options.committed?.(changes);
+				for (const run of later) schedule(run.ms, run.name, run.args);
+				if (tag !== void 0) answers.set(tag, { value });
+				if (overlay.size) for (const watcher of watchers) watcher.run();
+				return value;
+			} catch (error) {
+				const refusal = refusalOf(error);
+				if (tag !== void 0) answers.set(tag, { error: refusal });
+				throw refusal;
+			}
+		};
+		const result = turn.then(run, run);
+		turn = result.catch(() => void 0);
+		return result;
+	}
+	async function runAction(fn, args, caller) {
+		const { get, range } = reading();
+		const capabilities = {
+			get: async (table, id) => get(table, id),
+			range: async (table, index, bounds) => range(table, index, bounds),
+			user: caller.user,
+			server: caller.server,
+			issuer: null,
+			internal: caller.internal,
+			fetch: (url, init) => fetch(url, init),
+			now: clock,
+			random,
+			run: (name, args) => invokeAny(name, args, {
+				...caller,
+				internal: true
+			}),
+			schedule: async (ms, name, args) => schedule(ms, name, args),
+			scheduled: async (id) => {
+				const row = scheduledRow(id);
+				return row ? {
+					name: row.name,
+					args: row.args,
+					at: row.due,
+					state: row.state,
+					...row.error ? { error: row.error } : {}
+				} : null;
+			},
+			cancel: async (id) => cancelScheduled(id)
+		};
+		return answered(fn, await fn.handler(capabilities, args));
+	}
+	async function invoke(name, args, caller, kind, tag) {
+		const fn = kind ? functionFor(name, kind, caller) : loaded?.functions.get(name);
+		if (!fn) throw new DatabaseError("no function", `no function ${name}`);
+		if (!kind) functionFor(name, fn.options.kind, caller);
+		const given = wire(args ?? {});
+		try {
+			checked(fn, given);
+			if (fn.options.kind === "query") return await runQuery(fn, given, caller);
+			if (fn.options.kind === "mutation") return await runMutation(fn, given, caller, tag);
+			return await runAction(fn, given, caller);
+		} catch (error) {
+			throw refusalOf(error);
+		}
+	}
+	const invokeAny = (name, args, caller) => invoke(name, args, caller);
+	const clientFor = (user) => callerClient({
+		user,
+		server: false,
+		internal: false
+	});
+	function callerClient(caller) {
+		return {
+			query: (fn, args) => invoke(nameOf(fn), args, caller, "query"),
+			mutation: (fn, args, options = {}) => invoke(nameOf(fn), args, caller, "mutation", options.tag),
+			action: (fn, args) => invoke(nameOf(fn), args, caller, "action"),
+			watch(fn, args, onValue) {
+				let last, stopped = false;
+				const watcher = { async run() {
+					try {
+						const value = await invoke(nameOf(fn), args, caller, "query");
+						const text = JSON.stringify(value);
+						if (!stopped && text !== last) {
+							last = text;
+							onValue(value);
+						}
+					} catch {}
+				} };
+				watchers.add(watcher);
+				watcher.run();
+				return () => {
+					stopped = true;
+					watchers.delete(watcher);
+				};
+			},
+			as: (subject) => clientFor(subject),
+			tag: async () => `t${hex(random(12))}`
+		};
+	}
+	function exclusive(work) {
+		const result = turn.then(work, work);
+		turn = result.catch(() => void 0);
+		return result;
+	}
+	return {
+		serve(next) {
+			loaded = next;
+			for (const watcher of watchers) watcher.run();
+		},
+		exclusive,
+		client: clientFor(null),
+		caller: callerClient,
+		kind: (name) => loaded?.functions.get(name)?.options.kind,
+		rows: () => Object.fromEntries([...tables].map(([name, rows]) => [name, Object.fromEntries(rows)])),
+		commit(write) {
+			return exclusive(() => {
+				const changes = write(Object.fromEntries([...tables].map(([name, rows]) => [name, Object.fromEntries(rows)])));
+				for (const change of changes) if (change.row) tableOf(change.table).set(change.id, change.row);
+				else tables.get(change.table)?.delete(change.id);
+				if (changes.length) {
+					options.committed?.(changes);
+					for (const watcher of watchers) watcher.run();
+				}
+				return changes;
+			});
+		},
+		close() {
+			for (const entry of scheduled.values()) clearTimeout(entry.timer);
+		}
+	};
+}
+//#endregion
+export { compare, databaseStandIn, loadDatabase };

package/email/client.d.mts

@@ -0,0 +1,34 @@
+import { CheckedMessage, EmailEngine, EmailErrorCode, SentMessage } from "./index.mjs";
+//#region src/email/client.d.ts
+declare const MESSAGES_PATH = "/email/messages";
+type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/** Email's engine at `origin` (the API's) for the Email key `key`. */
+declare function client(origin: string, options: {
+  readonly key: string;
+  readonly fetch?: Fetch;
+}): EmailEngine;
+/**
+ * The platform's side of the wire: checks the request again, as it comes from the network, and hands
+ * the key and the Message to `send`, which throws an `EmailError` for a refusal.
+ */
+declare function serveMessages(send: (key: string, message: CheckedMessage) => Promise<SentMessage>): (request: Request) => Promise<Response>;
+/** What a bound Email handle returns: the Message as sent, or the refusal, which crosses a Service Binding as data. */
+type BoundAnswer = SentMessage | {
+  readonly error: {
+    readonly code: EmailErrorCode;
+    readonly message: string;
+  };
+};
+/**
+ * What Midsummer hands a Deployment as `context.email`: sends from the Sending domains its
+ * Environment binds, with no key.
+ *
+ *   await email(boundEmail(context.email)).send({ from: "Acme <hi@acme.dev>", to: ["ada@example.com"], subject: "Hi", text: "Hello" })
+ */
+declare function boundEmail(handle: {
+  send(message: CheckedMessage): Promise<BoundAnswer>;
+}): EmailEngine;
+/** The platform's side of a bound handle: the same checks as `serveMessages`, a refusal returned as data. */
+declare function serveBound(send: (message: CheckedMessage) => Promise<SentMessage>): (message: unknown) => Promise<BoundAnswer>;
+//#endregion
+export { BoundAnswer, MESSAGES_PATH, boundEmail, client, serveBound, serveMessages };

package/email/client.mjs

@@ -0,0 +1,131 @@
+import { EmailError, email } from "./index.mjs";
+//#region src/email/client.ts
+/**
+* Email's wire: code holding an Email key sends through `client`, and the platform replies with
+* `serveMessages`. One Message is one POST of JSON to `<origin>/email/messages` with
+* `authorization: Bearer <the key's secret>`; the answer is the `SentMessage`, or
+* `{ "error": { "code", "message" } }` with the code's status.
+*
+*   const mail = email(client("https://api.<site>", { key }))
+*/
+const MESSAGES_PATH = "/email/messages";
+const STATUS = {
+	invalid: 400,
+	forbidden: 401,
+	unverified: 422,
+	unavailable: 503
+};
+/** Email's engine at `origin` (the API's) for the Email key `key`. */
+function client(origin, options) {
+	const url = `${origin.replace(/\/+$/, "")}${MESSAGES_PATH}`;
+	const fetcher = options.fetch ?? ((input, init) => fetch(input, init));
+	return { async send(message) {
+		let response;
+		try {
+			response = await fetcher(url, {
+				method: "POST",
+				headers: {
+					authorization: `Bearer ${options.key}`,
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(message)
+			});
+		} catch {
+			throw new EmailError("unavailable", "Email could not be reached");
+		}
+		const body = await response.json().catch(() => void 0);
+		if (response.ok && body && typeof body.id === "string") return body;
+		const code = body?.error?.code;
+		throw new EmailError(code && code in STATUS ? code : "unavailable", body?.error?.message ?? `Email answered ${response.status}`);
+	} };
+}
+/**
+* The platform's side of the wire: checks the request again, as it comes from the network, and hands
+* the key and the Message to `send`, which throws an `EmailError` for a refusal.
+*/
+function serveMessages(send) {
+	const refuse = (code, message) => Response.json({ error: {
+		code,
+		message
+	} }, { status: STATUS[code] });
+	return async (request) => {
+		if (request.method !== "POST") return Response.json({ error: {
+			code: "invalid",
+			message: "Use POST."
+		} }, { status: 405 });
+		const key = /^Bearer (\S+)$/.exec(request.headers.get("authorization") ?? "")?.[1];
+		if (!key) return refuse("forbidden", "Send with an Email key: authorization: Bearer <key>.");
+		const text = await request.text();
+		if (text.length > 2e6) return refuse("invalid", "A Message is at most 2 MB.");
+		let body;
+		try {
+			body = JSON.parse(text);
+		} catch {
+			body = void 0;
+		}
+		if (!isMessage(body)) return refuse("invalid", "The body is not a Message.");
+		try {
+			const sent = await email({ send: (message) => send(key, message) }).send(body);
+			return Response.json({
+				id: sent.id,
+				state: sent.state,
+				suppressed: sent.suppressed,
+				...sent.error !== void 0 ? { error: sent.error } : {}
+			});
+		} catch (error) {
+			if (error instanceof EmailError) return refuse(error.code, error.message);
+			throw error;
+		}
+	};
+}
+/**
+* What Midsummer hands a Deployment as `context.email`: sends from the Sending domains its
+* Environment binds, with no key.
+*
+*   await email(boundEmail(context.email)).send({ from: "Acme <hi@acme.dev>", to: ["ada@example.com"], subject: "Hi", text: "Hello" })
+*/
+function boundEmail(handle) {
+	return { async send(message) {
+		let answer;
+		try {
+			answer = await handle.send(message);
+		} catch {
+			throw new EmailError("unavailable", "Email could not be reached");
+		}
+		if ("id" in answer) return answer;
+		throw new EmailError(answer.error.code in STATUS ? answer.error.code : "unavailable", answer.error.message);
+	} };
+}
+/** The platform's side of a bound handle: the same checks as `serveMessages`, a refusal returned as data. */
+function serveBound(send) {
+	return async (message) => {
+		if (!isMessage(message)) return { error: {
+			code: "invalid",
+			message: "The body is not a Message."
+		} };
+		try {
+			const sent = await email({ send }).send(message);
+			return {
+				id: sent.id,
+				state: sent.state,
+				suppressed: sent.suppressed,
+				...sent.error !== void 0 ? { error: sent.error } : {}
+			};
+		} catch (error) {
+			if (error instanceof EmailError) return { error: {
+				code: error.code,
+				message: error.message
+			} };
+			throw error;
+		}
+	};
+}
+const strings = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+const optional = (value) => value === void 0 || typeof value === "string";
+function isMessage(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const m = value;
+	return typeof m.from === "string" && strings(m.to) && (m.cc === void 0 || strings(m.cc)) && (m.bcc === void 0 || strings(m.bcc)) && typeof m.subject === "string" && optional(m.replyTo) && optional(m.text) && optional(m.html) && optional(m.key);
+}
+//#endregion
+export { MESSAGES_PATH, boundEmail, client, serveBound, serveMessages };