@softure-ai/mailing 0.1.6 → 0.1.7

package/src/server/send-mail.ts

@@ -5,7 +5,17 @@
 // 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 type { Queryable } from "@softure-ai/db";
-import { TRANSACTIONAL_KIND, type MailingErrorCode, type MailProvider, type OutgoingMail, type ProviderMessage, type ProviderOutcome, type SendMailOptions, type SendMailResult } from "../contract.js";
+import {
+  TRANSACTIONAL_KIND,
+  type MailingErrorCode,
+  type MailProvider,
+  type OutgoingMail,
+  type ProviderFailureStatus,
+  type ProviderMessage,
+  type ProviderOutcome,
+  type SendMailOptions,
+  type SendMailResult,
+} from "../contract.js";
 import type { MailingMessages } from "../messages/index.js";
 import { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders } from "./list-mail.js";
 import { getMailingModule, getMailingOptions } from "./options.js";
@@ -27,7 +37,9 @@ 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
- * same `idempotencyKey`), `suppressed` (a list mail to someone who unsubscribed; do not retry).
+ * same `idempotencyKey`), `suppressed` (a list mail to someone who unsubscribed; do not retry),
+ * `provider_refused` / `quota_exceeded` (the account cannot send: stop, fix or wait, then retry). A
+ * failure the provider answered with an HTTP status carries it as `httpStatus`.
  * 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> {
@@ -54,11 +66,18 @@ export async function sendMail(context: MailContext, mail: OutgoingMail, options
   if (outcome.status === "sent") {
     return ok({ id: outcome.id, provider: provider.name });
   }
-  const code: MailingErrorCode = `mailing.${outcome.status}`;
+  const code = FAILURE_CODES[outcome.status];
   logFailure(provider, code, { status: outcome.httpStatus });
-  return err(code);
+  return outcome.httpStatus === undefined ? err(code) : { ...err(code), httpStatus: outcome.httpStatus };
 }
 
+const FAILURE_CODES: Readonly<Record<ProviderFailureStatus, MailingErrorCode>> = {
+  rejected: "mailing.rejected",
+  unavailable: "mailing.unavailable",
+  refused: "mailing.provider_refused",
+  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 };
@@ -130,12 +149,17 @@ function readOutcome(outcome: unknown): ProviderOutcome {
   if (status === "sent") {
     return typeof id === "string" && id !== "" ? { status, id } : { status: "unavailable" };
   }
-  if (status === "rejected" || status === "unavailable") {
-    return typeof httpStatus === "number" ? { status, httpStatus } : { status };
+  if (typeof status === "string" && Object.hasOwn(FAILURE_CODES, status)) {
+    const failure = status as ProviderFailureStatus;
+    return isHttpStatus(httpStatus) ? { status: failure, httpStatus } : { status: failure };
   }
   return { status: "unavailable" };
 }
 
+function isHttpStatus(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+}
+
 /**
  * The module's only log line. Deliberately takes nothing but the provider, the code, a status,
  * field names and a fixed cause: anything added "for diagnosis" is where an address leaks first.

package/src/server/suppressions.ts

@@ -9,7 +9,7 @@ import { and, eq, inArray } from "drizzle-orm";
 import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
 import { suppressions } from "../schema.js";
 import { getMailingOptions } from "./options.js";
-import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeToken } from "./unsubscribe-link.js";
+import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubscribe-link.js";
 
 export type SuppressionContext = ModuleContext<Queryable>;
 
@@ -54,20 +54,22 @@ export async function liftSuppression(ctx: Pick<SuppressionContext, "db">, addre
 }
 
 /**
- * Unsubscribes the recipient of a signed link and runs `onUnsubscribed` in the same transaction,
- * also when the recipient had already unsubscribed (a retried one-click heals a missed hook). The
- * signature is checked before the database is touched; a link that does not verify is
- * `mailing.invalid_link`. Throws on a database failure or when the hook throws (nothing is stored).
+ * Unsubscribes the recipient of a link and runs `onUnsubscribed` in the same transaction, also when
+ * the recipient had already unsubscribed (a retried one-click heals a missed hook). A signed link
+ * (or a bare token) is checked against the secrets before the database is touched; a legacy link
+ * goes to the app's `legacyUnsubscribe.verify`, which names the address. A link that does not
+ * verify is `mailing.invalid_link`. Throws on a database failure, or when `verify` or the hook
+ * throws (nothing is stored).
  */
 export async function unsubscribe(
   ctx: SuppressionContext,
-  token: UnsubscribeToken | null,
+  link: UnsubscribeLink | UnsubscribeToken | null,
   source: Exclude<SuppressionSource, "operator">,
   env: Env = process.env,
 ): Promise<Result<undefined, UnsubscribeErrorCode>> {
-  if (token === null || !verifyUnsubscribeToken(token, readUnsubscribeSecrets(env))) return err("mailing.invalid_link");
+  const recipientKey = await verifyLink(ctx, link, env);
+  if (recipientKey === null) return err("mailing.invalid_link");
   const { onUnsubscribed } = getMailingOptions(ctx.config);
-  const { recipientKey } = token;
   await ctx.db.transaction(async (tx) => {
     const txCtx: SuppressionContext = { ...ctx, db: tx };
     await recordSuppression(txCtx, recipientKey, source);
@@ -75,3 +77,16 @@ export async function unsubscribe(
   });
   return ok();
 }
+
+/** The recipient key a link proves, or `null` when it proves none. */
+async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, env: Env): Promise<string | null> {
+  if (link === null) return null;
+  if (!("scheme" in link) || link.scheme === "signed") {
+    const token = "scheme" in link ? link.token : link;
+    return verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)) ? token.recipientKey : null;
+  }
+  const legacy = getMailingOptions(ctx.config).legacyUnsubscribe;
+  if (legacy === undefined) return null;
+  const address: unknown = await legacy.verify(link.values, ctx);
+  return typeof address === "string" && address.trim() !== "" ? getRecipientKey(address) : null;
+}

package/src/server/unsubscribe-link.ts

@@ -5,7 +5,7 @@
 // so it never reaches a log, an error or a result.
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 import type { SoftureConfig } from "@softure-ai/core";
-import { getMailingRoutes } from "./options.js";
+import { getMailingOptions, getMailingRoutes } from "./options.js";
 
 /** Signs every new link and verifies. */
 export const UNSUBSCRIBE_SECRET_ENV = "MAILING_UNSUBSCRIBE_SECRET";
@@ -101,6 +101,46 @@ export function buildUnsubscribeLinks(config: SoftureConfig, address: string, se
   };
 }
 
+/** A legacy link's value longer than this makes the link invalid before the app's `verify` sees it. */
+export const MAX_LEGACY_VALUE_LENGTH = 512;
+
+/** The link a person followed: the module's signed one, or one the app sent before it adopted the module. */
+export type UnsubscribeLink =
+  | { readonly scheme: "signed"; readonly token: UnsubscribeToken }
+  | { readonly scheme: "legacy"; readonly values: Readonly<Record<string, string>> };
+
+/** Reads one query or form value; `URLSearchParams` and `FormData` both fit. */
+export interface LinkParams {
+  get(name: string): unknown;
+}
+
+/**
+ * The link in a query or a form. A link with the recipient parameter (`r`) is a signed link, whatever else it
+ * carries, so a crafted URL cannot route a signed link to the app's legacy check. Without it, and with
+ * `mailing({ legacyUnsubscribe })`, a link that has every legacy parameter (non-empty, at most 512 characters) is
+ * a legacy link. Anything else is `null`. Checks no signature: `unsubscribe` does.
+ */
+export function readUnsubscribeLink(params: LinkParams, config: SoftureConfig): UnsubscribeLink | null {
+  if (params.get(RECIPIENT_PARAM) !== null && params.get(RECIPIENT_PARAM) !== undefined) {
+    const token = readUnsubscribeToken(params);
+    return token === null ? null : { scheme: "signed", token };
+  }
+  const legacy = getMailingOptions(config).legacyUnsubscribe;
+  if (legacy === undefined) return null;
+  const values: Record<string, string> = {};
+  for (const name of legacy.params) {
+    const value = params.get(name);
+    if (typeof value !== "string" || value === "" || value.length > MAX_LEGACY_VALUE_LENGTH) return null;
+    values[name] = value;
+  }
+  return { scheme: "legacy", values };
+}
+
+/** The query (or form) parameters that carry `link`, to send it back to the page. */
+export function getUnsubscribeLinkParams(link: UnsubscribeLink): Record<string, string> {
+  return link.scheme === "signed" ? { [RECIPIENT_PARAM]: link.token.recipientKey, [SIGNATURE_PARAM]: link.token.signature } : { ...link.values };
+}
+
 /** The token in a link's query (or a form), when both parameters are present once. */
 export function readUnsubscribeToken(params: { get(name: string): unknown }): UnsubscribeToken | null {
   const recipientKey = params.get(RECIPIENT_PARAM);