@voltro/plugin-mail 0.85.0 → 0.86.0

package/dist/service.js

@@ -0,0 +1,279 @@
+import { MailError as e, MailService as t, toList as n } from "./types.js";
+import { renderTemplate as r } from "./render.js";
+import { lookupGlobalTemplate as i } from "./registry.js";
+import { memorySuppressionStore as a } from "./suppression.js";
+import { memoryIdempotencyStore as o } from "./idempotency.js";
+import { makeScheduler as s, memoryScheduleStore as c } from "./scheduler.js";
+import { consoleProvider as l, lettermintProvider as u, mailgunProvider as d, memoryProvider as f, postmarkProvider as p, resendProvider as m, sendgridProvider as h, sesProvider as g, smtpProvider as _ } from "./providers.js";
+import { Effect as v, Layer as y, Schedule as b } from "effect";
+import { createLogger as x } from "@voltro/logger";
+//#region src/service.ts
+var S = x({ scope: "@voltro/plugin-mail" }), C = (e) => {
+	if (e.provider !== void 0 && typeof e.provider != "string") return e.provider;
+	let t = e.env ?? {}, n = e.provider ?? t.MAIL_PROVIDER ?? "console", r = (e, t) => {
+		if (!t) throw Error(`@voltro/plugin-mail: provider '${n}' needs apiKey or ${e}`);
+		return t;
+	};
+	switch (n) {
+		case "lettermint": return u({ projectToken: r("LETTERMINT_PROJECT_TOKEN", e.apiKey ?? t.LETTERMINT_PROJECT_TOKEN) });
+		case "resend": return m({ apiKey: r("RESEND_API_KEY", e.apiKey ?? t.RESEND_API_KEY) });
+		case "postmark": return p({ serverToken: r("POSTMARK_SERVER_TOKEN", e.apiKey ?? t.POSTMARK_SERVER_TOKEN) });
+		case "sendgrid": return h({ apiKey: r("SENDGRID_API_KEY", e.apiKey ?? t.SENDGRID_API_KEY) });
+		case "ses": return g({
+			region: r("AWS_REGION", t.AWS_REGION),
+			accessKeyId: r("AWS_ACCESS_KEY_ID", t.AWS_ACCESS_KEY_ID),
+			secretAccessKey: r("AWS_SECRET_ACCESS_KEY", t.AWS_SECRET_ACCESS_KEY),
+			...t.AWS_SESSION_TOKEN ? { sessionToken: t.AWS_SESSION_TOKEN } : {}
+		});
+		case "mailgun": return d({
+			apiKey: r("MAILGUN_API_KEY", e.apiKey ?? t.MAILGUN_API_KEY),
+			domain: r("MAILGUN_DOMAIN", t.MAILGUN_DOMAIN),
+			...t.MAILGUN_BASE_URL ? { baseUrl: t.MAILGUN_BASE_URL } : {}
+		});
+		case "smtp": {
+			if (t.SMTP_URL) return _({ url: t.SMTP_URL });
+			let e = r("SMTP_URL/SMTP_HOST", t.SMTP_HOST);
+			return _({
+				host: e,
+				...t.SMTP_PORT ? { port: Number(t.SMTP_PORT) } : {},
+				secure: t.SMTP_SECURE === "true",
+				...t.SMTP_USER && t.SMTP_PASS ? { auth: {
+					user: t.SMTP_USER,
+					pass: t.SMTP_PASS
+				} } : {}
+			});
+		}
+		case "memory": return f();
+		default: return l((e, t) => S.info(e, t));
+	}
+}, w = (t) => {
+	let l = t.attempts ?? 3, u = t.suppression ?? a(), d = t.allowlist, f = t.production !== !0 && d !== void 0 && d.length > 0, p = (e) => d.some((t) => t.toLowerCase() === e.toLowerCase()), m = b.recurs(l).pipe(b.while(({ input: e }) => e.transient)), h = /* @__PURE__ */ new Map();
+	for (let e of t.templates ?? []) h.set(e.locale ? `${e.name}:${e.locale}` : e.name, e);
+	let g = (e, t) => (t ? h.get(`${e}:${t}`) : void 0) ?? h.get(e) ?? i(e, t), _ = /* @__PURE__ */ new Map(), y = (e, t) => `${e.name}|${e.locale ?? ""}|${JSON.stringify(t ?? null)}`, x = (e, t) => {
+		if (_.set(e, t), _.size > 500) {
+			let e = _.keys().next().value;
+			e !== void 0 && _.delete(e);
+		}
+	}, C = t.idempotency ?? o(), w = s({
+		store: t.schedule ?? c(),
+		providerSchedules: t.provider.supportsScheduling === !0,
+		flush: (e) => O(e)
+	}), T = (n) => {
+		if (n.stream !== "broadcast" || t.provider.managesUnsubscribe === !0) return v.succeed(void 0);
+		let r = n.unsubscribe;
+		if (r === void 0 || !r.oneClickUrl.startsWith("https://")) return v.fail(new e({
+			provider: t.provider.name,
+			message: `a broadcast needs \`unsubscribe: { oneClickUrl }\` (an https URL) — '${t.provider.name}' does not unsubscribe recipients itself`,
+			transient: !1
+		}));
+		let i = [`<${r.oneClickUrl}>`, ...r.mailto === void 0 ? [] : [`<mailto:${r.mailto.replace(/^mailto:/, "")}>`]];
+		return v.succeed({
+			"List-Unsubscribe": i.join(", "),
+			"List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+		});
+	}, E = (r) => v.gen(function* () {
+		let i = r.from ?? t.from;
+		if (!i) return yield* v.fail(new e({
+			provider: t.provider.name,
+			message: "no `from` — set mailPlugin({ from }) or pass message.from",
+			transient: !1
+		}));
+		let a = n(r.to);
+		if (f) {
+			let e = a.filter(p);
+			if (e.length === 0) return S.warn("mail skipped — no recipient in allowlist (non-production)", {
+				to: a.join(","),
+				subject: r.subject
+			}), t.onSent?.({
+				id: "skipped-allowlist",
+				to: a,
+				from: i,
+				subject: r.subject,
+				provider: "skipped",
+				ok: !0,
+				ts: Date.now()
+			}), {
+				kind: "skip",
+				result: {
+					id: "skipped-allowlist",
+					provider: "skipped"
+				}
+			};
+			a = e;
+		}
+		let o = r.tenantId ?? null, s = [];
+		for (let e of a) (yield* u.isSuppressed(o, e)) || s.push(e);
+		if (s.length === 0) return S.warn("mail skipped — all recipients suppressed", {
+			to: a.join(","),
+			subject: r.subject
+		}), t.onSent?.({
+			id: "skipped-suppressed",
+			to: a,
+			from: i,
+			subject: r.subject,
+			provider: "suppressed",
+			ok: !0,
+			ts: Date.now()
+		}), {
+			kind: "skip",
+			result: {
+				id: "skipped-suppressed",
+				provider: "suppressed"
+			}
+		};
+		a = s;
+		let c = r.replyTo ?? t.replyTo, l = yield* T(r), d = l === void 0 ? r.headers : {
+			...r.headers,
+			...l
+		};
+		return {
+			kind: "send",
+			message: {
+				...r,
+				from: i,
+				to: a,
+				...c === void 0 ? {} : { replyTo: c },
+				...d === void 0 ? {} : { headers: d }
+			}
+		};
+	}), D = (e) => {
+		let r = n(e.to);
+		return t.provider.send(e).pipe(v.retry(m), v.tap((n) => v.sync(() => {
+			S.info("mail sent", {
+				provider: n.provider,
+				id: n.id,
+				to: r.join(",")
+			}), t.onSent?.({
+				id: n.id,
+				to: r,
+				from: e.from,
+				subject: e.subject,
+				provider: n.provider,
+				ok: !0,
+				ts: Date.now()
+			});
+		})), v.tapError((n) => v.sync(() => {
+			S.warn("mail failed", {
+				provider: n.provider,
+				status: n.status,
+				message: n.message
+			}), t.onSent?.({
+				id: `err-${Date.now()}`,
+				to: r,
+				from: e.from,
+				subject: e.subject,
+				provider: n.provider,
+				ok: !1,
+				error: n.message,
+				ts: Date.now()
+			});
+		})));
+	}, O = (e) => v.gen(function* () {
+		let r = yield* E(e);
+		return r.kind === "skip" ? r.result : w.shouldHold(e.scheduledAt) ? (yield* w.hold(r.message), S.info("mail scheduled (held for later flush)", {
+			subject: r.message.subject,
+			dueAt: e.scheduledAt?.toISOString()
+		}), t.onSent?.({
+			id: "scheduled",
+			to: n(r.message.to),
+			from: r.message.from,
+			subject: r.message.subject,
+			provider: "scheduled",
+			ok: !0,
+			ts: Date.now()
+		}), {
+			id: "scheduled",
+			provider: "scheduled"
+		}) : yield* D(r.message);
+	}), k = (e, t, n) => t === void 0 ? n : v.gen(function* () {
+		let r = yield* C.reserve(e, t);
+		if (!r.won) return S.info("mail idempotent replay — skipped", { key: t }), r.prior ?? {
+			id: "idempotent-replay",
+			provider: "idempotent"
+		};
+		let i = yield* n;
+		return yield* C.record(e, t, i), i;
+	}), A = (t) => v.suspend(() => {
+		let n = g(t.template, t.locale);
+		if (!n) return v.fail(new e({
+			provider: "template",
+			message: `unknown template '${t.template}'${t.locale ? ` (locale '${t.locale}')` : ""}`,
+			transient: !1
+		}));
+		let i = y(n, t.props), a = _.get(i);
+		return (a ? v.succeed(a) : r(n, t.props).pipe(v.tap((e) => v.sync(() => x(i, e))))).pipe(v.map((e) => ({
+			to: t.to,
+			subject: e.subject,
+			html: e.html,
+			text: e.text,
+			...t.from === void 0 ? {} : { from: t.from },
+			...t.replyTo === void 0 ? {} : { replyTo: t.replyTo },
+			...t.cc === void 0 ? {} : { cc: t.cc },
+			...t.bcc === void 0 ? {} : { bcc: t.bcc },
+			...t.headers === void 0 ? {} : { headers: t.headers },
+			...t.tags === void 0 ? {} : { tags: t.tags },
+			...t.attachments === void 0 ? {} : { attachments: t.attachments },
+			...t.tenantId === void 0 ? {} : { tenantId: t.tenantId },
+			...t.scheduledAt === void 0 ? {} : { scheduledAt: t.scheduledAt },
+			...t.idempotencyKey === void 0 ? {} : { idempotencyKey: t.idempotencyKey },
+			...t.stream === void 0 ? {} : { stream: t.stream },
+			...t.unsubscribe === void 0 ? {} : { unsubscribe: t.unsubscribe },
+			...t.metadata === void 0 ? {} : { metadata: t.metadata }
+		})));
+	}), j = (e) => "template" in e ? A(e) : v.succeed(e);
+	return {
+		service: {
+			send: (e) => v.gen(function* () {
+				let t = yield* j(e);
+				return yield* k(t.tenantId ?? null, t.idempotencyKey, O(t));
+			}),
+			sendBatch: (e) => v.gen(function* () {
+				let r = yield* v.forEach(e, j), i = r.some((e) => e.idempotencyKey !== void 0 || w.shouldHold(e.scheduledAt));
+				if (t.provider.sendBatch && !i) {
+					let e = [], i = [];
+					for (let t of r) {
+						let n = yield* E(t);
+						n.kind === "skip" ? i.push(n.result) : (i.push(e.length), e.push(n.message));
+					}
+					let a = e.length > 0 ? yield* t.provider.sendBatch(e).pipe(v.retry(m), v.tap((r) => v.sync(() => {
+						e.forEach((e, i) => {
+							let a = r[i];
+							a && (S.info("mail sent (batch)", {
+								provider: a.provider,
+								id: a.id,
+								to: n(e.to).join(",")
+							}), t.onSent?.({
+								id: a.id,
+								to: n(e.to),
+								from: e.from,
+								subject: e.subject,
+								provider: a.provider,
+								ok: !0,
+								ts: Date.now()
+							}));
+						});
+					})), v.tapError((e) => v.sync(() => S.warn("mail batch failed", {
+						provider: e.provider,
+						status: e.status,
+						message: e.message
+					})))) : [];
+					return i.map((e) => typeof e == "number" ? a[e] ?? {
+						id: "batch",
+						provider: t.provider.name
+					} : e);
+				}
+				return yield* v.forEach(r, (e) => k(e.tenantId ?? null, e.idempotencyKey, O(e)));
+			}),
+			suppress: u.suppress,
+			unsuppress: u.unsuppress,
+			isSuppressed: u.isSuppressed,
+			provider: {
+				name: t.provider.name,
+				managesUnsubscribe: t.provider.managesUnsubscribe === !0
+			}
+		},
+		scheduler: w
+	};
+}, T = (e) => w(e).service, E = (e) => y.succeed(t, T(e));
+//#endregion
+export { T as buildMailService, w as buildMailServiceWithScheduler, E as mailServiceLayer, C as resolveProvider };

package/dist/skeleton.js

@@ -0,0 +1,24 @@
+//#region src/skeleton.ts
+var e = (t, n) => {
+	if (n > 6) return null;
+	let r = t.encoding === void 0 ? t : t.encoding[t.encoding.length - 1].to;
+	if (r !== t) return e(r, n + 1);
+	switch (t._tag) {
+		case "String": return "";
+		case "Number": return 0;
+		case "Boolean": return !1;
+		case "Literal": return t.literal;
+		case "Enum": return t.enums.length > 0 ? t.enums[0][1] : null;
+		case "Objects": {
+			let r = {};
+			for (let i of t.propertySignatures) typeof i.name == "string" && (r[i.name] = e(i.type, n + 1));
+			return r;
+		}
+		case "Arrays": return [];
+		case "Union": return t.types.length > 0 ? e(t.types[0], n + 1) : null;
+		case "Suspend": return e(t.thunk(), n + 1);
+		default: return null;
+	}
+}, t = (t) => e(t.ast, 0);
+//#endregion
+export { t as schemaSkeleton };

package/dist/storeTables.js

@@ -0,0 +1,28 @@
+import { Effect as e } from "effect";
+import { dropped as t, id as n, table as r, text as i, timestamp as a } from "@voltro/database";
+//#region src/storeTables.ts
+var o = "_voltro_mail_suppression", s = "_voltro_mail_idempotency", c = r(o, {
+	id: n({ scheme: "numeric" }),
+	tenant: i().maxLength(191),
+	email: i().maxLength(320),
+	reason: i().nullable(),
+	createdAt: a().default("now"),
+	created_at: t()
+}).unique("mailSuppressionAddress", ["tenant", "email"]).nonReactive(), l = r(s, {
+	id: n({ scheme: "numeric" }),
+	tenant: i().maxLength(191),
+	key: i().maxLength(255),
+	resultId: i().nullable().renamedFrom("result_id"),
+	resultProvider: i().nullable().renamedFrom("result_provider"),
+	createdAt: a().default("now"),
+	created_at: t()
+}).unique("mailIdempotencyKey", ["tenant", "key"]).nonReactive(), u = (t) => e.tryPromise({
+	try: t,
+	catch: (e) => e
+}), d = (e) => {
+	let t = [];
+	for (let n = e, r = 0; n != null && r < 4; n = n.cause, r++) t.push(n instanceof Error ? n.message : String(n));
+	return t.join(" ← ");
+};
+//#endregion
+export { s as MAIL_IDEMPOTENCY_TABLE, o as MAIL_SUPPRESSION_TABLE, u as attempt, d as describeError, l as mailIdempotencyTable, c as mailSuppressionTable };

package/dist/suppression.js

@@ -0,0 +1,46 @@
+import { MAIL_SUPPRESSION_TABLE as e, attempt as t, describeError as n, mailSuppressionTable as r } from "./storeTables.js";
+import { Effect as i } from "effect";
+import { createLogger as a } from "@voltro/logger";
+import { and as o, eq as s, inSet as c, queryFor as l } from "@voltro/database";
+//#region src/suppression.ts
+var u = a({ scope: "@voltro/plugin-mail" }), d = (e) => e.trim().toLowerCase(), f = "*", p = (e) => e ?? f, m = () => {
+	let e = /* @__PURE__ */ new Set(), t = (e, t) => `${p(e)}\u0000${d(t)}`;
+	return {
+		isSuppressed: (n, r) => i.sync(() => e.has(t(n, r)) || e.has(t(null, r))),
+		suppress: (n, r) => i.sync(() => void e.add(t(n, r))),
+		unsuppress: (n, r) => i.sync(() => void e.delete(t(n, r)))
+	};
+}, h = () => {
+	let a = null, m = (e, t) => ({
+		tenant: p(e),
+		email: d(t)
+	});
+	return {
+		isSuppressed: (e, n) => {
+			let u = a;
+			return u ? t(() => u.query(l(r).where(o(s("email", d(n)), c("tenant", [p(e), f]))).limit(1).descriptor)).pipe(i.map((e) => e.length > 0), i.catch(() => i.succeed(!1))) : i.succeed(!1);
+		},
+		suppress: (r, o, s) => {
+			let c = a;
+			return c ? t(() => c.upsert(e, {
+				...m(r, o),
+				reason: s,
+				createdAt: /* @__PURE__ */ new Date()
+			}, { conflictColumns: ["tenant", "email"] })).pipe(i.asVoid, i.catch((e) => i.sync(() => u.warn("suppress write failed", {
+				email: d(o),
+				message: n(e)
+			})))) : i.void;
+		},
+		unsuppress: (n, r) => {
+			let c = a;
+			if (!c) return i.void;
+			let { tenant: l, email: u } = m(n, r);
+			return t(() => c.deleteMany(e, { where: o(s("tenant", l), s("email", u)) })).pipe(i.asVoid, i.catch(() => i.void));
+		},
+		bind: async (e) => {
+			a = e;
+		}
+	};
+};
+//#endregion
+export { m as memorySuppressionStore, h as postgresSuppressionStore };

package/dist/types.js

@@ -0,0 +1,20 @@
+import { Context as e, Schema as t } from "effect";
+//#region src/types.ts
+var n = class extends t.TaggedError()("MailError", {
+	provider: t.String,
+	message: t.String,
+	transient: t.Boolean,
+	status: t.optional(t.Number)
+}) {}, r = class extends t.TaggedError()("MailWebhookError", {
+	provider: t.String,
+	message: t.String
+}) {}, i = (e) => ({
+	name: e.name,
+	props: e.props,
+	subject: e.subject,
+	render: e.render,
+	...e.locale === void 0 ? {} : { locale: e.locale },
+	...e.preview === void 0 ? {} : { preview: e.preview }
+}), a = class extends e.Service()("@voltro/plugin-mail/MailService") {}, o = (e) => e === void 0 ? [] : typeof e == "string" ? [e] : e;
+//#endregion
+export { n as MailError, a as MailService, r as MailWebhookError, i as defineEmail, o as toList };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-mail",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "Transactional and broadcast email — one MailProvider contract, multiple adapters (Lettermint / Resend / Postmark / SendGrid / SES / Mailgun / SMTP + console/memory for dev/test). Exposes a MailService via the plugin services layer with transient retry, suppression, a mounted delivery-event webhook and a dev allowlist.",
   "keywords": [
     "voltro",
@@ -33,10 +33,10 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/database": "0.85.0",
-    "@voltro/env": "0.85.0",
-    "@voltro/logger": "0.85.0",
-    "@voltro/protocol": "0.85.0"
+    "@voltro/database": "0.86.0",
+    "@voltro/env": "0.86.0",
+    "@voltro/logger": "0.86.0",
+    "@voltro/protocol": "0.86.0"
   },
   "optionalDependencies": {
     "nodemailer": "^10.0.10"