better-supabase 0.13.0 → 0.14.0

package/dist/blocks/mail-sync/index.js

@@ -0,0 +1,898 @@
+import { n as dbError } from "../../errors-03ysrOt4.js";
+import { t as temporal } from "../../temporal-required-B8qQHYbI.js";
+import { a as ok, r as err, t as AsyncResult } from "../../result-B3m7xtRY.js";
+import { n as isRecord } from "../../guards-6F2bCtQR.js";
+import { t as mailSyncSqlOptions } from "../../options-zkyhM3qi.js";
+import { A as requiredInstant, B as dbTransport, C as optionalText, D as recordOf, H as rpcTransport, I as textOf, S as optionalInstant, U as sqlTransport, k as recordsOf, m as instantArg, n as applyTemporal, o as blockCall } from "../../block-helpers-CiKtrb6g.js";
+import { i as wrapTransport, n as extendBlock, r as withBlockHooks } from "../../block-hooks-BymdcD0V.js";
+import { n as entitySchema } from "../../entity-schema-BXXC1NnT.js";
+import { n as credentialRefInTenant, r as foreignCredentialRef } from "../../provider-EJ0-5GwJ.js";
+import { n as event, t as defineEvents } from "../../event-map-CtPFhcOp.js";
+import { n as defineBlock } from "../../define-block-Dze77QTw.js";
+//#region src/blocks/mail-sync/providers.ts
+/** Checks the provider's `apiVersion` before the block uses it. */
+function mailProviderOf(provider) {
+	const version = provider.apiVersion;
+	if (version !== 1) throw new TypeError(`mail "${provider.name}" targets mail provider API ${String(version)}; this better-supabase supports 1. Upgrade better-supabase or use a release of the provider for API 1.`);
+	return provider;
+}
+const record = (value) => isRecord(value) ? value : {};
+const list = (value) => Array.isArray(value) ? value : [];
+const text = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+/** The `DbError` for a provider response that isn't a success. */
+async function httpError(provider, response) {
+	const body = await response.text().catch(() => "");
+	const message = `${provider} answered ${String(response.status)}${body.length > 0 ? `: ${body.slice(0, 300)}` : ""}`;
+	const retry = Number(response.headers.get("retry-after"));
+	const retryAfter = Number.isFinite(retry) && retry > 0 ? retry : void 0;
+	if (response.status === 401 || response.status === 403) return err(dbError("unauthorized", message, { hint: "MAIL_TOKEN_REFUSED" }));
+	if (response.status === 404) return err(dbError("not_found", message));
+	if (response.status === 429) return err(dbError("rate_limited", message, { ...retryAfter === void 0 ? {} : { retryAfter } }));
+	return err(dbError("network", message, { ...retryAfter === void 0 ? {} : { retryAfter } }));
+}
+function http(provider, base, token, options, headers = {}) {
+	const run = options.fetch ?? fetch;
+	const call = (path, init, signal) => AsyncResult.from(async () => {
+		const response = await run(path.startsWith("https://") ? path : `${base}${path}`, {
+			...init,
+			headers: {
+				accept: "application/json",
+				...headers,
+				...token.headers,
+				...init.body === void 0 ? {} : { "content-type": "application/json" }
+			},
+			...signal === void 0 ? {} : { signal }
+		});
+		if (!response.ok) return httpError(provider, response);
+		const body = await response.text();
+		return ok(body.length === 0 ? {} : record(JSON.parse(body)));
+	});
+	return {
+		get: (path, signal) => call(path, { method: "GET" }, signal),
+		post: (path, body, signal) => call(path, {
+			method: "POST",
+			body: JSON.stringify(body)
+		}, signal)
+	};
+}
+/** Splits `Name <a@b>, "Last, First" <c@d>` into addresses. */
+function parseAddresses(header) {
+	if (header === void 0) return [];
+	const parts = [];
+	let current = "";
+	let quoted = false;
+	let angled = false;
+	for (const char of header) {
+		if (char === "\"") quoted = !quoted;
+		else if (char === "<") angled = true;
+		else if (char === ">") angled = false;
+		if (char === "," && !quoted && !angled) {
+			parts.push(current);
+			current = "";
+		} else current += char;
+	}
+	parts.push(current);
+	return parts.flatMap((part) => {
+		const trimmed = part.trim();
+		const match = /^(.*)<([^<>]+)>$/.exec(trimmed);
+		const address = (match?.[2] ?? trimmed).trim().toLowerCase();
+		const name = match?.[1]?.trim().replaceAll(/^"|"$/g, "").trim();
+		if (!address.includes("@")) return [];
+		return [name === void 0 || name.length === 0 ? { address } : {
+			address,
+			name
+		}];
+	});
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function base64(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCodePoint(byte);
+	return btoa(binary);
+}
+const base64Url = (value) => base64(encoder.encode(value)).replaceAll("+", "-").replaceAll("/", "_").replace(/[=]+$/, "");
+function fromBase64Url(value) {
+	const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/"));
+	return decoder.decode(Uint8Array.from(binary, (char) => char.codePointAt(0) ?? 0));
+}
+/** A header value without line breaks, so it can't add a header. */
+const headerValue = (value) => value.replaceAll(/[\r\n]+/g, " ");
+/** RFC 2047 for a header with non-ASCII text. */
+function encodedWord(value) {
+	const clean = headerValue(value);
+	return /^[\u0020-\u007E]*$/.test(clean) ? clean : `=?UTF-8?B?${base64(encoder.encode(clean))}?=`;
+}
+const formatAddress = (address) => address.name === void 0 ? headerValue(address.address) : `${encodedWord(address.name)} <${headerValue(address.address)}>`;
+const wrap = (value) => (value.match(/.{1,76}/g) ?? []).join("\r\n");
+/**
+* The RFC 5322 message for a draft: a `multipart/alternative` with the text and
+* HTML parts, base64 encoded, and the reply headers when it answers one.
+*/
+function buildMime(input) {
+	const { draft, from, reply } = input;
+	const boundary = `bs-${input.messageId.replaceAll(/[^A-Za-z0-9]/g, "")}`;
+	const join = (addresses) => (addresses ?? []).map(formatAddress).join(", ");
+	const headers = [
+		`From: ${formatAddress(from)}`,
+		`To: ${join(draft.to)}`,
+		...(draft.cc ?? []).length > 0 ? [`Cc: ${join(draft.cc)}`] : [],
+		...(draft.bcc ?? []).length > 0 ? [`Bcc: ${join(draft.bcc)}`] : [],
+		`Subject: ${encodedWord(draft.subject)}`,
+		`Message-ID: ${headerValue(input.messageId)}`,
+		...reply?.messageId === void 0 ? [] : [`In-Reply-To: ${headerValue(reply.messageId)}`, `References: ${headerValue(reply.messageId)}`],
+		"MIME-Version: 1.0",
+		`Content-Type: multipart/alternative; boundary="${boundary}"`
+	];
+	const part = (type, body) => [
+		`--${boundary}`,
+		`Content-Type: ${type}; charset="UTF-8"`,
+		"Content-Transfer-Encoding: base64",
+		"",
+		wrap(base64(encoder.encode(body)))
+	].join("\r\n");
+	return [
+		...headers,
+		"",
+		part("text/plain", draft.text ?? ""),
+		...draft.html === void 0 ? [] : [part("text/html", draft.html)],
+		`--${boundary}--`,
+		""
+	].join("\r\n");
+}
+/** A `Message-ID` on the sender's domain. */
+function newMessageId(from) {
+	const domain = from.address.split("@")[1] ?? "localhost";
+	return `<${crypto.randomUUID()}@${domain}>`;
+}
+const GMAIL_SCOPES = ["https://www.googleapis.com/auth/gmail.readonly", "https://www.googleapis.com/auth/gmail.send"];
+/** The first part of `type` in a Gmail message part tree, decoded. */
+function gmailBody(value, type) {
+	const part = record(value);
+	const data = text(record(part["body"])["data"]);
+	if (part["mimeType"] === type && data !== void 0) return fromBase64Url(data);
+	for (const child of list(part["parts"])) {
+		const found = gmailBody(child, type);
+		if (found !== void 0) return found;
+	}
+}
+/** A Gmail API message (`format=full`) as a provider message. */
+function gmailMessage(value) {
+	const row = record(value);
+	const id = text(row["id"]);
+	const labels = list(row["labelIds"]);
+	if (id === void 0 || labels.includes("DRAFT")) return;
+	const payload = record(row["payload"]);
+	const headers = new Map(list(payload["headers"]).map((header) => {
+		const entry = record(header);
+		return [String(entry["name"] ?? "").toLowerCase(), String(entry["value"] ?? "")];
+	}));
+	const internal = Number(row["internalDate"]);
+	const sentAt = Number.isFinite(internal) ? temporal().Instant.fromEpochMilliseconds(internal) : temporal().Now.instant();
+	const from = parseAddresses(headers.get("from"))[0];
+	const subject = text(headers.get("subject"));
+	const messageId = text(headers.get("message-id"));
+	const snippet = text(row["snippet"]);
+	const plain = gmailBody(payload, "text/plain");
+	const html = gmailBody(payload, "text/html");
+	return {
+		externalId: id,
+		threadId: text(row["threadId"]) ?? id,
+		...messageId === void 0 ? {} : { messageId },
+		...labels.includes("SENT") ? { direction: "outbound" } : {},
+		...from === void 0 ? {} : { from },
+		to: parseAddresses(headers.get("to")),
+		cc: parseAddresses(headers.get("cc")),
+		...subject === void 0 ? {} : { subject },
+		...snippet === void 0 ? {} : { snippet },
+		...plain === void 0 ? {} : { text: plain },
+		...html === void 0 ? {} : { html },
+		sentAt
+	};
+}
+/**
+* Gmail through its REST API with the member's OAuth token: the first sync
+* reads the last `initialDays` of mail, later ones the history since the stored
+* `historyId`. No Google SDK is needed.
+*/
+function gmailMail(options = {}) {
+	const base = options.baseUrl ?? "https://gmail.googleapis.com/gmail/v1/users/me";
+	const days = options.initialDays ?? 30;
+	const fetchAll = (api, ids, signal) => AsyncResult.from(async () => {
+		const messages = [];
+		for (const id of ids) {
+			const read = await api.get(`/messages/${encodeURIComponent(id)}?format=full`, signal);
+			if (!read.ok) {
+				if (read.error.kind === "not_found") continue;
+				return read;
+			}
+			const message = gmailMessage(read.data);
+			if (message !== void 0) messages.push(message);
+		}
+		return ok(messages);
+	});
+	const initial = (api, input) => api.get("/profile", input.signal).andThen((profile) => api.get(`/messages?maxResults=${String(input.limit)}&q=${encodeURIComponent(`newer_than:${String(days)}d`)}`, input.signal).andThen((page) => fetchAll(api, list(page["messages"]).flatMap((entry) => {
+		const id = text(record(entry)["id"]);
+		return id === void 0 ? [] : [id];
+	}), input.signal)).map((messages) => ({
+		messages,
+		cursor: String(profile["historyId"] ?? ""),
+		more: false
+	})));
+	return {
+		apiVersion: 1,
+		name: "gmail",
+		scopes: GMAIL_SCOPES,
+		list: (input) => {
+			const api = http("gmail", base, input.token, options);
+			if (input.cursor === void 0 || input.cursor.length === 0) return initial(api, input);
+			return AsyncResult.from(async () => {
+				const history = await api.get(`/history?historyTypes=messageAdded&maxResults=${String(input.limit)}&startHistoryId=${encodeURIComponent(input.cursor ?? "")}`, input.signal);
+				if (!history.ok) return history.error.kind === "not_found" ? initial(api, {
+					token: input.token,
+					limit: input.limit,
+					...input.signal === void 0 ? {} : { signal: input.signal }
+				}) : history;
+				const records = list(history.data["history"]).map(record);
+				const ids = [...new Set(records.flatMap((entry) => list(entry["messagesAdded"]).flatMap((added) => {
+					const id = text(record(record(added)["message"])["id"]);
+					return id === void 0 ? [] : [id];
+				})))];
+				const more = text(history.data["nextPageToken"]) !== void 0;
+				const last = records.at(-1)?.["id"];
+				const cursor = String((more ? last : history.data["historyId"]) ?? input.cursor);
+				return fetchAll(api, ids, input.signal).map((messages) => ({
+					messages,
+					cursor,
+					more
+				}));
+			});
+		},
+		send: (input) => {
+			const api = http("gmail", base, input.token, options);
+			const messageId = newMessageId(input.from);
+			const raw = base64Url(buildMime({
+				from: input.from,
+				draft: input.draft,
+				messageId,
+				...input.reply === void 0 ? {} : { reply: input.reply }
+			}));
+			return api.post("/messages/send", {
+				raw,
+				...input.reply === void 0 ? {} : { threadId: input.reply.threadId }
+			}, input.signal).map((sent) => {
+				const id = String(sent["id"] ?? "");
+				return {
+					externalId: id,
+					threadId: String(sent["threadId"] ?? id),
+					messageId
+				};
+			});
+		}
+	};
+}
+const OUTLOOK_SCOPES = ["https://graph.microsoft.com/Mail.Read", "https://graph.microsoft.com/Mail.Send"];
+const OUTLOOK_FIELDS = "id,conversationId,internetMessageId,subject,bodyPreview,body,from,toRecipients,ccRecipients,sentDateTime,receivedDateTime,isDraft";
+const FOLDERS = ["inbox", "sentitems"];
+const outlookAddress = (value) => {
+	const email = record(record(value)["emailAddress"]);
+	const address = text(email["address"])?.toLowerCase();
+	const name = text(email["name"]);
+	if (address === void 0) return;
+	return name === void 0 ? { address } : {
+		address,
+		name
+	};
+};
+const outlookAddresses = (value) => list(value).flatMap((entry) => {
+	const address = outlookAddress(entry);
+	return address === void 0 ? [] : [address];
+});
+/** A Microsoft Graph message as a provider message. */
+function outlookMessage(value, folder) {
+	const row = record(value);
+	const id = text(row["id"]);
+	if (id === void 0 || row["isDraft"] === true || "@removed" in row) return;
+	const body = record(row["body"]);
+	const content = text(body["content"]);
+	const html = body["contentType"] === "html" ? content : void 0;
+	const plain = body["contentType"] === "html" ? void 0 : content;
+	const at = text(row["sentDateTime"]) ?? text(row["receivedDateTime"]);
+	const from = outlookAddress(row["from"]);
+	const messageId = text(row["internetMessageId"]);
+	const subject = text(row["subject"]);
+	const snippet = text(row["bodyPreview"]);
+	return {
+		externalId: id,
+		threadId: text(row["conversationId"]) ?? id,
+		...messageId === void 0 ? {} : { messageId },
+		direction: folder === "sentitems" ? "outbound" : "inbound",
+		...from === void 0 ? {} : { from },
+		to: outlookAddresses(row["toRecipients"]),
+		cc: outlookAddresses(row["ccRecipients"]),
+		...subject === void 0 ? {} : { subject },
+		...snippet === void 0 ? {} : { snippet },
+		...plain === void 0 ? {} : { text: plain },
+		...html === void 0 ? {} : { html },
+		sentAt: at === void 0 ? temporal().Now.instant() : temporal().Instant.from(at)
+	};
+}
+function outlookCursor(value) {
+	if (value === void 0 || value.length === 0) return {};
+	try {
+		const parsed = record(JSON.parse(value));
+		return Object.fromEntries(FOLDERS.flatMap((folder) => {
+			const link = text(parsed[folder]);
+			return link?.startsWith("https://") === true ? [[folder, link]] : [];
+		}));
+	} catch {
+		return {};
+	}
+}
+/**
+* Outlook and Microsoft 365 through Microsoft Graph with the member's OAuth
+* token: the inbox and sent items through delta queries, whose links are the
+* cursor. No Microsoft SDK is needed.
+*/
+function outlookMail(options = {}) {
+	const base = options.baseUrl ?? "https://graph.microsoft.com/v1.0";
+	const recipients = (addresses) => (addresses ?? []).map((address) => ({ emailAddress: {
+		address: address.address,
+		...address.name === void 0 ? {} : { name: address.name }
+	} }));
+	return {
+		apiVersion: 1,
+		name: "outlook",
+		scopes: OUTLOOK_SCOPES,
+		list: (input) => AsyncResult.from(async () => {
+			const api = http("outlook", base, input.token, options, { prefer: `odata.maxpagesize=${String(input.limit)}` });
+			const cursor = outlookCursor(input.cursor);
+			const next = {};
+			const messages = [];
+			let more = false;
+			for (const folder of FOLDERS) {
+				const page = await api.get(cursor[folder] ?? `/me/mailFolders/${folder}/messages/delta?$select=${OUTLOOK_FIELDS}`, input.signal);
+				if (!page.ok) return page;
+				for (const entry of list(page.data["value"])) {
+					const message = outlookMessage(entry, folder);
+					if (message !== void 0) messages.push(message);
+				}
+				const following = text(page.data["@odata.nextLink"]);
+				const delta = text(page.data["@odata.deltaLink"]);
+				more ||= following !== void 0;
+				const link = following ?? delta ?? cursor[folder];
+				if (link !== void 0) next[folder] = link;
+			}
+			return ok({
+				messages,
+				cursor: JSON.stringify(next),
+				more
+			});
+		}),
+		send: (input) => {
+			const api = http("outlook", base, input.token, options);
+			const message = {
+				subject: input.draft.subject,
+				body: input.draft.html === void 0 ? {
+					contentType: "text",
+					content: input.draft.text ?? ""
+				} : {
+					contentType: "html",
+					content: input.draft.html
+				},
+				toRecipients: recipients(input.draft.to),
+				ccRecipients: recipients(input.draft.cc),
+				bccRecipients: recipients(input.draft.bcc)
+			};
+			return (input.reply === void 0 ? api.post("/me/messages", message, input.signal) : api.post(`/me/messages/${encodeURIComponent(input.reply.externalId)}/createReply`, { message }, input.signal)).andThen((created) => {
+				const id = String(created["id"] ?? "");
+				const messageId = text(created["internetMessageId"]);
+				return api.post(`/me/messages/${encodeURIComponent(id)}/send`, {}, input.signal).map(() => ({
+					externalId: id,
+					threadId: String(created["conversationId"] ?? id),
+					...messageId === void 0 ? {} : { messageId }
+				}));
+			});
+		}
+	};
+}
+//#endregion
+//#region src/blocks/mail-sync/tracking.ts
+/**
+* At most this many links in one message are tracked; the rest stay as they
+* are.
+*/
+const MAX_LINKS = 100;
+const MAX_URL = 2048;
+const HREF = /(<a\b[^>]*?\bhref\s*=\s*)(["'])(https?:\/\/[^"']+)\2/giu;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/u;
+/** The transparent 1x1 GIF the open pixel answers with. */
+const PIXEL = Uint8Array.of(71, 73, 70, 56, 57, 97, 1, 0, 1, 0, 128, 0, 0, 0, 0, 0, 255, 255, 255, 33, 249, 4, 1, 0, 0, 0, 0, 44, 0, 0, 0, 0, 1, 0, 1, 0, 0, 2, 1, 68, 0, 59);
+const base64url = (bytes) => btoa(String.fromCodePoint(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/[=]+$/u, "");
+/** The SHA-256 of a tracking token, in hex. */
+async function trackingHash(token) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(token));
+	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+const decode = (url) => url.replaceAll("&amp;", "&");
+/**
+* Rewrites a message's `http(s)` links to go through `baseUrl/c/<token>/<n>`
+* and adds an open pixel at `baseUrl/o/<token>`. The token is random and only
+* its hash is stored, so a URL can't be guessed from the database.
+*/
+async function trackHtml(html, baseUrl) {
+	const token = base64url(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32)));
+	const base = baseUrl.replace(/\/+$/u, "");
+	const links = [];
+	const rewritten = html.replaceAll(HREF, (whole, start, quote, url) => {
+		const target = decode(url);
+		if (links.length >= MAX_LINKS || target.length > MAX_URL) return whole;
+		links.push(target);
+		return `${start}${quote}${base}/c/${token}/${String(links.length - 1)}${quote}`;
+	});
+	const pixel = `<img src="${base}/o/${token}" width="1" height="1" alt="" style="display:none">`;
+	const closing = rewritten.search(/<\/body>/iu);
+	return {
+		html: closing === -1 ? `${rewritten}${pixel}` : `${rewritten.slice(0, closing)}${pixel}${rewritten.slice(closing)}`,
+		hash: await trackingHash(token),
+		links
+	};
+}
+/** Reads `.../o/<token>` or `.../c/<token>/<n>` from a request URL. */
+function trackingHitOf(url) {
+	const parts = new URL(url).pathname.split("/").filter(Boolean);
+	const [kind, token, position] = parts.slice(parts.at(-3) === "c" ? -3 : -2);
+	if (token === void 0 || !TOKEN.test(token)) return;
+	if (kind === "o" && position === void 0) return {
+		kind: "open",
+		token
+	};
+	if (kind === "c" && position !== void 0 && /^\d{1,3}$/u.test(position)) return {
+		kind: "click",
+		token,
+		position: Number(position)
+	};
+}
+/** The open pixel's response: never cached, so each open reaches the route. */
+function pixelResponse() {
+	return new Response(PIXEL, { headers: {
+		"content-type": "image/gif",
+		"cache-control": "no-store, max-age=0"
+	} });
+}
+//#endregion
+//#region src/blocks/mail-sync/mail-sync.ts
+const SHARES = /* @__PURE__ */ new Set(["records", "private"]);
+const STATUSES = /* @__PURE__ */ new Set([
+	"active",
+	"paused",
+	"error",
+	"disconnected"
+]);
+function accountOf(value) {
+	const row = recordOf(value, "mail account");
+	const share = textOf(row["share"]);
+	const status = textOf(row["status"]);
+	const ref = row["credential_ref"];
+	if (!SHARES.has(share) || !STATUSES.has(status) || !isRecord(ref)) throw new TypeError(`mail account returned ${JSON.stringify(row)}`);
+	const optional = {
+		cursor: optionalText(row["sync_cursor"]),
+		lastSyncedAt: optionalInstant(row["last_synced_at"]),
+		lastError: optionalText(row["last_error"])
+	};
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["tenant_id"]),
+		userId: textOf(row["user_id"]),
+		provider: textOf(row["provider"]),
+		address: textOf(row["address"]),
+		credentialRef: {
+			...ref,
+			provider: textOf(ref["provider"])
+		},
+		share: share === "private" ? "private" : "records",
+		status: status === "paused" || status === "error" || status === "disconnected" ? status : "active",
+		createdAt: requiredInstant(row["created_at"], "createdAt"),
+		...Object.fromEntries(Object.entries(optional).filter(([, entry]) => entry !== void 0))
+	};
+}
+const subjectsOf = (value) => recordsOf(value, "mail thread subjects").map((subject) => ({
+	type: textOf(subject["type"]),
+	id: textOf(subject["id"])
+}));
+function threadOf(value) {
+	const row = recordOf(value, "mail thread");
+	const optional = {
+		subject: optionalText(row["subject"]),
+		snippet: optionalText(row["snippet"]),
+		lastMessageAt: optionalInstant(row["last_message_at"]),
+		engagementId: optionalText(row["engagement_id"])
+	};
+	return {
+		id: textOf(row["id"]),
+		organizationId: textOf(row["tenant_id"]),
+		accountId: textOf(row["account_id"]),
+		address: textOf(row["address"]),
+		externalId: textOf(row["external_id"]),
+		messageCount: Number(row["message_count"] ?? 0),
+		subjects: subjectsOf(row["subjects"]),
+		...Object.fromEntries(Object.entries(optional).filter(([, entry]) => entry !== void 0))
+	};
+}
+const texts = (value) => Array.isArray(value) ? value.map(textOf) : [];
+function messageOf(value) {
+	const row = recordOf(value, "mail message");
+	const address = optionalText(row["from_address"]);
+	const name = optionalText(row["from_name"]);
+	const optional = {
+		messageId: optionalText(row["rfc_message_id"]),
+		from: address === void 0 ? void 0 : name === void 0 ? { address } : {
+			address,
+			name
+		},
+		subject: optionalText(row["subject"]),
+		snippet: optionalText(row["snippet"]),
+		text: optionalText(row["body_text"]),
+		html: optionalText(row["body_html"]),
+		templateVersionId: optionalText(row["template_version_id"]),
+		openedAt: optionalInstant(row["opened_at"]),
+		clickedAt: optionalInstant(row["clicked_at"])
+	};
+	return {
+		id: textOf(row["id"]),
+		threadId: textOf(row["thread_id"]),
+		accountId: textOf(row["account_id"]),
+		externalId: textOf(row["external_id"]),
+		direction: row["direction"] === "outbound" ? "outbound" : "inbound",
+		to: texts(row["to_addresses"]),
+		cc: texts(row["cc_addresses"]),
+		sentAt: requiredInstant(row["sent_at"], "sentAt"),
+		tracked: typeof row["tracking_hash"] === "string",
+		openCount: Number(row["open_count"] ?? 0),
+		clickCount: Number(row["click_count"] ?? 0),
+		...Object.fromEntries(Object.entries(optional).filter(([, entry]) => entry !== void 0))
+	};
+}
+function detailOf(value) {
+	if (value === null || value === void 0) return;
+	const row = recordOf(value, "mail thread");
+	return {
+		...threadOf(row),
+		messages: recordsOf(row["messages"], "mail messages").map(messageOf)
+	};
+}
+/** A provider message as `ingest_mail` and `record_sent_mail` take it. */
+function messageArg(message) {
+	return {
+		externalId: message.externalId,
+		threadId: message.threadId,
+		sentAt: message.sentAt.toString(),
+		to: message.to,
+		cc: message.cc,
+		...message.messageId === void 0 ? {} : { messageId: message.messageId },
+		...message.direction === void 0 ? {} : { direction: message.direction },
+		...message.from === void 0 ? {} : { from: message.from },
+		...message.subject === void 0 ? {} : { subject: message.subject },
+		...message.snippet === void 0 ? {} : { snippet: message.snippet },
+		...message.text === void 0 ? {} : { text: message.text },
+		...message.html === void 0 ? {} : { html: message.html }
+	};
+}
+const missing = (message, hint) => dbError("invalid_input", message, { hint });
+/**
+* The mail-sync block: members connect Gmail, Outlook or another provider with
+* their own OAuth grant; a job pulls their mail into threads linked to the
+* people and companies on them, logged as email engagements; `send` sends from
+* the member's mailbox and stores the message.
+*/
+function createMailSync(options) {
+	applyTemporal(options);
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	const providers = new Map((options.providers ?? []).map((provider) => [provider.name, mailProviderOf(provider)]));
+	const providerOf = (account) => {
+		const provider = providers.get(account.provider);
+		return provider === void 0 ? err(missing(`createMailSync has no provider "${account.provider}"`, "MAIL_PROVIDER_MISSING")) : ok(provider);
+	};
+	const tokenOf = (account, provider) => {
+		const credentials = options.credentials;
+		if (credentials === void 0) return AsyncResult.err(missing("createMailSync needs credentials to resolve mailbox grants", "MAIL_CREDENTIALS_MISSING"));
+		if (!credentialRefInTenant(account.credentialRef, account.organizationId)) return AsyncResult.err(foreignCredentialRef(account.organizationId));
+		return credentials.getToken(account.credentialRef, {
+			subject: {
+				type: "user",
+				id: account.userId
+			},
+			...provider.scopes === void 0 ? {} : { scopes: provider.scopes }
+		});
+	};
+	const thread = (id) => call("get_mail_thread", { thread: id }, detailOf);
+	const replyTarget = (threadId) => threadId === void 0 ? AsyncResult.ok(void 0) : thread(threadId).andThen((found) => {
+		const last = found?.messages.at(-1);
+		if (found === void 0 || last === void 0) return AsyncResult.err(dbError("not_found", "no such thread with messages", { hint: "MAIL_THREAD_NOT_FOUND" }));
+		return AsyncResult.ok({
+			threadId: found.externalId,
+			externalId: last.externalId,
+			...last.messageId === void 0 ? {} : { messageId: last.messageId }
+		});
+	});
+	const sync = (account, run = {}) => AsyncResult.from(async () => {
+		const provider = providerOf(account);
+		if (!provider.ok) return provider;
+		const token = await tokenOf(account, provider.data);
+		if (!token.ok) return token;
+		let cursor = account.cursor;
+		let stored = 0;
+		for (let page = 0; page < (run.pages ?? 5); page += 1) {
+			const listed = await provider.data.list({
+				token: token.data,
+				limit: run.limit ?? 50,
+				...cursor === void 0 ? {} : { cursor }
+			});
+			if (!listed.ok) return listed;
+			const ingested = await call("ingest_mail", {
+				account: account.id,
+				messages: listed.data.messages.map(messageArg),
+				next_cursor: listed.data.cursor
+			}, (value) => Number(recordOf(value, "ingest_mail")["stored"] ?? 0));
+			if (!ingested.ok) return ingested;
+			stored += ingested.data;
+			cursor = listed.data.cursor;
+			if (!listed.data.more) break;
+		}
+		return ok(stored);
+	});
+	const sendMail = (accountId, draft) => call("get_mail_account", { account: accountId }, (value) => value === null ? void 0 : accountOf(value)).andThen(async (account) => {
+		if (account === void 0 || account.status === "disconnected") return err(dbError("not_found", "no such connected mailbox", { hint: "MAIL_ACCOUNT_NOT_FOUND" }));
+		const provider = providerOf(account);
+		if (!provider.ok) return provider;
+		const reply = await replyTarget(draft.threadId);
+		if (!reply.ok) return reply;
+		const token = await tokenOf(account, provider.data);
+		if (!token.ok) return token;
+		const from = { address: account.address };
+		const { threadId: _thread, templateVersionId, track, ...message } = draft;
+		const tracked = options.tracking === void 0 || track === false || draft.html === void 0 ? void 0 : await trackHtml(draft.html, options.tracking.url);
+		const sent = await provider.data.send({
+			token: token.data,
+			from,
+			draft: tracked === void 0 ? message : {
+				...message,
+				html: tracked.html
+			},
+			...reply.data === void 0 ? {} : { reply: reply.data }
+		});
+		if (!sent.ok) return sent;
+		return call("record_sent_mail", {
+			account: account.id,
+			message: {
+				...templateVersionId === void 0 ? {} : { templateVersionId },
+				...tracked === void 0 ? {} : {
+					trackingHash: tracked.hash,
+					trackedLinks: tracked.links
+				},
+				...messageArg({
+					externalId: sent.data.externalId,
+					threadId: sent.data.threadId,
+					...sent.data.messageId === void 0 ? {} : { messageId: sent.data.messageId },
+					direction: "outbound",
+					from,
+					to: draft.to,
+					cc: draft.cc ?? [],
+					subject: draft.subject,
+					...draft.text === void 0 ? {} : {
+						text: draft.text,
+						snippet: draft.text.slice(0, 200)
+					},
+					...draft.html === void 0 ? {} : { html: draft.html },
+					sentAt: temporal().Now.instant()
+				})
+			}
+		}, messageOf);
+	});
+	return withBlockHooks({
+		connect: (organizationId, input) => call("connect_mail_account", {
+			tenant: organizationId,
+			provider: input.provider,
+			address: input.address,
+			credential_ref: input.credentialRef,
+			share: input.share ?? null
+		}, accountOf),
+		update: (accountId, input) => call("update_mail_account", {
+			account: accountId,
+			share: input.share ?? null,
+			paused: input.paused ?? null
+		}, accountOf),
+		disconnect: (accountId, disconnect = {}) => call("disconnect_mail_account", {
+			account: accountId,
+			purge: disconnect.purge ?? false
+		}, (value) => value === true),
+		accounts: (organizationId) => call("mail_accounts_of", { tenant: organizationId }, (value) => recordsOf(value, "mail_accounts_of").map(accountOf)),
+		threads: (organizationId, list = {}) => call("list_mail_threads", {
+			tenant: organizationId,
+			account: list.accountId ?? null,
+			before: instantArg(list.before) ?? null,
+			page_size: list.limit ?? null
+		}, (value) => recordsOf(value, "list_mail_threads").map(threadOf)),
+		threadsOf: (subject, list = {}) => call("mail_threads_of", {
+			subject_type: subject.type,
+			subject_id: subject.id,
+			before: instantArg(list.before) ?? null,
+			page_size: list.limit ?? null
+		}, (value) => recordsOf(value, "mail_threads_of").map(threadOf)),
+		thread,
+		link: (threadId, subjects) => call("link_mail_thread", {
+			thread: threadId,
+			subjects: subjects.map((subject) => ({
+				type: subject.type,
+				id: subject.id
+			}))
+		}, threadOf),
+		unlink: (threadId, subject) => call("unlink_mail_thread", {
+			thread: threadId,
+			subject_type: subject.type,
+			subject_id: subject.id
+		}, (value) => value === true),
+		send: (accountId, draft) => draft.track === true && options.tracking === void 0 ? AsyncResult.err(missing("createMailSync needs tracking to track a message", "MAIL_TRACKING_MISSING")) : sendMail(accountId, draft),
+		sync,
+		track: (request) => AsyncResult.from(async () => {
+			const hit = trackingHitOf(request.url);
+			if (hit === void 0) return ok(new Response(null, { status: 404 }));
+			const tracked = await call("track_mail", {
+				hash: await trackingHash(hit.token),
+				kind: hit.kind,
+				link: hit.kind === "click" ? hit.position : null,
+				user_agent: request.headers.get("user-agent")?.slice(0, 300) ?? null
+			}, (value) => value === null ? void 0 : optionalText(recordOf(value, "track_mail")["url"]));
+			if (!tracked.ok) return tracked;
+			if (hit.kind === "open") return ok(pixelResponse());
+			return ok(tracked.data === void 0 ? new Response(null, { status: 404 }) : Response.redirect(tracked.data, 302));
+		}),
+		templateStats: (organizationId, stats = {}) => call("mail_template_stats", {
+			tenant: organizationId,
+			since: instantArg(stats.since) ?? null
+		}, (value) => recordsOf(value, "mail_template_stats").map((row) => ({
+			templateVersionId: String(row["templateVersionId"]),
+			sent: Number(row["sent"]),
+			opened: Number(row["opened"]),
+			clicked: Number(row["clicked"]),
+			replied: Number(row["replied"])
+		}))),
+		syncDue: (run = {}) => call("due_mail_accounts", {
+			max_count: run.accounts ?? null,
+			stale_after: run.staleAfter ?? null
+		}, (value) => recordsOf(value, "due_mail_accounts").map(accountOf)).andThen(async (accounts) => {
+			let stored = 0;
+			const failed = [];
+			for (const account of accounts) {
+				const result = await sync(account, {
+					...run.pages === void 0 ? {} : { pages: run.pages },
+					...run.limit === void 0 ? {} : { limit: run.limit }
+				});
+				if (result.ok) {
+					stored += result.data;
+					continue;
+				}
+				failed.push({
+					accountId: account.id,
+					message: result.error.message
+				});
+				const status = result.error.kind === "rate_limited" ? "active" : "error";
+				const marked = await call("set_mail_account_status", {
+					account: account.id,
+					status,
+					error: result.error.message
+				}, (value) => value === true);
+				if (!marked.ok) return marked;
+			}
+			return ok({
+				accounts: accounts.length,
+				stored,
+				failed
+			});
+		})
+	}, options.hooks, {
+		block: "mail-sync",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+//#region src/blocks/mail-sync/events.ts
+/** The `mail-sync` block's event types, for its manifest and `onBlockEvent`. */
+const mailSyncEvents = defineEvents({
+	"mail_account.connected": event(),
+	"mail_account.disconnected": event(),
+	"mail_message.received": event(),
+	"mail_message.sent": event(),
+	"mail_message.opened": event(),
+	"mail_message.clicked": event()
+});
+//#endregion
+//#region src/blocks/mail-sync/schemas.ts
+/** What `connect` takes. The SQL checks the address and the ref's tenant. */
+const mailAccountInputSchema = entitySchema({
+	title: "MailAccountInput",
+	fields: {
+		provider: {
+			kind: "string",
+			minLength: 1,
+			maxLength: 40
+		},
+		address: {
+			kind: "string",
+			minLength: 3,
+			maxLength: 320
+		},
+		credentialRef: {
+			kind: "json",
+			description: "The member's OAuth grant: { provider, tenant, ... }."
+		},
+		share: {
+			kind: "enum",
+			values: ["records", "private"],
+			optional: true
+		}
+	}
+});
+/** What `send` takes. */
+const mailDraftSchema = entitySchema({
+	title: "MailDraft",
+	fields: {
+		to: {
+			kind: "json",
+			array: true,
+			description: "The recipients: { address, name? }."
+		},
+		cc: {
+			kind: "json",
+			array: true,
+			optional: true
+		},
+		bcc: {
+			kind: "json",
+			array: true,
+			optional: true
+		},
+		subject: {
+			kind: "string",
+			maxLength: 998
+		},
+		text: {
+			kind: "string",
+			optional: true
+		},
+		html: {
+			kind: "string",
+			optional: true
+		},
+		threadId: {
+			kind: "uuid",
+			optional: true
+		},
+		templateVersionId: {
+			kind: "uuid",
+			optional: true
+		},
+		track: {
+			kind: "boolean",
+			optional: true
+		}
+	}
+});
+//#endregion
+//#region src/blocks/mail-sync/manifest.ts
+/** The `mail-sync` block's manifest (ADR 0029). */
+const mailSyncBlock = defineBlock({
+	name: "mail-sync",
+	sql: ["mail-sync"],
+	options: { "mail-sync": mailSyncSqlOptions },
+	events: mailSyncEvents,
+	schemas: {
+		mail_account: { input: mailAccountInputSchema },
+		mail_message: { input: mailDraftSchema }
+	},
+	provides: { mailer: (client) => client },
+	create: createMailSync,
+	category: "crm"
+});
+//#endregion
+export { buildMime, createMailSync, dbTransport, extendBlock, gmailMail, gmailMessage, mailAccountInputSchema, mailDraftSchema, mailProviderOf, mailSyncBlock, mailSyncEvents, mailSyncSqlOptions, messageArg, newMessageId, outlookMail, outlookMessage, parseAddresses, rpcTransport, sqlTransport, withBlockHooks, wrapTransport };