@softure-ai/mailing 0.1.5 → 0.1.7

package/src/server/deliveries.ts

@@ -1,20 +1,24 @@
 // The delivery ledger (mailing.deliveries): a mail goes out at most once per scope and recipient.
 // The sender claims the row in one conditional upsert before it calls the provider, then closes it
 // with one outcome. A claim left behind by a crash is taken over once it is stale, and the mail is
-// sent again with the same idempotency key, so the provider folds it into the first send.
+// sent again with the same idempotency key, so the provider folds it into the first send. A claim
+// older than the provider keeps that key is "uncertain": it is taken over only when the operator
+// says so. A failure about the sending account (refused key, spent quota) closes nothing: the
+// claim goes back, attempt included, so fixing the account and re-running loses no recipient.
 import { type ModuleContext } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
-import { and, eq, lt, or, sql } from "drizzle-orm";
+import { and, eq, gte, lt, or, sql, type SQL } from "drizzle-orm";
 import { isMailKind } from "../address.js";
-import { TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
+import { HALTING_ERROR_CODES, TRANSACTIONAL_KIND, type MailingErrorCode, type OutgoingMail } from "../contract.js";
+import { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS } from "../options.js";
 import { deliveries } from "../schema.js";
+import { getMailingOptions } from "./options.js";
 import { sendMail } from "./send-mail.js";
 import { getRecipientKey } from "./unsubscribe-link.js";
 
 export type DeliveryContext = ModuleContext<Queryable>;
 
-/** How long a claim may stay open before another sender may take it over. */
-export const DEFAULT_STALE_CLAIM_MS = 15 * 60_000;
+export { DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS };
 /** Claims a delivery gets before `mailing.unavailable` becomes its final outcome. */
 export const DEFAULT_MAX_ATTEMPTS = 5;
 
@@ -35,21 +39,42 @@ export interface Delivery {
 }
 
 export interface DeliverOptions {
+  /** Default: the module's `staleClaimMs` (15 minutes). */
   readonly staleClaimMs?: number;
+  /** Default: the module's `uncertainClaimMs` (23 hours). */
+  readonly uncertainClaimMs?: number;
+  /**
+   * Takes over uncertain claims too (older than `uncertainClaimMs`), accepting that their mail may arrive twice.
+   * An operator's decision, e.g. `softure-mail campaign --resend-uncertain`. Default false.
+   */
+  readonly retakeUncertain?: boolean;
   readonly maxAttempts?: number;
 }
 
+/** The codes that stop a run: the sending account, not the mail, is the problem. */
+export type HaltingErrorCode = "mailing.provider_refused" | "mailing.quota_exceeded";
+
 export type DeliveryOutcome =
   /** Sent now; `id` is the provider's message id. */
   | { readonly status: "sent"; readonly id: string }
   /** Refused now, for good (suppressed, rejected, invalid, or unavailable too many times). */
-  | { readonly status: "rejected"; readonly reason: MailingErrorCode }
+  | { readonly status: "rejected"; readonly reason: MailingErrorCode; readonly httpStatus?: number }
   /** An earlier run already closed this delivery; nothing was sent. */
   | { readonly status: "done"; readonly outcome: "sent" | "rejected" }
   /** Another sender holds a fresh claim; nothing was sent. */
   | { readonly status: "in-flight" }
+  /**
+   * A claim older than `uncertainClaimMs` is open: its mail may have gone out. Nothing was sent; only
+   * `retakeUncertain` sends it again.
+   */
+  | { readonly status: "uncertain" }
   /** The provider was unavailable; the claim is released for a later run. */
-  | { readonly status: "retry-later" };
+  | { readonly status: "retry-later"; readonly httpStatus?: number }
+  /**
+   * The provider refused the account or its quota is spent: the claim is released, its attempt given back. Stop
+   * sending (every other mail fails the same way) and run again once the account can send.
+   */
+  | { readonly status: "halted"; readonly reason: HaltingErrorCode; readonly httpStatus?: number };
 
 /**
  * Sends `delivery.mail` unless the ledger already has an outcome (or a fresh claim) for its scope
@@ -58,27 +83,55 @@ export type DeliveryOutcome =
  * malformed scope or kind, and when `sendMail` throws.
  */
 export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
-  const { staleClaimMs = DEFAULT_STALE_CLAIM_MS, maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
+  const windows = resolveClaimWindows(ctx, options);
+  const { maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
   const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
   assertDelivery(delivery, kind);
 
   const recipientKey = getRecipientKey(delivery.mail.to);
   const key = { scope: delivery.scope, recipientKey };
-  const attempt = await claimDelivery(ctx, { ...key, kind, campaignId: delivery.campaignId ?? null, staleClaimMs });
-  if (attempt === null) return readClosedDelivery(ctx, key);
+  const attempt = await claimDelivery(ctx, { ...key, kind, campaignId: delivery.campaignId ?? null, ...windows });
+  if (attempt === null) return readClosedDelivery(ctx, key, windows.uncertainClaimMs);
 
   const result = await sendMail(ctx, delivery.mail, { idempotencyKey: `${delivery.scope}:${recipientKey}` });
   const fence = { ...key, attempt };
   if (result.ok) {
-    await closeDelivery(ctx, fence, { status: "sent", providerMessageId: result.value.id, reason: null });
+    await closeDelivery(ctx, fence, { status: "sent", providerMessageId: result.value.id, reason: null, providerStatus: null });
     return { status: "sent", id: result.value.id };
   }
+  const providerStatus = result.httpStatus ?? null;
+  const httpStatus = result.httpStatus === undefined ? {} : { httpStatus: result.httpStatus };
+  if (isHaltingCode(result.error)) {
+    await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: true });
+    return { status: "halted", reason: result.error, ...httpStatus };
+  }
   if (result.error === "mailing.unavailable" && attempt < maxAttempts) {
-    await releaseDelivery(ctx, fence);
-    return { status: "retry-later" };
+    await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: false });
+    return { status: "retry-later", ...httpStatus };
+  }
+  await closeDelivery(ctx, fence, { status: "rejected", providerMessageId: null, reason: result.error, providerStatus });
+  return { status: "rejected", reason: result.error, ...httpStatus };
+}
+
+function isHaltingCode(code: MailingErrorCode): code is HaltingErrorCode {
+  return HALTING_ERROR_CODES.has(code);
+}
+
+interface ClaimWindows {
+  readonly staleClaimMs: number;
+  readonly uncertainClaimMs: number;
+  readonly retakeUncertain: boolean;
+}
+
+/** The claim windows: the call's options, else the module's, else the defaults. */
+function resolveClaimWindows(ctx: DeliveryContext, options: DeliverOptions): ClaimWindows {
+  const configured = getMailingOptions(ctx.config);
+  const staleClaimMs = options.staleClaimMs ?? configured.staleClaimMs;
+  const uncertainClaimMs = options.uncertainClaimMs ?? configured.uncertainClaimMs;
+  if (uncertainClaimMs <= staleClaimMs) {
+    throw new Error(`@softure-ai/mailing: uncertainClaimMs (${String(uncertainClaimMs)}) must be more than staleClaimMs (${String(staleClaimMs)})`);
   }
-  await closeDelivery(ctx, fence, { status: "rejected", providerMessageId: null, reason: result.error });
-  return { status: "rejected", reason: result.error };
+  return { staleClaimMs, uncertainClaimMs, retakeUncertain: options.retakeUncertain ?? false };
 }
 
 function assertDelivery(delivery: Delivery, kind: string): void {
@@ -100,31 +153,34 @@ interface DeliveryKey {
 
 /**
  * Takes the row in one statement: a new row, a `pending` one, or a claim older than
- * `staleClaimMs`. Resolves with the attempt number that fences the outcome, or `null` when the row
- * is closed or claimed by someone else.
+ * `staleClaimMs` (and, unless `retakeUncertain`, not older than `uncertainClaimMs`). Resolves with
+ * the attempt number that fences the outcome, or `null` when the row is closed, claimed by someone
+ * else, or uncertain.
  */
-async function claimDelivery(
-  ctx: DeliveryContext,
-  claim: DeliveryKey & { readonly kind: string; readonly campaignId: string | null; readonly staleClaimMs: number },
-): Promise<number | null> {
+async function claimDelivery(ctx: DeliveryContext, claim: DeliveryKey & ClaimWindows & { readonly kind: string; readonly campaignId: string | null }): Promise<number | null> {
   const now = ctx.clock.now();
   const staleBefore = new Date(now.getTime() - claim.staleClaimMs);
+  const uncertainBefore = new Date(now.getTime() - claim.uncertainClaimMs);
+  const isStale: SQL | undefined = claim.retakeUncertain
+    ? lt(deliveries.claimedAt, staleBefore)
+    : and(lt(deliveries.claimedAt, staleBefore), gte(deliveries.claimedAt, uncertainBefore));
   const rows = await ctx.db
     .insert(deliveries)
     .values({ scope: claim.scope, recipientKey: claim.recipientKey, kind: claim.kind, campaignId: claim.campaignId, status: "claimed", attempts: 1, claimedAt: now, createdAt: now })
     .onConflictDoUpdate({
       target: [deliveries.scope, deliveries.recipientKey],
       set: { status: "claimed", attempts: sql`${deliveries.attempts} + 1`, claimedAt: now },
-      setWhere: or(eq(deliveries.status, "pending"), and(eq(deliveries.status, "claimed"), lt(deliveries.claimedAt, staleBefore))),
+      setWhere: or(eq(deliveries.status, "pending"), and(eq(deliveries.status, "claimed"), isStale)),
     })
     .returning();
   return rows[0]?.attempts ?? null;
 }
 
-async function readClosedDelivery(ctx: DeliveryContext, key: DeliveryKey): Promise<DeliveryOutcome> {
-  const rows = await ctx.db.select({ status: deliveries.status }).from(deliveries).where(matchKey(key)).limit(1);
-  const status = rows[0]?.status;
-  if (status === "sent" || status === "rejected") return { status: "done", outcome: status };
+async function readClosedDelivery(ctx: DeliveryContext, key: DeliveryKey, uncertainClaimMs: number): Promise<DeliveryOutcome> {
+  const rows = await ctx.db.select({ status: deliveries.status, claimedAt: deliveries.claimedAt }).from(deliveries).where(matchKey(key)).limit(1);
+  const row = rows[0];
+  if (row?.status === "sent" || row?.status === "rejected") return { status: "done", outcome: row.status };
+  if (row?.status === "claimed" && row.claimedAt.getTime() < ctx.clock.now().getTime() - uncertainClaimMs) return { status: "uncertain" };
   // A fresh claim; `pending` only between another sender's release and this read.
   return { status: "in-flight" };
 }
@@ -135,7 +191,7 @@ type Fence = DeliveryKey & { readonly attempt: number };
 async function closeDelivery(
   ctx: DeliveryContext,
   fence: Fence,
-  outcome: { readonly status: "sent" | "rejected"; readonly providerMessageId: string | null; readonly reason: string | null },
+  outcome: { readonly status: "sent" | "rejected"; readonly providerMessageId: string | null; readonly reason: string | null; readonly providerStatus: number | null },
 ): Promise<void> {
   await ctx.db
     .update(deliveries)
@@ -143,10 +199,14 @@ async function closeDelivery(
     .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
 }
 
-async function releaseDelivery(ctx: DeliveryContext, fence: Fence): Promise<void> {
+/**
+ * Puts the claim back for a later run. A halt gives its attempt back: the account's failure says
+ * nothing about this mail, so it must not bring the delivery closer to `maxAttempts`.
+ */
+async function releaseDelivery(ctx: DeliveryContext, fence: Fence, release: { readonly providerStatus: number | null; readonly giveAttemptBack: boolean }): Promise<void> {
   await ctx.db
     .update(deliveries)
-    .set({ status: "pending" })
+    .set({ status: "pending", providerStatus: release.providerStatus, ...(release.giveAttemptBack ? { attempts: fence.attempt - 1 } : {}) })
     .where(and(matchKey(fence), eq(deliveries.status, "claimed"), eq(deliveries.attempts, fence.attempt)));
 }
 

package/src/server/index.ts

@@ -7,6 +7,7 @@ export {
   registerCampaign,
   sendCampaign,
   type CampaignErrorCode,
+  type CampaignHalt,
   type CampaignPlan,
   type CampaignSummary,
   type SendCampaignOptions,
@@ -14,11 +15,13 @@ export {
 export {
   DEFAULT_MAX_ATTEMPTS,
   DEFAULT_STALE_CLAIM_MS,
+  DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
   type DeliveryOutcome,
+  type HaltingErrorCode,
 } from "./deliveries.js";
 export {
   checkSenderDns,
@@ -39,6 +42,9 @@ export { isSuppressed, liftSuppression, suppressRecipient, unsubscribe, type Sup
 export {
   buildUnsubscribeLinks,
   getRecipientKey,
+  getUnsubscribeLinkParams,
+  MAX_LEGACY_VALUE_LENGTH,
+  readUnsubscribeLink,
   MIN_UNSUBSCRIBE_SECRET_LENGTH,
   readUnsubscribeSecrets,
   readUnsubscribeToken,
@@ -49,6 +55,8 @@ export {
   UNSUBSCRIBE_SECRET_ENV,
   verifyUnsubscribeToken,
   type Env,
+  type LinkParams,
+  type UnsubscribeLink,
   type UnsubscribeLinks,
   type UnsubscribeSecrets,
   type UnsubscribeToken,

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