@softure-ai/mailing 0.1.11 → 0.1.13

package/src/server/run-deliveries.ts

@@ -0,0 +1,193 @@
+// 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, type MailingErrorCode } from "../contract.js";
+import { deliverOnce, forecastDelivery, getRunHalt, type DeliverOptions, type Delivery, type DeliveryContext, type DeliveryForecast, type DeliveryOutcome, type RunHalt } 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: ReadonlySet<MailingErrorCode> = new Set(["mailing.rejected", "mailing.unavailable"]);
+
+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;
+}
+
+type Counts = { -readonly [Key in Exclude<keyof DeliveryRunSummary, "dryRun" | "halted" | "remaining" | "rejected">]: number } & { rejected: Record<MailingErrorCode, number> };
+
+/**
+ * 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<Recipient>(ctx: DeliveryContext, input: DeliveryRunInput<Recipient>, options: RunDeliveriesOptions = {}): Promise<DeliveryRunSummary> {
+  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: 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<string>();
+  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: Delivery): string {
+  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: Delivery): void {
+  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: DeliveryContext,
+  delivery: Delivery,
+  { options, reached }: { readonly options: DeliverOptions; readonly reached: Set<string> },
+): Promise<DeliveryForecast> {
+  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: Counts, forecast: DeliveryForecast): void {
+  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: Counts, outcome: DeliveryOutcome): void {
+  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(): Record<MailingErrorCode, number> {
+  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: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/server/send-mail.ts

@@ -3,7 +3,7 @@
 // or the result, and `headers` cannot replace the envelope or the sender (a mail's own reply-to is
 // the `replyTo` field, checked like `to`). List mail (any kind but `transactional`) also gets a signed unsubscribe
 // link in a footer and the RFC 8058 headers, and is refused for a recipient who unsubscribed.
-import { err, ok, type SoftureConfig } from "@softure-ai/core";
+import { err, ok, type Err, type Ok, type SoftureConfig } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import {
   TRANSACTIONAL_KIND,
@@ -20,7 +20,7 @@ import type { MailingMessages } from "../messages/index.js";
 import { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders } from "./list-mail.js";
 import { getMailingModule, getMailingOptions } from "./options.js";
 import { isSuppressed } from "./suppressions.js";
-import { buildUnsubscribeLinks, MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "./unsubscribe-link.js";
+import { buildUnsubscribeLinks, MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "./unsubscribe-link.js";
 import { validateMail, type ValidMail } from "./validate-mail.js";
 
 /**
@@ -32,8 +32,6 @@ export interface MailContext {
   readonly db?: Queryable;
 }
 
-type MailContent = Omit<ProviderMessage, "from" | "replyTo" | "idempotencyKey">;
-
 /**
  * Sends `mail` and resolves with the provider's message id or a `mailing.*` code:
  * `invalid_input` (fix the input), `rejected` (do not retry), `unavailable` (retry later with the
@@ -43,26 +41,24 @@ type MailContent = Omit<ProviderMessage, "from" | "replyTo" | "idempotencyKey">;
  * Throws only when the module is not enabled, or for list mail without `context.db`.
  */
 export async function sendMail(context: MailContext, mail: OutgoingMail, options: SendMailOptions = {}): Promise<SendMailResult> {
-  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: MailContent = 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 });
   }
@@ -71,6 +67,33 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
   return outcome.httpStatus === undefined ? err(code) : { ...err(code), httpStatus: outcome.httpStatus };
 }
 
+/** 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 function previewMail(config: SoftureConfig, mail: OutgoingMail, options: PreviewMailOptions = {}): MailPreviewResult {
+  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: Readonly<Record<ProviderFailureStatus, MailingErrorCode>> = {
   rejected: "mailing.rejected",
   unavailable: "mailing.unavailable",
@@ -78,44 +101,47 @@ const FAILURE_CODES: Readonly<Record<ProviderFailureStatus, MailingErrorCode>> =
   quota_exceeded: "mailing.quota_exceeded",
 };
 
-type ListMailResult =
-  | { readonly ok: true; readonly value: MailContent }
-  | { readonly ok: false; readonly error: "mailing.suppressed" | "mailing.unavailable"; readonly cause: string };
+type ListMailRefusal = { readonly error: "mailing.suppressed" | "mailing.unavailable"; readonly cause: string };
 
 /**
- * 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: MailContext, mail: ValidMail): Promise<ListMailResult> {
+async function checkListMail(context: MailContext, mail: ValidMail, secret: string | null): Promise<ListMailRefusal | null> {
   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: boolean;
   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: SoftureConfig, mail: ValidMail, secret: string | null): ProviderMessage {
+  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] as MailingMessages).footer;
+  const copy = (getMailingModule(config).messages[config.locale] as MailingMessages).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/src/server/suppressions.ts

@@ -23,6 +23,33 @@ export async function isSuppressed(ctx: Pick<SuppressionContext, "db">, address:
   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: Pick<SuppressionContext, "db">, addresses: readonly string[]): Promise<Set<string>> {
+  const byKey = new Map<string, string[]>();
+  for (const address of addresses) {
+    const key = getRecipientKey(address);
+    byKey.set(key, [...(byKey.get(key) ?? []), address]);
+  }
+  const keys = [...byKey.keys()];
+  const suppressed = new Set<string>();
+  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: SuppressionContext, recipientKey: string, source: SuppressionSource): Promise<void> {
   await ctx.db.insert(suppressions).values({ recipientKey, source, createdAt: ctx.clock.now() }).onConflictDoNothing();
@@ -93,7 +120,7 @@ async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | Unsub
   }
   const legacy = getMailingOptions(ctx.config).legacyUnsubscribe;
   if (legacy === undefined) return null;
-  const address: unknown = await legacy.verify(link.values, ctx);
+  const address: unknown = 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 } };
 }