@voltro/plugin-mail 0.85.0 → 0.87.0

package/dist/egress.js

@@ -0,0 +1,34 @@
+//#region src/egress.ts
+var e = {
+	lettermint: "api.lettermint.co",
+	resend: "api.resend.com",
+	postmark: "api.postmarkapp.com",
+	sendgrid: "api.sendgrid.com"
+}, t = (e) => {
+	try {
+		return new URL(e).host || void 0;
+	} catch {
+		return;
+	}
+}, n = (n) => {
+	let r = n.env ?? {}, i = (e) => [{
+		destination: e,
+		purpose: "outgoing email: recipients, subject and body",
+		data: ["personal", "content"],
+		disable: "MAIL_PROVIDER=console (or memory) logs mail instead of sending it — none leaves"
+	}];
+	if (n.provider !== void 0 && typeof n.provider != "string") {
+		let e = n.provider.name;
+		return e === "console" || e === "memory" ? [] : i(`runtime:the '${e}' mail provider`);
+	}
+	let a = n.provider ?? r.MAIL_PROVIDER ?? "console", o = e[a];
+	if (o !== void 0) return i(o);
+	switch (a) {
+		case "ses": return i(r.AWS_REGION ? `email.${r.AWS_REGION}.amazonaws.com` : "runtime:email.<AWS_REGION>.amazonaws.com");
+		case "mailgun": return i((r.MAILGUN_BASE_URL ? t(r.MAILGUN_BASE_URL) : void 0) ?? "api.mailgun.net");
+		case "smtp": return i((r.SMTP_URL ? t(r.SMTP_URL) : void 0) ?? (r.SMTP_HOST ? `${r.SMTP_HOST}${r.SMTP_PORT ? `:${r.SMTP_PORT}` : ""}` : void 0) ?? "runtime:SMTP_URL or SMTP_HOST");
+		default: return [];
+	}
+};
+//#endregion
+export { n as mailEgressOf };

package/dist/events.js

@@ -0,0 +1,46 @@
+import { Effect as e } from "effect";
+//#region src/events.ts
+var t = (e, t, n, r, i, a = {}) => {
+	if (!t) return null;
+	let o = a.metadata !== null && typeof a.metadata == "object" ? Object.fromEntries(Object.entries(a.metadata).filter(([, e]) => typeof e == "string")) : void 0;
+	return {
+		type: e,
+		email: t,
+		provider: n,
+		raw: i,
+		...r === void 0 ? {} : { messageId: r },
+		...a.eventId === void 0 ? {} : { eventId: a.eventId },
+		...o === void 0 ? {} : { metadata: o }
+	};
+}, n = (e) => e === "message.hard_bounced" ? "bounced" : e === "message.spam_complaint" ? "complained" : e === "message.unsubscribed" ? "unsubscribed" : e === "message.delivered" ? "delivered" : e === "message.opened" ? "opened" : e === "message.clicked" ? "clicked" : "unknown", r = (e) => e === "hard_bounce" ? "bounced" : e === "spam_complaint" ? "complained" : e === "unsubscribe" ? "unsubscribed" : "unknown", i = (e) => e === "email.bounced" ? "bounced" : e === "email.complained" ? "complained" : e === "email.delivered" ? "delivered" : e === "email.opened" ? "opened" : e === "email.clicked" ? "clicked" : "unknown", a = (e) => e === "Bounce" ? "bounced" : e === "SpamComplaint" ? "complained" : e === "Delivery" ? "delivered" : e === "Open" ? "opened" : e === "Click" ? "clicked" : "unknown", o = (e) => e === "bounce" || e === "dropped" ? "bounced" : e === "spamreport" ? "complained" : e === "delivered" ? "delivered" : e === "open" ? "opened" : e === "click" ? "clicked" : "unknown", s = (e, s) => {
+	let c = [], l = (e) => {
+		e && c.push(e);
+	};
+	if (e === "sendgrid" && Array.isArray(s)) {
+		for (let e of s) l(t(o(String(e.event)), e.email, "sendgrid", e.sg_message_id, e));
+		return c;
+	}
+	let u = s ?? {};
+	if (e === "lettermint") {
+		let e = String(u.event), i = u.data ?? {}, a = typeof u.id == "string" ? u.id : void 0;
+		return e === "suppression.added" ? (i.type === "email" && l(t(r(String(i.reason)), i.value, "lettermint", void 0, s, { eventId: a })), c) : e === "suppression.removed" ? (i.type === "email" && l(t("unsuppressed", i.value, "lettermint", void 0, s, { eventId: a })), c) : (e.startsWith("message.") && l(t(n(e), i.recipient, "lettermint", i.message_id, s, {
+			eventId: a,
+			metadata: i.metadata
+		})), c);
+	}
+	if (e === "resend") {
+		let e = u.data ?? {}, n = Array.isArray(e.to) ? e.to[0] : e.to ?? e.email;
+		return l(t(i(String(u.type)), n, "resend", e.email_id, s)), c;
+	}
+	if (e === "postmark") {
+		let e = u.Email ?? u.Recipient;
+		return l(t(a(String(u.RecordType)), e, "postmark", u.MessageID, s, { metadata: u.Metadata })), c;
+	}
+	return c;
+}, c = (t, n, r, i = null) => e.gen(function* () {
+	let e = s(t, n);
+	for (let t of e) t.type === "bounced" || t.type === "complained" ? yield* r.suppress(i, t.email, t.type) : t.type === "unsuppressed" && (yield* r.unsuppress(i, t.email));
+	return e;
+});
+//#endregion
+export { c as handleMailEvents, s as parseMailEvent };

package/dist/idempotency.js

@@ -0,0 +1,75 @@
+import { MAIL_IDEMPOTENCY_TABLE as e, attempt as t, describeError as n } from "./storeTables.js";
+import { Effect as r } from "effect";
+import { createLogger as i } from "@voltro/logger";
+import { and as a, eq as o } from "@voltro/database";
+//#region src/idempotency.ts
+var s = i({ scope: "@voltro/plugin-mail" }), c = (e) => e ?? "*", l = () => {
+	let e = /* @__PURE__ */ new Map(), t = (e, t) => `${c(e)} ${t}`;
+	return {
+		reserve: (n, i) => r.sync(() => {
+			let r = t(n, i);
+			if (e.has(r)) {
+				let t = e.get(r);
+				return t ? {
+					won: !1,
+					prior: t
+				} : { won: !1 };
+			}
+			return e.set(r, null), { won: !0 };
+		}),
+		record: (n, i, a) => r.sync(() => void e.set(t(n, i), a))
+	};
+}, u = () => {
+	let i = null;
+	return {
+		reserve: (a, o) => {
+			let l = i;
+			return l ? t(() => l.insertIgnoreWithOutcome(e, {
+				tenant: c(a),
+				key: o,
+				createdAt: /* @__PURE__ */ new Date()
+			}, { conflictColumns: ["tenant", "key"] })).pipe(r.map(({ row: e, outcome: t }) => {
+				if (t === "inserted") return { won: !0 };
+				let n = e.resultId, r = e.resultProvider;
+				return typeof n == "string" && typeof r == "string" ? {
+					won: !1,
+					prior: {
+						id: n,
+						provider: r
+					}
+				} : { won: !1 };
+			}), r.catch((e) => r.sync(() => (s.warn("idempotency reserve failed — skipping send to avoid a double", {
+				key: o,
+				message: n(e)
+			}), { won: !1 })))) : r.succeed({ won: !1 });
+		},
+		record: (l, u, d) => {
+			let f = i;
+			return f ? t(() => f.updateMany(e, {
+				resultId: d.id,
+				resultProvider: d.provider
+			}, { where: a(o("tenant", c(l)), o("key", u)) })).pipe(r.asVoid, r.catch((e) => r.sync(() => s.warn("idempotency record failed", {
+				key: u,
+				message: n(e)
+			})))) : r.void;
+		},
+		bind: async (e) => {
+			i = e;
+		}
+	};
+}, d = (n, i, s) => t(() => n.query({
+	table: e,
+	predicate: a(o("tenant", c(i)), o("key", s)),
+	projection: ["resultId", "resultProvider"],
+	order: [],
+	take: 1,
+	skip: void 0
+})).pipe(r.map((e) => {
+	let t = e[0], n = t?.resultId, r = t?.resultProvider;
+	return typeof n == "string" && n !== "" && typeof r == "string" && r !== "" ? {
+		id: n,
+		provider: r
+	} : null;
+}), r.catch(() => r.succeed(null)));
+//#endregion
+export { l as memoryIdempotencyStore, u as postgresIdempotencyStore, d as readMailReceipt };

package/dist/index.d.ts

@@ -1,10 +1,13 @@
+import { ColumnBuilder } from '@voltro/database';
 import { Context } from 'effect';
 import { DataStore } from '@voltro/database';
 import { Effect } from 'effect';
+import { FieldDefinitions } from '@voltro/database';
 import { Layer } from 'effect';
 import { PluginEgressDeclaration } from '@voltro/protocol';
 import { PluginHttpRouteRequest } from '@voltro/protocol';
 import { Schema } from 'effect';
+import { Table } from '@voltro/database';
 import { VoltroPlugin } from '@voltro/protocol';
 import { YieldableError } from 'effect/Cause';
 
@@ -215,6 +218,17 @@ export declare interface MailgunOptions {
 
 export declare const mailgunProvider: (options: MailgunOptions) => MailProvider;
 
+/** One row per idempotency key: the reservation, then the winning send's result. */
+export declare const mailIdempotencyTable: Table<"_voltro_mail_idempotency", FieldDefinitions<{
+    readonly id: ColumnBuilder<number, "id", boolean>;
+    readonly tenant: ColumnBuilder<string, "text", boolean>;
+    readonly key: ColumnBuilder<string, "text", boolean>;
+    readonly resultId: ColumnBuilder<string | null, "text", boolean>;
+    readonly resultProvider: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly created_at: ColumnBuilder<unknown, "text", boolean>;
+}>, false, never>;
+
 /** A message to send. `from` is optional here — the service fills it
  *  from the plugin's configured default before handing it to a provider. */
 export declare interface MailMessage {
@@ -245,6 +259,10 @@ export declare interface MailMessage {
      *  step. The first send with a given key delivers; a replay with the same
      *  key is a no-op returning the recorded result. Scoped per tenant. */
     readonly idempotencyKey?: string;
+    /** Override the service's transient retry count for this message. Zero means
+     * one provider dispatch, for callers that durably reconcile unknown outcomes.
+     * This is not a provider-side delivery/idempotency guarantee. */
+    readonly retryAttempts?: number;
     /** `transactional` (default) or `broadcast`. See `MailStream`. */
     readonly stream?: MailStream;
     /** How a recipient leaves a broadcast. See `MailUnsubscribe`. */
@@ -447,6 +465,17 @@ export declare interface MailServiceShape {
  */
 export declare type MailStream = 'transactional' | 'broadcast';
 
+/** One row per suppressed (tenant, address). Kept until lifted — a bounce or a
+ *  complaint does not expire, so this table has no retention policy. */
+export declare const mailSuppressionTable: Table<"_voltro_mail_suppression", FieldDefinitions<{
+    readonly id: ColumnBuilder<number, "id", boolean>;
+    readonly tenant: ColumnBuilder<string, "text", boolean>;
+    readonly email: ColumnBuilder<string, "text", boolean>;
+    readonly reason: ColumnBuilder<string | null, "text", boolean>;
+    readonly createdAt: ColumnBuilder<Date, "timestamp", true>;
+    readonly created_at: ColumnBuilder<unknown, "text", boolean>;
+}>, false, never>;
+
 /**
  * How a recipient leaves a broadcast. `oneClickUrl` is the HTTPS endpoint a
  * mail client POSTs `List-Unsubscribe=One-Click` to (RFC 8058); the service
@@ -543,6 +572,11 @@ export declare const postmarkProvider: (options: {
 /** Stable snapshot of everything the memory provider has "sent". */
 export declare const readMailBuffer: () => ReadonlyArray<ResolvedMessage>;
 
+/** Read a recorded persistent receipt without reserving a key or dispatching.
+ * Missing, pending, unbound or unavailable storage is not delivery evidence.
+ * The server caller owns authorization for the requested tenant/key. */
+export declare const readMailReceipt: (store: DataStore, tenantId: string | null, key: string) => Effect.Effect<SendResult | null>;
+
 /** Register CLI-discovered (or hand-collected) templates. Idempotent per key. */
 export declare const registerEmailTemplates: (templates: ReadonlyArray<AnyEmailTemplate>) => void;
 
@@ -697,6 +731,10 @@ export declare interface TemplateMessage {
     readonly scheduledAt?: Date;
     /** See `MailMessage.idempotencyKey`. */
     readonly idempotencyKey?: string;
+    /** Override the service's transient retry count for this message. Zero means
+     * one provider dispatch, for callers that durably reconcile unknown outcomes.
+     * This is not a provider-side delivery/idempotency guarantee. */
+    readonly retryAttempts?: number;
     /** See `MailMessage.stream`. */
     readonly stream?: MailStream;
     /** See `MailMessage.unsubscribe`. */