@softure-ai/mailing 0.1.11 → 0.1.12

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 } };
 }