@abraca/resend 2.16.0

package/src/index.ts

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * @abraca/resend — entry point.
+ *
+ * Environment variables:
+ *   ABRA_URL                  (required) — Abracadabra server URL
+ *   ABRA_SPACE_ID             — Pin to a specific space (default: first visible)
+ *   ABRA_KEY_FILE             — Ed25519 seed path (default ~/.abracadabra/resend.key)
+ *   ABRA_INVITE_CODE          — Used only on first-run register
+ *   ABRA_AGENT_NAME           — Display name (default "Resend Bridge")
+ *
+ *   RESEND_API_KEY            (required) — Resend API key
+ *   RESEND_FROM               (required) — Default `from` address
+ *   RESEND_INBOUND_ENABLED    — "false" to skip the webhook server (default true)
+ *   RESEND_INBOUND_PORT       — Bind port for /inbound (default 0 = ephemeral)
+ *   RESEND_INBOUND_HOST       — Bind host (default 0.0.0.0)
+ *   RESEND_INBOUND_SECRET     — Required when inbound is enabled (Svix signing secret)
+ */
+import { bootstrap } from "./bootstrap.ts";
+import { InboundServer } from "./inbound-server.ts";
+import { OutboxWatcher } from "./outbox-watcher.ts";
+import { ResendClient } from "./resend-client.ts";
+import { AbracadabraResendServer } from "./server.ts";
+
+function required(name: string): string {
+	const value = process.env[name];
+	if (!value || value.trim().length === 0) {
+		console.error(`[abracadabra-resend] Missing required env var: ${name}`);
+		process.exit(1);
+	}
+	return value;
+}
+
+function boolEnv(name: string, fallback: boolean): boolean {
+	const v = process.env[name];
+	if (v === undefined) return fallback;
+	const norm = v.trim().toLowerCase();
+	if (["0", "false", "no", "off", ""].includes(norm)) return false;
+	return true;
+}
+
+async function main(): Promise<void> {
+	const url = required("ABRA_URL");
+	const resendApiKey = required("RESEND_API_KEY");
+	const defaultFrom = required("RESEND_FROM");
+
+	const inboundEnabled = boolEnv("RESEND_INBOUND_ENABLED", true);
+	const inboundSecret = inboundEnabled
+		? required("RESEND_INBOUND_SECRET")
+		: process.env.RESEND_INBOUND_SECRET ?? "";
+	const inboundPort = process.env.RESEND_INBOUND_PORT
+		? Number(process.env.RESEND_INBOUND_PORT)
+		: 0;
+	const inboundHost = process.env.RESEND_INBOUND_HOST ?? "0.0.0.0";
+
+	const server = new AbracadabraResendServer({
+		url,
+		spaceId: process.env.ABRA_SPACE_ID,
+		keyFile: process.env.ABRA_KEY_FILE,
+		inviteCode: process.env.ABRA_INVITE_CODE,
+		agentName: process.env.ABRA_AGENT_NAME,
+	});
+
+	try {
+		await server.connect();
+	} catch (err: any) {
+		console.error(`[abracadabra-resend] Failed to connect: ${err?.message ?? err}`);
+		process.exit(1);
+	}
+
+	const boot = await bootstrap(server);
+	console.error(
+		`[abracadabra-resend] Bootstrapped Inbox=${boot.inboxId} Outbox=${boot.outboxId}`,
+	);
+
+	const sender = new ResendClient(resendApiKey);
+	const watcher = new OutboxWatcher({ server, sender, bootstrap: boot, defaultFrom });
+	watcher.start();
+
+	let inbound: InboundServer | null = null;
+	if (inboundEnabled) {
+		inbound = new InboundServer({
+			server,
+			bootstrap: boot,
+			secret: inboundSecret,
+			port: Number.isFinite(inboundPort) ? inboundPort : 0,
+			host: inboundHost,
+		});
+		try {
+			await inbound.start();
+		} catch (err: any) {
+			console.error(
+				`[abracadabra-resend] Inbound server failed to start: ${err?.message ?? err}`,
+			);
+			process.exit(1);
+		}
+	} else {
+		console.error(
+			"[abracadabra-resend] Inbound disabled (RESEND_INBOUND_ENABLED=false)",
+		);
+	}
+
+	console.error("[abracadabra-resend] Ready.");
+
+	const shutdown = async () => {
+		console.error("[abracadabra-resend] Shutting down...");
+		watcher.stop();
+		if (inbound) await inbound.stop();
+		await server.destroy();
+		process.exit(0);
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+}
+
+main().catch((err) => {
+	console.error("[abracadabra-resend] Fatal error:", err);
+	process.exit(1);
+});
+
+export { AbracadabraResendServer } from "./server.ts";
+export { bootstrap } from "./bootstrap.ts";
+export { InboundServer } from "./inbound-server.ts";
+export { OutboxWatcher } from "./outbox-watcher.ts";
+export { ResendClient } from "./resend-client.ts";
+export type { ResendSender, SendResult } from "./resend-client.ts";
+export { renderEmail, RenderError } from "./render.ts";
+export type { EmailPayload } from "./render.ts";

package/src/outbox-watcher.ts

@@ -0,0 +1,283 @@
+/**
+ * Outbox watcher. Observes the doc-tree map (deeply, so per-entry parentId
+ * updates surface) and dispatches any doc that lands under the "Ready" column.
+ *
+ * Dispatch flow per doc:
+ *   render → resend.send → patch meta.resendId/sentAt → move to Sent
+ * On failure:
+ *   patch meta.error/errorAt → move to Failed (left for human triage)
+ *
+ * Idempotency:
+ *   - `meta.resendId` already set → skip (recovers from a restart that landed
+ *     between Resend ack and the post-send move).
+ *   - In-flight `Set<docId>` prevents the same observe burst from double-firing.
+ */
+import { patchEntry, toPlain } from "@abraca/dabra";
+import type * as Y from "yjs";
+import type { BootstrapResult } from "./bootstrap.ts";
+import { renderEmail, RenderError } from "./render.ts";
+import type { ResendSender } from "./resend-client.ts";
+import type { AbracadabraResendServer } from "./server.ts";
+
+export interface OutboxWatcherOptions {
+	server: AbracadabraResendServer;
+	sender: ResendSender;
+	bootstrap: BootstrapResult;
+	defaultFrom: string;
+}
+
+interface EntryView {
+	id: string;
+	label: string;
+	parentId: string | null;
+	meta: Record<string, unknown>;
+}
+
+function readEntry(treeMap: Y.Map<any>, id: string): EntryView | null {
+	const raw = treeMap.get(id);
+	if (!raw) return null;
+	const plain = toPlain(raw) as any;
+	if (!plain || typeof plain !== "object") return null;
+	return {
+		id,
+		label: typeof plain.label === "string" ? plain.label : "Untitled",
+		parentId: plain.parentId ?? null,
+		meta:
+			plain.meta && typeof plain.meta === "object"
+				? (plain.meta as Record<string, unknown>)
+				: {},
+	};
+}
+
+export class OutboxWatcher {
+	private readonly server: AbracadabraResendServer;
+	private readonly sender: ResendSender;
+	private readonly bootstrap: BootstrapResult;
+	private readonly defaultFrom: string;
+	private readonly inFlight = new Set<string>();
+	private readonly handled = new Set<string>();
+	private observer: ((events: Y.YEvent<any>[]) => void) | null = null;
+	private treeMap: Y.Map<any> | null = null;
+	private rootDoc: Y.Doc | null = null;
+	private txHandler: ((tx: Y.Transaction) => void) | null = null;
+
+	constructor(opts: OutboxWatcherOptions) {
+		this.server = opts.server;
+		this.sender = opts.sender;
+		this.bootstrap = opts.bootstrap;
+		this.defaultFrom = opts.defaultFrom;
+	}
+
+	start(): void {
+		const treeMap = this.server.getTreeMap();
+		if (!treeMap) {
+			throw new Error("OutboxWatcher.start: server is not connected");
+		}
+		this.treeMap = treeMap;
+
+		const rootDoc = this.server.rootDocument;
+		if (!rootDoc) {
+			throw new Error("OutboxWatcher.start: root doc not connected");
+		}
+		this.rootDoc = rootDoc;
+
+		// Initial scan — pick up anything already in Ready before we attached.
+		void this.scan("init");
+
+		// observeDeep on the tree map catches all the common edits (patchEntry
+		// mutating a nested Y.Map, treeMap.set replacing an entry).
+		const obs = (events: Y.YEvent<any>[]) => {
+			console.error(
+				`[abracadabra-resend] observeDeep fired (${events.length} events)`,
+			);
+			void this.scan("observeDeep");
+		};
+		treeMap.observeDeep(obs);
+		this.observer = obs;
+
+		// afterTransaction on the root Y.Doc fires for EVERY transaction applied
+		// to the doc — local writes and updates dispatched into this doc.
+		const onTx = (tx: Y.Transaction) => {
+			const changed: string[] = [];
+			for (const [type, events] of tx.changedParentTypes.entries()) {
+				const name = (type as any)._item ? (type as any)._item.parentSub : type.constructor.name;
+				const keys = events.flatMap((ev: any) => Array.from(ev.keysChanged ?? []));
+				changed.push(`${name ?? "type"}[${keys.join(",")}]`);
+			}
+			console.error(
+				`[abracadabra-resend] root afterTransaction (local=${tx.local}, origin=${String(tx.origin)}, changed=${changed.join(" | ") || "(none)"})`,
+			);
+			void this.scan("afterTransaction");
+		};
+		rootDoc.on("afterTransaction", onTx);
+		this.txHandler = onTx;
+
+		// Belt-and-suspenders: subdocs. abracadabra-rs may route some space-tree
+		// edits through subdoc payloads that don't fire transactions on the root
+		// doc directly. Watch every subdoc's transactions too.
+		const onSubdocs = (changes: { added: Set<Y.Doc>; removed: Set<Y.Doc>; loaded: Set<Y.Doc> }) => {
+			console.error(
+				`[abracadabra-resend] subdocs: added=${changes.added.size} loaded=${changes.loaded.size}`,
+			);
+			for (const sub of [...changes.added, ...changes.loaded]) {
+				sub.on("afterTransaction", (tx: Y.Transaction) => {
+					console.error(
+						`[abracadabra-resend] subdoc afterTransaction (guid=${sub.guid}, local=${tx.local})`,
+					);
+					void this.scan("subdoc");
+				});
+			}
+		};
+		rootDoc.on("subdocs", onSubdocs);
+
+		// Raw doc update — fires for every binary Yjs update applied to the doc,
+		// from any origin. If THIS doesn't fire when a remote writer changes
+		// state, the bridge's WS isn't delivering updates.
+		rootDoc.on("update", (_update: Uint8Array, origin: unknown) => {
+			console.error(
+				`[abracadabra-resend] root update applied (origin=${String(origin)})`,
+			);
+			void this.scan("update");
+		});
+
+		console.error(
+			`[abracadabra-resend] Outbox watcher attached (ready column ${this.bootstrap.columns.Ready})`,
+		);
+	}
+
+	stop(): void {
+		if (this.rootDoc && this.txHandler) {
+			this.rootDoc.off("afterTransaction", this.txHandler);
+		}
+		if (this.treeMap && this.observer) {
+			this.treeMap.unobserveDeep(this.observer);
+		}
+		this.txHandler = null;
+		this.rootDoc = null;
+		this.observer = null;
+		this.treeMap = null;
+	}
+
+	private async scan(reason: string): Promise<void> {
+		const treeMap = this.treeMap;
+		if (!treeMap) return;
+		const readyColId = this.bootstrap.columns.Ready;
+		const outboxId = this.bootstrap.outboxId;
+		const columnIds = new Set(Object.values(this.bootstrap.columns));
+		const candidates: EntryView[] = [];
+		let inReadyCount = 0;
+		let totalEntries = 0;
+		// Dump every entry whose ancestor is Outbox so we can compare bridge
+		// view vs cou-sh view.
+		const outboxSubtree: Array<{ id: string; label: string; parentId: string | null; under: string }> = [];
+		treeMap.forEach((_raw: any, id: string) => {
+			totalEntries++;
+			const e = readEntry(treeMap, id);
+			if (!e) return;
+			// classify under outbox: direct child of Outbox, or grandchild via a column
+			if (e.parentId === outboxId || (e.parentId && columnIds.has(e.parentId))) {
+				outboxSubtree.push({
+					id,
+					label: e.label,
+					parentId: e.parentId,
+					under: e.parentId === outboxId ? "Outbox" :
+						e.parentId === this.bootstrap.columns.Draft ? "Draft" :
+						e.parentId === this.bootstrap.columns.Ready ? "Ready" :
+						e.parentId === this.bootstrap.columns.Sent ? "Sent" :
+						e.parentId === this.bootstrap.columns.Failed ? "Failed" : "?",
+				});
+			}
+			if (e.parentId !== readyColId) return;
+			inReadyCount++;
+			if (this.inFlight.has(id) || this.handled.has(id)) return;
+			if (typeof e.meta.resendId === "string" && e.meta.resendId.length > 0) {
+				this.handled.add(id);
+				this.moveTo(id, this.bootstrap.columns.Sent);
+				return;
+			}
+			candidates.push(e);
+		});
+		console.error(
+			`[abracadabra-resend] scan(${reason}): ${totalEntries} entries, ${inReadyCount} in Ready, ${candidates.length} to dispatch | Outbox subtree (${outboxSubtree.length}): ${outboxSubtree.map((e) => `${e.under}:"${e.label}"`).join(", ")}`,
+		);
+
+		for (const entry of candidates) {
+			this.inFlight.add(entry.id);
+			void this.dispatch(entry).finally(() => {
+				this.inFlight.delete(entry.id);
+			});
+		}
+	}
+
+	private async dispatch(entry: EntryView): Promise<void> {
+		const { id, label } = entry;
+		try {
+			const payload = await renderEmail(this.server, id, this.defaultFrom);
+			console.error(
+				`[abracadabra-resend] sending "${payload.subject}" → ${payload.to.join(", ")} (doc=${id})`,
+			);
+			const { id: resendId } = await this.sender.send(payload, {
+				"X-Abra-Doc-Id": id,
+			});
+			this.handled.add(id);
+			this.patchMeta(id, { resendId, sentAt: Date.now(), error: null });
+			this.moveTo(id, this.bootstrap.columns.Sent);
+			console.error(
+				`[abracadabra-resend] sent "${payload.subject}" (resend=${resendId}, doc=${id})`,
+			);
+		} catch (err: any) {
+			this.handled.add(id);
+			const message =
+				err instanceof RenderError
+					? err.message
+					: err?.message
+						? String(err.message)
+						: String(err);
+			console.error(
+				`[abracadabra-resend] send failed for "${label}" (${id}): ${message}`,
+			);
+			this.patchMeta(id, { error: message, errorAt: Date.now() });
+			this.moveTo(id, this.bootstrap.columns.Failed);
+		}
+	}
+
+	private patchMeta(id: string, patch: Record<string, unknown>): void {
+		const treeMap = this.treeMap;
+		const rootDoc = this.server.rootDocument;
+		if (!treeMap || !rootDoc) return;
+		const current = readEntry(treeMap, id);
+		if (!current) return;
+		const nextMeta = { ...current.meta, ...patch };
+		for (const [k, v] of Object.entries(patch)) {
+			if (v === null) delete nextMeta[k];
+		}
+		rootDoc.transact(() => {
+			patchEntry(treeMap, id, {
+				meta: nextMeta,
+				updatedAt: Date.now(),
+			});
+		});
+	}
+
+	private moveTo(id: string, newParentId: string): void {
+		const treeMap = this.treeMap;
+		const rootDoc = this.server.rootDocument;
+		if (!treeMap || !rootDoc) return;
+		const now = Date.now();
+		rootDoc.transact(() => {
+			patchEntry(treeMap, id, {
+				parentId: newParentId,
+				order: now,
+				updatedAt: now,
+			});
+		});
+		// Best-effort registry reparent so REST/FTS sees the move too.
+		void this.server.client
+			.updateDocumentMeta(id, { parent_id: newParentId })
+			.catch((e) => {
+				console.error(
+					`[abracadabra-resend] REST reparent failed for ${id}: ${e?.message ?? e}`,
+				);
+			});
+	}
+}

package/src/render.ts

@@ -0,0 +1,112 @@
+/**
+ * Render an outbox document to an email-ready payload.
+ *
+ * Reads addressing from the doc's tree-entry `meta` (to/cc/bcc/subject/from/
+ * replyTo) and renders the body Y.XmlFragment via `@abraca/convert`'s
+ * `yjsToHtml` — which already emits a complete `<!DOCTYPE html>` doc with the
+ * doc label as `<h1>`, so the result is suitable as-is for Resend's `html`
+ * field.
+ */
+import { yjsToHtml } from "@abraca/convert";
+import { toPlain } from "@abraca/dabra";
+import type { AbracadabraResendServer } from "./server.ts";
+
+export interface EmailPayload {
+	subject: string;
+	html: string;
+	to: string[];
+	cc?: string[];
+	bcc?: string[];
+	from?: string;
+	replyTo?: string;
+}
+
+export class RenderError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RenderError";
+	}
+}
+
+function asStringArray(value: unknown): string[] {
+	if (Array.isArray(value)) {
+		return value
+			.filter((v): v is string => typeof v === "string" && v.trim().length > 0)
+			.map((v) => v.trim());
+	}
+	if (typeof value === "string" && value.trim().length > 0) {
+		// Allow `to: "alice@x.com, bob@y.com"` as a convenience.
+		return value
+			.split(",")
+			.map((s) => s.trim())
+			.filter((s) => s.length > 0);
+	}
+	return [];
+}
+
+function asOptionalString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim().length > 0
+		? value.trim()
+		: undefined;
+}
+
+interface OutboxEntry {
+	label: string;
+	meta: Record<string, unknown>;
+}
+
+function readEntry(
+	server: AbracadabraResendServer,
+	docId: string,
+): OutboxEntry | null {
+	const treeMap = server.getTreeMap();
+	if (!treeMap) return null;
+	const raw = treeMap.get(docId);
+	if (!raw) return null;
+	const plain = toPlain(raw) as any;
+	if (!plain || typeof plain !== "object") return null;
+	return {
+		label: typeof plain.label === "string" ? plain.label : "(no subject)",
+		meta:
+			plain.meta && typeof plain.meta === "object"
+				? (plain.meta as Record<string, unknown>)
+				: {},
+	};
+}
+
+export async function renderEmail(
+	server: AbracadabraResendServer,
+	docId: string,
+	defaultFrom: string,
+): Promise<EmailPayload> {
+	const entry = readEntry(server, docId);
+	if (!entry) {
+		throw new RenderError(`Doc ${docId} has no tree entry.`);
+	}
+
+	const to = asStringArray(entry.meta.to);
+	if (to.length === 0) {
+		throw new RenderError(
+			`Doc ${docId} has no recipients — set meta.to (array of email addresses).`,
+		);
+	}
+	const cc = asStringArray(entry.meta.cc);
+	const bcc = asStringArray(entry.meta.bcc);
+	const from = asOptionalString(entry.meta.from) ?? defaultFrom;
+	const replyTo = asOptionalString(entry.meta.replyTo);
+	const subject = asOptionalString(entry.meta.subject) ?? entry.label;
+
+	const provider = await server.getChildProvider(docId);
+	const fragment = provider.document.getXmlFragment("default");
+	const html = yjsToHtml(fragment, subject);
+
+	return {
+		subject,
+		html,
+		to,
+		cc: cc.length ? cc : undefined,
+		bcc: bcc.length ? bcc : undefined,
+		from,
+		replyTo,
+	};
+}

package/src/resend-client.ts

@@ -0,0 +1,50 @@
+/**
+ * Thin wrapper around the official `resend` SDK. Kept separate so tests can
+ * substitute a fake without mocking the SDK directly.
+ */
+import { Resend } from "resend";
+import type { EmailPayload } from "./render.ts";
+
+export interface SendResult {
+	id: string;
+}
+
+export interface ResendSender {
+	send(payload: EmailPayload, headers?: Record<string, string>): Promise<SendResult>;
+}
+
+export class ResendClient implements ResendSender {
+	private readonly resend: Resend;
+
+	constructor(apiKey: string) {
+		this.resend = new Resend(apiKey);
+	}
+
+	async send(
+		payload: EmailPayload,
+		headers?: Record<string, string>,
+	): Promise<SendResult> {
+		if (!payload.from) {
+			throw new Error("ResendClient.send: payload.from is required");
+		}
+		const { data, error } = await this.resend.emails.send({
+			from: payload.from,
+			to: payload.to,
+			cc: payload.cc,
+			bcc: payload.bcc,
+			subject: payload.subject,
+			html: payload.html,
+			replyTo: payload.replyTo,
+			headers,
+		});
+		if (error) {
+			throw new Error(
+				`Resend rejected the message: ${error.message ?? JSON.stringify(error)}`,
+			);
+		}
+		if (!data?.id) {
+			throw new Error("Resend returned no id for the dispatched message");
+		}
+		return { id: data.id };
+	}
+}