@voltro/plugin-mail 0.80.0 → 0.82.0

package/README.md

@@ -2,7 +2,7 @@
 
 # @voltro/plugin-mail
 
-**Transactional email plugin — one MailProvider contract, multiple adapters (Resend / Postmark / SendGrid / SMTP + console/memory for dev/test). Exposes a MailService via the plugin services layer with transient retry and a dev allowlist.**
+**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.**
 
 [📖 Documentation](https://docs.voltro.dev/docs/plugins/mail) · [voltro.dev](https://voltro.dev) · [Voltro Cloud](https://voltro.cloud)
 

package/THIRD-PARTY-NOTICES.md

@@ -4348,7 +4348,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-## nodemailer@9.1.1
+## nodemailer@10.0.11
 
 License: MIT-0
 
@@ -5155,7 +5155,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## undici@8.10.0
+## undici@8.11.2
 
 License: MIT
 

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { Context } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
+import { PluginEgressDeclaration } from '@voltro/protocol';
+import { PluginHttpRouteRequest } from '@voltro/protocol';
 import { Schema } from 'effect';
 import { VoltroPlugin } from '@voltro/protocol';
 
@@ -121,6 +123,21 @@ export declare interface IdempotencyStore {
  *  exports (name + subject fn + render fn + a props schema). */
 export declare const isEmailTemplate: (v: unknown) => v is AnyEmailTemplate;
 
+export declare interface LettermintOptions {
+    /** Project API token (`lm_…`), sent as `x-lettermint-token`. */
+    readonly projectToken: string;
+    /** Default `https://api.lettermint.co/v1`. */
+    readonly baseUrl?: string;
+    /** Route slug per stream. Default: the project's default route (its
+     *  transactional one) for `transactional`, `broadcast` for `broadcast`. */
+    readonly routes?: {
+        readonly transactional?: string;
+        readonly broadcast?: string;
+    };
+}
+
+export declare const lettermintProvider: (options: LettermintOptions) => MailProvider;
+
 /** Names (+ locale variants) of every globally-registered template. */
 export declare const listGlobalTemplates: () => ReadonlyArray<{
     readonly name: string;
@@ -141,6 +158,12 @@ export declare interface MailAttachment {
     readonly contentType?: string;
 }
 
+/** What mail egress a provider choice declares. */
+export declare const mailEgressOf: (options: {
+    readonly provider?: MailProviderName | MailProvider;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}) => ReadonlyArray<PluginEgressDeclaration>;
+
 /**
  * Mail failure. `transient` drives retry — HTTP 408 / 429 / 5xx and network
  * failures are retryable; other HTTP 4xx are not. SMTP instead retries 4xx
@@ -164,10 +187,21 @@ export declare interface MailEvent {
     readonly email: string;
     readonly provider: string;
     readonly messageId?: string;
+    /** The provider's id for this event — the key to act on a redelivered
+     *  webhook only once. */
+    readonly eventId?: string;
+    /** What the message was sent with as `metadata`, returned by the provider. */
+    readonly metadata?: Readonly<Record<string, string>>;
     readonly raw: unknown;
 }
 
-export declare type MailEventType = 'delivered' | 'bounced' | 'complained' | 'opened' | 'clicked' | 'unknown';
+/** `unsubscribed`: the recipient left a broadcast through the provider's own
+ *  unsubscribe (a provider that `managesUnsubscribe`). It is NOT suppressed
+ *  app-wide — it ended one list, not the person's transactional mail.
+ *  `unsuppressed`: the provider lifted a suppression (someone removed it in
+ *  its dashboard) — lifted here too, or the app would keep dropping mail the
+ *  provider would now deliver. */
+export declare type MailEventType = 'delivered' | 'bounced' | 'complained' | 'unsubscribed' | 'unsuppressed' | 'opened' | 'clicked' | 'unknown';
 
 export declare interface MailgunOptions {
     readonly apiKey: string;
@@ -208,12 +242,30 @@ 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;
+    /** `transactional` (default) or `broadcast`. See `MailStream`. */
+    readonly stream?: MailStream;
+    /** How a recipient leaves a broadcast. See `MailUnsubscribe`. */
+    readonly unsubscribe?: MailUnsubscribe;
+    /** Key/value pairs the provider stores with the message and returns on its
+     *  delivery events (`MailEvent.metadata`) — how a bounce finds its way back
+     *  to the row that caused it. Never added to the mail itself. Lettermint and
+     *  Postmark carry it; other providers ignore it. */
+    readonly metadata?: Readonly<Record<string, string>>;
 }
 
-export declare const mailPlugin: (options?: MailPluginOptions) => VoltroPlugin;
+/**
+ * The mail plugin, with the service it built — the same one handlers yield as
+ * `MailService`. For wiring that happens in `app.config.ts`, before any
+ * handler runs: `authRoutesPlugin({ sendEmail: mailSender(mail.service) })`.
+ */
+export declare type MailPlugin = VoltroPlugin & {
+    readonly service: MailServiceShape;
+};
+
+export declare const mailPlugin: (options?: MailPluginOptions) => MailPlugin;
 
 export declare interface MailPluginOptions {
-    /** `'resend' | 'postmark' | 'sendgrid' | 'smtp' | 'console' | 'memory'`
+    /** `'lettermint' | 'resend' | 'postmark' | 'sendgrid' | 'smtp' | 'console' | 'memory'`
      *  (built from env) or a `MailProvider`. Default: `MAIL_PROVIDER` env, else
      *  `'console'`. */
     readonly provider?: MailProviderName | MailProvider;
@@ -247,7 +299,9 @@ export declare interface MailPluginOptions {
     /** How often (ms) the scheduled-send flush loop wakes to deliver due held
      *  messages. Default 1000. Ignored when the provider schedules natively. */
     readonly scheduleTickMs?: number;
-    /** Disambiguates multiple instances of this plugin in one app. */
+    /** Mount the provider's delivery-event webhook. Needs a provider with a
+     *  `webhook` verifier (Lettermint). See `MailWebhookOptions`. */
+    readonly webhook?: MailWebhookOptions;
     /**
      * Namespace for this plugin's inspect endpoints. Default `mail`.
      *
@@ -290,9 +344,24 @@ export declare interface MailProvider {
     /** One request for N personalized messages. Each keeps its own subject /
      *  body / template vars. Returns one `SendResult` per input, in order. */
     readonly sendBatch?: (messages: ReadonlyArray<ResolvedMessage>) => Effect.Effect<ReadonlyArray<SendResult>, MailError>;
+    /** True if the provider adds its own unsubscribe link and one-click headers
+     *  to broadcast mail and suppresses whoever uses them (Lettermint's
+     *  broadcast route). The service then sends no `List-Unsubscribe` of its own
+     *  — two competing unsubscribe mechanisms would each only half work. */
+    readonly managesUnsubscribe?: boolean;
+    /** Verifies and parses the provider's delivery-event webhook. Present →
+     *  `mailPlugin({ webhook })` can mount the endpoint. */
+    readonly webhook?: MailProviderWebhook;
 }
 
-export declare type MailProviderName = 'resend' | 'postmark' | 'sendgrid' | 'ses' | 'mailgun' | 'smtp' | 'console' | 'memory';
+export declare type MailProviderName = 'lettermint' | 'resend' | 'postmark' | 'sendgrid' | 'ses' | 'mailgun' | 'smtp' | 'console' | 'memory';
+
+/** A provider's delivery-event webhook: signature check, then normalisation. */
+export declare interface MailProviderWebhook {
+    /** Verify the signature over the RAW body and decode it. Fails with
+     *  `MailWebhookError` for a missing, stale or forged signature. */
+    readonly verify: (headers: Readonly<Record<string, string | undefined>>, rawBody: string, secret: string, nowSeconds?: number) => Effect.Effect<unknown, MailWebhookError>;
+}
 
 export declare interface MailSendRecord {
     readonly id: string;
@@ -356,6 +425,69 @@ export declare interface MailServiceShape {
     readonly unsuppress: (tenantId: string | null, email: string) => Effect.Effect<void>;
     /** Is this address currently suppressed for the tenant? */
     readonly isSuppressed: (tenantId: string | null, email: string) => Effect.Effect<boolean>;
+    /** The provider behind the service. `managesUnsubscribe` tells a broadcast
+     *  sender whether the provider already puts an unsubscribe link in the mail
+     *  (then the body needs none of its own). Absent on a hand-built service. */
+    readonly provider?: {
+        readonly name: string;
+        readonly managesUnsubscribe: boolean;
+    };
+}
+
+/**
+ * Which kind of mail this is. `transactional` (the default) is one-to-one mail
+ * a person's own action triggered — an invitation, a receipt, a password
+ * reset. `broadcast` is one-to-many mail — a newsletter, a campaign. Providers
+ * that separate the two (Lettermint routes, Postmark message streams) send
+ * them from different infrastructure, so a newsletter's complaints never cost
+ * a password reset its inbox placement.
+ */
+export declare type MailStream = 'transactional' | 'broadcast';
+
+/**
+ * How a recipient leaves a broadcast. `oneClickUrl` is the HTTPS endpoint a
+ * mail client POSTs `List-Unsubscribe=One-Click` to (RFC 8058); the service
+ * turns it into the `List-Unsubscribe` + `List-Unsubscribe-Post` headers.
+ * Required on a broadcast unless the provider unsubscribes recipients itself
+ * (`MailProvider.managesUnsubscribe`).
+ */
+export declare interface MailUnsubscribe {
+    readonly oneClickUrl: string;
+    /** Optional `mailto:` alternative listed beside the URL. */
+    readonly mailto?: string;
+}
+
+/** A webhook that failed verification — answer 401, never process it. */
+export declare class MailWebhookError extends MailWebhookError_base {
+}
+
+declare const MailWebhookError_base: Schema.TaggedErrorClass<MailWebhookError, "MailWebhookError", {
+    readonly _tag: Schema.tag<"MailWebhookError">;
+} & {
+    provider: typeof Schema.String;
+    message: typeof Schema.String;
+}>;
+
+/**
+ * The provider's delivery-event webhook, mounted by the plugin. Bounces and
+ * spam complaints suppress the address in the plugin's OWN suppression store
+ * — the one every send checks — then `onEvent` sees every event.
+ */
+export declare interface MailWebhookOptions {
+    /** Signing secret. Default: `MAIL_WEBHOOK_SECRET`. Without one the endpoint
+     *  answers 503, and a production boot refuses. */
+    readonly secret?: string;
+    /** Default `/webhooks/mail`. */
+    readonly path?: string;
+    /**
+     * Every verified event, after suppression — an unsubscribe to record, a
+     * bounce to mark on the row the message's `metadata` names. A failure
+     * answers 500 and the provider redelivers, so act idempotently
+     * (`event.eventId`). `store` is the app's boot store, as on any plugin route.
+     */
+    readonly onEvent?: (event: MailEvent, ctx: {
+        readonly store: PluginHttpRouteRequest['store'];
+    }) => Effect.Effect<void, unknown> | Promise<void> | void;
 }
 
 export declare const makeScheduler: (options: SchedulerOptions) => Scheduler;
@@ -402,6 +534,10 @@ export declare const postgresSuppressionStore: (options?: PostgresSuppressionOpt
 
 export declare const postmarkProvider: (options: {
     readonly serverToken: string;
+    readonly streams?: {
+        readonly transactional?: string;
+        readonly broadcast?: string;
+    };
 }) => MailProvider;
 
 /** Stable snapshot of everything the memory provider has "sent". */
@@ -558,8 +694,19 @@ export declare interface TemplateMessage {
     readonly scheduledAt?: Date;
     /** See `MailMessage.idempotencyKey`. */
     readonly idempotencyKey?: string;
+    /** See `MailMessage.stream`. */
+    readonly stream?: MailStream;
+    /** See `MailMessage.unsubscribe`. */
+    readonly unsubscribe?: MailUnsubscribe;
+    /** See `MailMessage.metadata`. */
+    readonly metadata?: Readonly<Record<string, string>>;
 }
 
+/** Lettermint signs `${t}.${rawBody}` with HMAC-SHA256 under the webhook
+ *  secret: `x-lettermint-signature: t=<unix>,v1=<hex>` (several `v1` during a
+ *  secret rotation), `x-lettermint-delivery: <unix>` must equal `t`. */
+export declare const verifyLettermintSignature: (headers: Readonly<Record<string, string | undefined>>, rawBody: string, secret: string, nowSeconds?: number, toleranceSeconds?: number) => Effect.Effect<unknown, MailWebhookError>;
+
 export { VoltroPlugin }
 
 export { }