@voltro/plugin-mail 0.81.0 → 0.83.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
 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';
 
@@ -115,12 +118,30 @@ export declare interface IdempotencyStore {
     readonly record: (tenantId: string | null, key: string, result: SendResult) => Effect.Effect<void>;
     readonly activate?: (env: NodeJS.ProcessEnv) => Promise<void>;
     readonly deactivate?: () => Promise<void>;
+    /** Receives the app's `DataStore` at `bindDataStore`, for a store kept in the
+     *  app's own database. */
+    readonly bind?: (store: DataStore) => Promise<void>;
 }
 
 /** Structural guard: recognise a `defineEmail(...)` result among a module's
  *  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 +162,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 +191,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 +246,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;
@@ -232,12 +288,12 @@ export declare interface MailPluginOptions {
      *  `mail.send({ template, props })`. */
     readonly templates?: ReadonlyArray<AnyEmailTemplate>;
     /** Suppression backend for bounced/complained addresses: `'memory'`
-     *  (default, single-node), `'postgres'` (own pool from `DB_*`/`PG_*` env),
+     *  (default, single-node), `'postgres'` (the app's own postgres connection),
      *  or a custom `SuppressionStore`. */
     readonly suppression?: 'memory' | 'postgres' | SuppressionStore;
     /** Per-send idempotency backend (webhook-retry double-send guard):
-     *  `'memory'` (default, single-node), `'postgres'` (own pool from
-     *  `DB_*`/`PG_*` env), or a custom `IdempotencyStore`. Engaged only for a
+     *  `'memory'` (default, single-node), `'postgres'` (the app's own
+     *  postgres connection), or a custom `IdempotencyStore`. Engaged only for a
      *  send carrying `idempotencyKey`. */
     readonly idempotency?: 'memory' | 'postgres' | IdempotencyStore;
     /** Backing store for HELD scheduled messages (providers without native
@@ -247,7 +303,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 +348,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 +429,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;
@@ -378,30 +514,33 @@ export declare interface Outbox {
 /** Normalise a provider webhook payload to MailEvents. Unknown shapes → []. */
 export declare const parseMailEvent: (provider: string, payload: unknown) => ReadonlyArray<MailEvent>;
 
-export declare interface PostgresIdempotencyOptions {
-    readonly table?: string;
-    readonly maxConnections?: number;
-}
-
 /**
- * Postgres dedup store. `reserve` is an atomic
- * `INSERT … ON CONFLICT (tenant, key) DO NOTHING RETURNING` — exactly one
- * replica sees the insert, so exactly one send fires fleet-wide. Unlike the
- * suppression store this does NOT fail open: if the dedup DB is unreachable a
- * reserve reports `won: false` (skip) so a blip can never turn into a
- * double-send — the safer failure for an at-least-once webhook.
+ * Dedup in the app's own database: `_voltro_mail_idempotency`, declared through
+ * the plugin's `extendSchema` (`storeTables.ts`) and written through the app's
+ * `DataStore`, bound at `bindDataStore`. `reserve` is an `insertIgnore` on the
+ * (tenant, key) primary key, and its outcome comes from the store's own insert
+ * decision — exactly one replica sees `inserted`, so exactly one send fires
+ * fleet-wide. Unlike the suppression store this does NOT fail open: if the
+ * database is unreachable a reserve reports `won: false` (skip) so a blip can
+ * never turn into a double-send — the safer failure for an at-least-once
+ * webhook.
  */
-export declare const postgresIdempotencyStore: (options?: PostgresIdempotencyOptions) => IdempotencyStore;
-
-export declare interface PostgresSuppressionOptions {
-    readonly table?: string;
-    readonly maxConnections?: number;
-}
+export declare const postgresIdempotencyStore: () => IdempotencyStore;
 
-export declare const postgresSuppressionStore: (options?: PostgresSuppressionOptions) => SuppressionStore;
+/**
+ * The suppression list in the app's own database: `_voltro_mail_suppression`,
+ * declared through the plugin's `extendSchema` (`storeTables.ts`) and written
+ * through the app's `DataStore`, bound at `bindDataStore`. Multi-node correct on
+ * every dialect the app runs on; nothing opens a connection of its own.
+ */
+export declare const postgresSuppressionStore: () => SuppressionStore;
 
 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". */
@@ -537,6 +676,9 @@ export declare interface SuppressionStore {
     readonly unsuppress: (tenantId: string | null, email: string) => Effect.Effect<void>;
     readonly activate?: (env: NodeJS.ProcessEnv) => Promise<void>;
     readonly deactivate?: () => Promise<void>;
+    /** Receives the app's `DataStore` at `bindDataStore`, for a store kept in the
+     *  app's own database. */
+    readonly bind?: (store: DataStore) => Promise<void>;
 }
 
 /** Send a registered template instead of raw html/text. */
@@ -558,8 +700,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 { }