@softure-ai/mailing 0.1.11 → 0.1.13

package/dist/server/run-deliveries.d.ts

@@ -0,0 +1,62 @@
+import { type MailingErrorCode } from "../contract.js";
+import { type DeliverOptions, type Delivery, type DeliveryContext, type DeliveryOutcome, type RunHalt } from "./deliveries.js";
+export interface DeliveryRunInput<Recipient> {
+    readonly recipients: Iterable<Recipient> | AsyncIterable<Recipient>;
+    /** The delivery for one recipient (its scope and mail), or `null` to skip them. A throw stops the run. */
+    readonly build: (recipient: Recipient) => Delivery | null | Promise<Delivery | null>;
+}
+export interface RunDeliveriesOptions extends DeliverOptions {
+    /** Pause after every mail that reached the provider, for its rate limit. Default 0. */
+    readonly pauseMs?: number;
+    /**
+     * Most mails this run hands to the provider (sent, rejected by it, or not taken now). Once reached, the run reads
+     * the rest only to count `remaining`. A whole number of at least 1. Default: no limit.
+     */
+    readonly limit?: number;
+    /** Reads the ledger and the suppression list and sends and writes nothing; `sent` then counts what would go out. */
+    readonly dryRun?: boolean;
+    /** Called after every delivery of a real run, e.g. for progress output. Never receives the address. */
+    readonly onDelivery?: (outcome: DeliveryOutcome) => void;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /**
+     * End the run at the first `retry-later` (the provider is down, timed out or rate limited), reported in `halted` as
+     * `mailing.unavailable`. Going on would spend an attempt of every following recipient on the same answer. Default
+     * `true`.
+     */
+    readonly stopOnRetryLater?: boolean;
+}
+export interface DeliveryRunSummary {
+    readonly dryRun: boolean;
+    /** Recipients read (past the limit too, but not past a halt). */
+    readonly recipients: number;
+    /** `build` returned `null`; nothing stored. */
+    readonly skipped: number;
+    /** Sent in this run; in a dry run, the mails that would reach the provider. */
+    readonly sent: number;
+    /** Rejected in this run, by reason; suppressed list mail is under `mailing.suppressed`. */
+    readonly rejected: Readonly<Record<MailingErrorCode, number>>;
+    /** Closed by an earlier run (or, in a dry run, by a delivery earlier in this one); nothing sent. */
+    readonly done: number;
+    /** Claimed by another run that is still sending. */
+    readonly inFlight: number;
+    /** The provider was unavailable, or the run halted on it; the next run tries again. */
+    readonly retryLater: number;
+    /** Claimed more than `uncertainClaimMs` ago and never closed: their mail may have gone out. */
+    readonly uncertain: number;
+    /**
+     * Set when the run stopped early: at a failure about the sending account (run again once the account can send) or,
+     * with `stopOnRetryLater`, at the first mail the provider could not take now (`mailing.unavailable`; run again later).
+     */
+    readonly halted: RunHalt | null;
+    /** Deliveries past the `limit` cut that the next run would send; 0 without a cut, `null` after a halt. */
+    readonly remaining: number | null;
+}
+/**
+ * Builds and delivers one mail per recipient, in order, each at most once per scope and recipient. Stops at the first
+ * `halted` delivery and, unless `stopOnRetryLater` is `false`, at the first `retry-later`. Throws on a
+ * database failure, when `build` throws, like `deliverOnce` for a malformed delivery, at the first list mail when
+ * `MAILING_UNSUBSCRIBE_SECRET` is not set (each send would fail and use up an attempt), and (a `RangeError`) for a
+ * `limit` that is not a whole number of at least 1.
+ */
+export declare function runDeliveries<Recipient>(ctx: DeliveryContext, input: DeliveryRunInput<Recipient>, options?: RunDeliveriesOptions): Promise<DeliveryRunSummary>;
+//# sourceMappingURL=run-deliveries.d.ts.map

package/dist/server/run-deliveries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-deliveries.d.ts","sourceRoot":"","sources":["../../src/server/run-deliveries.ts"],"names":[],"mappings":"AAKA,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAA6C,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,eAAe,EAAyB,KAAK,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAMjM,MAAM,WAAW,gBAAgB,CAAC,SAAS;IACzC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;IACpE,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,KAAK,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,uFAAuF;IACvF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oHAAoH;IACpH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;IAC9D,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,0GAA0G;IAC1G,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAID;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,gBAAgB,CAAC,SAAS,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAyCxK"}

package/dist/server/run-deliveries.js

@@ -0,0 +1,133 @@
+// A run of lifecycle mail: one delivery per recipient through the ledger (`deliverOnce`), e.g. every subscription
+// whose trial ends this week. The app lists the recipients and builds each mail; the run keeps the ledger's
+// at-most-once rule, stops at the first failure about the sending account (refused key, spent quota), at the first
+// mail the provider could not take now (unless told otherwise), and after `limit` mails reached the provider, and
+// counts what it did. A dry run reads the same state and writes nothing.
+import { TRANSACTIONAL_KIND } from "../contract.js";
+import { deliverOnce, forecastDelivery, getRunHalt } from "./deliveries.js";
+import { getRecipientKey, MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "./unsubscribe-link.js";
+/** Rejections the provider answered (the others never left the process). */
+const PROVIDER_REASONS = new Set(["mailing.rejected", "mailing.unavailable"]);
+/**
+ * Builds and delivers one mail per recipient, in order, each at most once per scope and recipient. Stops at the first
+ * `halted` delivery and, unless `stopOnRetryLater` is `false`, at the first `retry-later`. Throws on a
+ * database failure, when `build` throws, like `deliverOnce` for a malformed delivery, at the first list mail when
+ * `MAILING_UNSUBSCRIBE_SECRET` is not set (each send would fail and use up an attempt), and (a `RangeError`) for a
+ * `limit` that is not a whole number of at least 1.
+ */
+export async function runDeliveries(ctx, input, options = {}) {
+    const { pauseMs = 0, limit, dryRun = false, onDelivery, sleep = wait, stopOnRetryLater = true, ...deliverOptions } = options;
+    if (limit !== undefined && !(Number.isInteger(limit) && limit >= 1)) {
+        throw new RangeError(`@softure-ai/mailing: runDeliveries limit must be a whole number of at least 1, got ${String(limit)}`);
+    }
+    const counts = { recipients: 0, skipped: 0, sent: 0, done: 0, inFlight: 0, retryLater: 0, uncertain: 0, rejected: emptyRejections() };
+    // Deliveries this run already sent or would send, so a dry run (and the count past the limit) sees its own effect.
+    const reached = new Set();
+    let handedToProvider = 0;
+    let remaining = 0;
+    for await (const recipient of input.recipients) {
+        counts.recipients += 1;
+        const delivery = await input.build(recipient);
+        if (delivery === null) {
+            counts.skipped += 1;
+            continue;
+        }
+        assertListMailCanBeSigned(delivery);
+        const isPastLimit = limit !== undefined && handedToProvider >= limit;
+        if (dryRun || isPastLimit) {
+            const forecast = await forecastOnce(ctx, delivery, { options: deliverOptions, reached });
+            if (isPastLimit) {
+                if (forecast.status === "send")
+                    remaining += 1;
+                continue;
+            }
+            countForecast(counts, forecast);
+            if (forecast.status === "send")
+                handedToProvider += 1;
+            continue;
+        }
+        const outcome = await deliverOnce(ctx, delivery, deliverOptions);
+        countOutcome(counts, outcome);
+        onDelivery?.(outcome);
+        const halt = getRunHalt(outcome, stopOnRetryLater);
+        if (halt !== null)
+            return { dryRun, ...counts, halted: halt, remaining: null };
+        const reachedProvider = outcome.status === "sent" || outcome.status === "retry-later" || (outcome.status === "rejected" && PROVIDER_REASONS.has(outcome.reason));
+        if (outcome.status === "sent")
+            reached.add(getDeliveryKey(delivery));
+        if (reachedProvider)
+            handedToProvider += 1;
+        if (reachedProvider && pauseMs > 0)
+            await sleep(pauseMs);
+    }
+    return { dryRun, ...counts, halted: null, remaining };
+}
+function getDeliveryKey(delivery) {
+    return `${delivery.scope}\n${getRecipientKey(delivery.mail.to)}`;
+}
+/** List mail without the signing secret is a configuration bug: stop before any claim is taken. */
+function assertListMailCanBeSigned(delivery) {
+    if ((delivery.mail.kind ?? TRANSACTIONAL_KIND) === TRANSACTIONAL_KIND || readUnsubscribeSecrets().current !== null)
+        return;
+    throw new Error(`@softure-ai/mailing: runDeliveries sends list mail, which needs ${UNSUBSCRIBE_SECRET_ENV} (at least ${String(MIN_UNSUBSCRIBE_SECRET_LENGTH)} characters)`);
+}
+/** The forecast, with a delivery this run already sent (or would send) counted as done. */
+async function forecastOnce(ctx, delivery, { options, reached }) {
+    const key = getDeliveryKey(delivery);
+    const forecast = await forecastDelivery(ctx, delivery, options);
+    if (forecast.status !== "send")
+        return forecast;
+    if (reached.has(key))
+        return { status: "done" };
+    reached.add(key);
+    return forecast;
+}
+function countForecast(counts, forecast) {
+    switch (forecast.status) {
+        case "send":
+            counts.sent += 1;
+            return;
+        case "rejected":
+            counts.rejected[forecast.reason] += 1;
+            return;
+        case "done":
+            counts.done += 1;
+            return;
+        case "in-flight":
+            counts.inFlight += 1;
+            return;
+        case "uncertain":
+            counts.uncertain += 1;
+            return;
+    }
+}
+function countOutcome(counts, outcome) {
+    switch (outcome.status) {
+        case "sent":
+            counts.sent += 1;
+            return;
+        case "rejected":
+            counts.rejected[outcome.reason] += 1;
+            return;
+        case "done":
+            counts.done += 1;
+            return;
+        case "in-flight":
+            counts.inFlight += 1;
+            return;
+        case "retry-later":
+        case "halted":
+            counts.retryLater += 1;
+            return;
+        case "uncertain":
+            counts.uncertain += 1;
+            return;
+    }
+}
+function emptyRejections() {
+    return { "mailing.invalid_input": 0, "mailing.rejected": 0, "mailing.unavailable": 0, "mailing.suppressed": 0, "mailing.provider_refused": 0, "mailing.quota_exceeded": 0 };
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=run-deliveries.js.map

package/dist/server/run-deliveries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-deliveries.js","sourceRoot":"","sources":["../../src/server/run-deliveries.ts"],"names":[],"mappings":"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"}

package/dist/server/send-mail.d.ts

@@ -1,6 +1,7 @@
-import { type SoftureConfig } from "@softure-ai/core";
+import { type Err, type Ok, type SoftureConfig } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { type OutgoingMail, type SendMailOptions, type SendMailResult } from "../contract.js";
+import { type OutgoingMail, type ProviderMessage, type SendMailOptions, type SendMailResult } from "../contract.js";
+import { type Env } from "./unsubscribe-link.js";
 /**
  * What `sendMail` needs: the app's configuration and, for list mail, the database handle (the
  * suppression check reads it). Transactional mail needs no `db`.
@@ -18,4 +19,22 @@ export interface MailContext {
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export declare function sendMail(context: MailContext, mail: OutgoingMail, options?: SendMailOptions): Promise<SendMailResult>;
+/** Why `previewMail` cannot render a mail: invalid input (with the fields), or list mail without the secret. */
+export type MailPreviewFailure = (Err<"mailing.invalid_input"> & {
+    readonly fields: readonly string[];
+}) | (Err<"mailing.unavailable"> & {
+    readonly cause: "no_unsubscribe_secret";
+});
+export type MailPreviewResult = Ok<ProviderMessage> | MailPreviewFailure;
+export interface PreviewMailOptions extends SendMailOptions {
+    /** Where the unsubscribe secret is read. Default: `process.env`. */
+    readonly env?: Env;
+}
+/**
+ * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, and for list mail the
+ * footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
+ * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed.
+ * The links in it are credentials for `mail.to`. Throws only when the module is not enabled.
+ */
+export declare function previewMail(config: SoftureConfig, mail: OutgoingMail, options?: PreviewMailOptions): MailPreviewResult;
 //# sourceMappingURL=send-mail.d.ts.map

package/dist/server/send-mail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-mail.d.ts","sourceRoot":"","sources":["../../src/server/send-mail.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAIL,KAAK,YAAY,EAIjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAQxB;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;CACzB;AAID;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA2B/H"}
+{"version":3,"file":"send-mail.d.ts","sourceRoot":"","sources":["../../src/server/send-mail.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAIL,KAAK,YAAY,EAEjB,KAAK,eAAe,EAEpB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAKxB,OAAO,EAAwG,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAC;AAGvJ;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAyB/H;AAED,gHAAgH;AAChH,MAAM,MAAM,kBAAkB,GAC1B,CAAC,GAAG,CAAC,uBAAuB,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC,GACvE,CAAC,GAAG,CAAC,qBAAqB,CAAC,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,uBAAuB,CAAA;CAAE,CAAC,CAAC;AAE/E,MAAM,MAAM,iBAAiB,GAAG,EAAE,CAAC,eAAe,CAAC,GAAG,kBAAkB,CAAC;AAEzE,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,oEAAoE;IACpE,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,iBAAiB,CAO1H"}

package/dist/server/send-mail.js

@@ -19,23 +19,22 @@ import { validateMail } from "./validate-mail.js";
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export async function sendMail(context, mail, options = {}) {
-    const { from, replyTo, provider, timeoutMs } = getMailingOptions(context.config);
+    const { provider, timeoutMs } = getMailingOptions(context.config);
     const validation = validateMail(mail, options);
     if (!validation.ok) {
         logFailure(provider, "mailing.invalid_input", { fields: validation.fields });
         return err("mailing.invalid_input");
     }
-    const { idempotencyKey, kind, replyTo: mailReplyTo, ...content } = validation.value;
-    let message = content;
-    if (kind !== TRANSACTIONAL_KIND) {
-        const listMail = await prepareListMail(context, validation.value);
-        if (!listMail.ok) {
-            logFailure(provider, listMail.error, { cause: listMail.cause });
-            return err(listMail.error);
+    const valid = validation.value;
+    const secret = readUnsubscribeSecrets().current;
+    if (valid.kind !== TRANSACTIONAL_KIND) {
+        const refusal = await checkListMail(context, valid, secret);
+        if (refusal !== null) {
+            logFailure(provider, refusal.error, { cause: refusal.cause });
+            return err(refusal.error);
         }
-        message = listMail.value;
     }
-    const outcome = await callProvider(provider, { ...message, from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey }, timeoutMs);
+    const outcome = await callProvider(provider, composeMessage(context.config, valid, secret), timeoutMs);
     if (outcome.status === "sent") {
         return ok({ id: outcome.id, provider: provider.name });
     }
@@ -43,6 +42,22 @@ export async function sendMail(context, mail, options = {}) {
     logFailure(provider, code, { status: outcome.httpStatus });
     return outcome.httpStatus === undefined ? err(code) : { ...err(code), httpStatus: outcome.httpStatus };
 }
+/**
+ * Exactly what `sendMail` would hand the provider for `mail`: the sender, the reply-to, and for list mail the
+ * footer with a link signed for `mail.to` and the RFC 8058 headers. Sends nothing, logs nothing and needs no
+ * database: it does not check the suppression list, so it renders a mail `sendMail` would refuse as suppressed.
+ * The links in it are credentials for `mail.to`. Throws only when the module is not enabled.
+ */
+export function previewMail(config, mail, options = {}) {
+    const { env, ...sendOptions } = options;
+    const validation = validateMail(mail, sendOptions);
+    if (!validation.ok)
+        return { ...err("mailing.invalid_input"), fields: validation.fields };
+    const secret = readUnsubscribeSecrets(env).current;
+    if (validation.value.kind !== TRANSACTIONAL_KIND && secret === null)
+        return { ...err("mailing.unavailable"), cause: "no_unsubscribe_secret" };
+    return ok(composeMessage(config, validation.value, secret));
+}
 const FAILURE_CODES = {
     rejected: "mailing.rejected",
     unavailable: "mailing.unavailable",
@@ -50,40 +65,45 @@ const FAILURE_CODES = {
     quota_exceeded: "mailing.quota_exceeded",
 };
 /**
- * A list mail with its footer and headers, or why it must not go out. Fails closed: without the
- * secret, or when the suppression list cannot be read, nothing is sent.
+ * Why a list mail must not go out, or `null` when it may. Fails closed: without the secret, or when the suppression
+ * list cannot be read, nothing is sent.
  */
-async function prepareListMail(context, mail) {
+async function checkListMail(context, mail, secret) {
     if (context.db === undefined) {
         throw new Error("@softure-ai/mailing: list mail needs the database handle; call sendMail({ config, db }, ...)");
     }
-    const secret = readUnsubscribeSecrets().current;
     if (secret === null) {
         console.error(`mailing: list mail needs ${UNSUBSCRIBE_SECRET_ENV} (at least ${String(MIN_UNSUBSCRIBE_SECRET_LENGTH)} characters) to sign unsubscribe links`);
-        return { ok: false, error: "mailing.unavailable", cause: "no_unsubscribe_secret" };
+        return { error: "mailing.unavailable", cause: "no_unsubscribe_secret" };
     }
-    let suppressed;
     try {
-        suppressed = await isSuppressed({ db: context.db }, mail.to);
+        return (await isSuppressed({ db: context.db }, mail.to)) ? { error: "mailing.suppressed", cause: "unsubscribed" } : null;
     }
     catch {
         // The error text can carry the query parameters, the recipient key among them.
-        return { ok: false, error: "mailing.unavailable", cause: "suppressions_unreadable" };
+        return { error: "mailing.unavailable", cause: "suppressions_unreadable" };
     }
-    if (suppressed)
-        return { ok: false, error: "mailing.suppressed", cause: "unsubscribed" };
-    const links = buildUnsubscribeLinks(context.config, mail.to, secret);
+}
+/**
+ * The message the provider receives: the configured sender, the mail's or the configured reply-to, and for list
+ * mail the footer and headers signed with `secret` (which the caller checked is set).
+ */
+function composeMessage(config, mail, secret) {
+    const { from, replyTo } = getMailingOptions(config);
+    const { idempotencyKey, kind, replyTo: mailReplyTo, ...content } = mail;
+    const envelope = { from, replyTo: mailReplyTo ?? replyTo ?? null, idempotencyKey };
+    if (kind === TRANSACTIONAL_KIND || secret === null)
+        return { ...content, ...envelope };
+    const links = buildUnsubscribeLinks(config, mail.to, secret);
     // The module factory merged the dictionaries; their shape is the module's own.
-    const copy = getMailingModule(context.config).messages[context.config.locale].footer;
+    const copy = getMailingModule(config).messages[config.locale].footer;
     return {
-        ok: true,
-        value: {
-            to: mail.to,
-            subject: mail.subject,
-            text: addTextFooter(mail.text, links, copy),
-            html: mail.html === null ? null : addHtmlFooter(mail.html, links, copy),
-            headers: { ...mail.headers, ...getListUnsubscribeHeaders(links) },
-        },
+        ...envelope,
+        to: mail.to,
+        subject: mail.subject,
+        text: addTextFooter(mail.text, links, copy),
+        html: mail.html === null ? null : addHtmlFooter(mail.html, links, copy),
+        headers: { ...mail.headers, ...getListUnsubscribeHeaders(links) },
     };
 }
 /**

package/dist/server/send-mail.js.map

@@ -1 +1 @@
-{"version":3,"file":"send-mail.js","sourceRoot":"","sources":["../../src/server/send-mail.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"send-mail.js","sourceRoot":"","sources":["../../src/server/send-mail.ts"],"names":[],"mappings":"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"}

package/dist/server/suppressions.d.ts

@@ -5,6 +5,11 @@ import { type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubsc
 export type SuppressionContext = ModuleContext<Queryable>;
 /** Whether `address` unsubscribed. Throws on a database failure: callers decide how to fail. */
 export declare function isSuppressed(ctx: Pick<SuppressionContext, "db">, address: string): Promise<boolean>;
+/**
+ * Which of `addresses` unsubscribed, each returned as it was given; e.g. a report that splits a list into
+ * active and suppressed recipients. Throws on a database failure: callers decide how to fail.
+ */
+export declare function findSuppressedAddresses(ctx: Pick<SuppressionContext, "db">, addresses: readonly string[]): Promise<Set<string>>;
 /**
  * Unsubscribes `address` from list mail, for an operator's script or another module (a bounce or
  * complaint handler). Throws on a database failure.

package/dist/server/suppressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suppressions.d.ts","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAA2B,MAAM,gBAAgB,CAAC;AAGvG,OAAO,EAAmE,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/J,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAE1D,gGAAgG;AAChG,wBAAsB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzG;AAOD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,iBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvI;AAKD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5G;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,EAC/C,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAC9C,GAAG,GAAE,GAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAWlD"}
+{"version":3,"file":"suppressions.d.ts","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAA2B,MAAM,gBAAgB,CAAC;AAGvG,OAAO,EAAmE,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/J,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAE1D,gGAAgG;AAChG,wBAAsB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzG;AAKD;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAkBrI;AAOD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,iBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvI;AAKD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5G;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,EAC/C,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAC9C,GAAG,GAAE,GAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAWlD"}

package/dist/server/suppressions.js

@@ -17,6 +17,32 @@ export async function isSuppressed(ctx, address) {
         .limit(1);
     return rows.length > 0;
 }
+/** How many recipient keys one query asks about, so a long list never builds an oversized statement. */
+const SUPPRESSION_LOOKUP_BATCH = 500;
+/**
+ * Which of `addresses` unsubscribed, each returned as it was given; e.g. a report that splits a list into
+ * active and suppressed recipients. Throws on a database failure: callers decide how to fail.
+ */
+export async function findSuppressedAddresses(ctx, addresses) {
+    const byKey = new Map();
+    for (const address of addresses) {
+        const key = getRecipientKey(address);
+        byKey.set(key, [...(byKey.get(key) ?? []), address]);
+    }
+    const keys = [...byKey.keys()];
+    const suppressed = new Set();
+    for (let start = 0; start < keys.length; start += SUPPRESSION_LOOKUP_BATCH) {
+        const rows = await ctx.db
+            .select({ recipientKey: suppressions.recipientKey })
+            .from(suppressions)
+            .where(inArray(suppressions.recipientKey, keys.slice(start, start + SUPPRESSION_LOOKUP_BATCH)));
+        for (const row of rows) {
+            for (const address of byKey.get(row.recipientKey) ?? [])
+                suppressed.add(address);
+        }
+    }
+    return suppressed;
+}
 /** Records an opt-out by recipient key. Throws on a database failure. */
 async function recordSuppression(ctx, recipientKey, source) {
     await ctx.db.insert(suppressions).values({ recipientKey, source, createdAt: ctx.clock.now() }).onConflictDoNothing();
@@ -75,7 +101,7 @@ async function verifyLink(ctx, link, env) {
     const legacy = getMailingOptions(ctx.config).legacyUnsubscribe;
     if (legacy === undefined)
         return null;
-    const address = await legacy.verify(link.values, ctx);
+    const address = await legacy.verify(link.values, ctx, env);
     if (typeof address !== "string" || address.trim() === "")
         return null;
     return { recipientKey: getRecipientKey(address), link: { scheme: "legacy", values: link.values } };

package/dist/server/suppressions.js.map

@@ -1 +1 @@
-{"version":3,"file":"suppressions.js","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"suppressions.js","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"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"}

package/migrations/0005_add_sql_surface.sql

@@ -0,0 +1,44 @@
+-- A stable surface for an app's own SQL (reports, recipient selection), so it never re-implements the recipient key
+-- or reads the tables' internals: a change to the tables keeps these names and columns. Every name is qualified,
+-- because a function runs with its caller's search_path.
+-- Rollback: DROP VIEW mailing.suppressed_recipients; DROP VIEW mailing.delivery_outcomes;
+--   DROP FUNCTION mailing.was_delivered(text, text); DROP FUNCTION mailing.is_suppressed(text);
+--   DROP FUNCTION mailing.recipient_key(text);
+--   DELETE FROM softure.migrations WHERE module = 'mailing' AND version = 5;
+
+-- getRecipientKey in SQL: base64url SHA-256 (unpadded) of the address, lowercased and trimmed of the whitespace
+-- JavaScript's trim() removes. lower() follows the database's ctype: under the C locale only ASCII letters are
+-- lowercased, so an address with non-ASCII capitals keys differently there than in JavaScript.
+CREATE FUNCTION recipient_key(address text) RETURNS text
+  LANGUAGE sql IMMUTABLE STRICT PARALLEL SAFE AS $$
+  SELECT rtrim(translate(encode(sha256(convert_to(lower(btrim(address,
+    chr(9) || chr(10) || chr(11) || chr(12) || chr(13) || chr(32) || chr(160) || chr(5760)
+    || chr(8192) || chr(8193) || chr(8194) || chr(8195) || chr(8196) || chr(8197) || chr(8198) || chr(8199)
+    || chr(8200) || chr(8201) || chr(8202) || chr(8232) || chr(8233) || chr(8239) || chr(8287) || chr(12288)
+    || chr(65279))), 'UTF8')), 'base64'), '+/', '-_'), '=')
+$$;
+
+-- Whether the address unsubscribed from list mail.
+CREATE FUNCTION is_suppressed(address text) RETURNS boolean
+  LANGUAGE sql STABLE STRICT PARALLEL SAFE AS $$
+  SELECT EXISTS (SELECT 1 FROM mailing.suppressions WHERE recipient_key = mailing.recipient_key(address))
+$$;
+
+-- Whether a mail of this scope was sent to the address (a `sent` delivery, made by the module or imported).
+CREATE FUNCTION was_delivered(scope text, address text) RETURNS boolean
+  LANGUAGE sql STABLE STRICT PARALLEL SAFE AS $$
+  SELECT EXISTS (
+    SELECT 1 FROM mailing.deliveries d
+    WHERE d.scope = was_delivered.scope AND d.recipient_key = mailing.recipient_key(address) AND d.status = 'sent'
+  )
+$$;
+
+-- The delivery ledger as app SQL may read it. status: pending, claimed, sent or rejected.
+CREATE VIEW delivery_outcomes AS
+  SELECT scope, recipient_key, kind, campaign_id, status, attempts, claimed_at, finished_at, imported_at
+  FROM mailing.deliveries;
+
+-- The suppression list as app SQL may read it. source: one-click, page or operator.
+CREATE VIEW suppressed_recipients AS
+  SELECT recipient_key, source, created_at
+  FROM mailing.suppressions;

package/module.json

@@ -1,6 +1,6 @@
 {
   "id": "mailing",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "dependsOn": {},
   "dbSchema": "mailing",
   "tables": ["suppressions", "campaigns", "deliveries"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/mailing",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "SOFTURE AI mailing module: sendMail over a provider adapter (Resend first) with plain-text and HTML bodies, sender and reply-to from config, idempotency keys, a timeout and a typed result; signed one-click unsubscribe (RFC 8058) with a suppression list for list mail; an exactly-once delivery ledger, campaigns sent from a content file by the softure-mail command, and a sender DNS check; a fake provider for tests.",
   "license": "MIT",
   "type": "module",