@softure-ai/mailing 0.1.8 → 0.1.9

package/src/server/deliveries.ts

@@ -10,7 +10,7 @@ import type { Queryable } from "@softure-ai/db";
 import { and, eq, gte, lt, or, sql, type SQL } from "drizzle-orm";
 import { isMailKind } from "../address.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 { DEFAULT_MAX_ATTEMPTS, 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";
@@ -18,9 +18,7 @@ import { getRecipientKey } from "./unsubscribe-link.js";
 
 export type DeliveryContext = ModuleContext<Queryable>;
 
-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;
+export { DEFAULT_MAX_ATTEMPTS, DEFAULT_STALE_CLAIM_MS, DEFAULT_UNCERTAIN_CLAIM_MS };
 
 const MAX_SCOPE_LENGTH = 128;
 const SCOPE = /^[a-z0-9][a-z0-9._:-]*$/;
@@ -48,7 +46,11 @@ export interface DeliverOptions {
    * An operator's decision, e.g. `softure-mail campaign --resend-uncertain`. Default false.
    */
   readonly retakeUncertain?: boolean;
-  readonly maxAttempts?: number;
+  /**
+   * Claims before `mailing.unavailable` closes the delivery as rejected; `null` never closes it. Default: the module's
+   * `maxAttempts` (5).
+   */
+  readonly maxAttempts?: number | null;
 }
 
 /** The codes that stop a run: the sending account, not the mail, is the problem. */
@@ -84,7 +86,7 @@ export type DeliveryOutcome =
  */
 export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
   const windows = resolveClaimWindows(ctx, options);
-  const { maxAttempts = DEFAULT_MAX_ATTEMPTS } = options;
+  const maxAttempts = options.maxAttempts === undefined ? getMailingOptions(ctx.config).maxAttempts : options.maxAttempts;
   const kind = delivery.mail.kind ?? TRANSACTIONAL_KIND;
   assertDelivery(delivery, kind);
 
@@ -105,7 +107,7 @@ export async function deliverOnce(ctx: DeliveryContext, delivery: Delivery, opti
     await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: true });
     return { status: "halted", reason: result.error, ...httpStatus };
   }
-  if (result.error === "mailing.unavailable" && attempt < maxAttempts) {
+  if (result.error === "mailing.unavailable" && (maxAttempts === null || attempt < maxAttempts)) {
     await releaseDelivery(ctx, fence, { providerStatus, giveAttemptBack: false });
     return { status: "retry-later", ...httpStatus };
   }
@@ -134,8 +136,13 @@ function resolveClaimWindows(ctx: DeliveryContext, options: DeliverOptions): Cla
   return { staleClaimMs, uncertainClaimMs, retakeUncertain: options.retakeUncertain ?? false };
 }
 
+/** Lowercase letters, digits and `._:-`, at most 128 characters. */
+export function isDeliveryScope(scope: string): boolean {
+  return scope.length <= MAX_SCOPE_LENGTH && SCOPE.test(scope);
+}
+
 function assertDelivery(delivery: Delivery, kind: string): void {
-  if (delivery.scope.length > MAX_SCOPE_LENGTH || !SCOPE.test(delivery.scope)) {
+  if (!isDeliveryScope(delivery.scope)) {
     throw new Error(`@softure-ai/mailing: deliverOnce scope "${delivery.scope}" must be lowercase letters, digits and ._:- (at most 128 characters)`);
   }
   if (!isMailKind(kind)) {

package/src/server/import-deliveries.ts

@@ -0,0 +1,149 @@
+// Seeds the delivery ledger with deliveries an app made before it adopted the module, so `deliverOnce` and
+// campaigns skip them. Every row is checked before anything is written; a row whose scope and recipient are
+// already in the ledger is left as it is (the ledger wins, and a live claim keeps its fence), so a re-run imports
+// nothing twice.
+import { isMailKind, isSingleAddress } from "../address.js";
+import { TRANSACTIONAL_KIND, type MailingErrorCode } from "../contract.js";
+import { deliveries } from "../schema.js";
+import { isDeliveryScope, type DeliveryContext } from "./deliveries.js";
+import { getRecipientKey } from "./unsubscribe-link.js";
+
+/** The reasons a rejected row may carry: the codes `deliverOnce` closes a row with. */
+export type ImportedRejectionReason = Extract<MailingErrorCode, "mailing.invalid_input" | "mailing.rejected" | "mailing.unavailable" | "mailing.suppressed">;
+
+const REJECTION_REASONS: ReadonlySet<string> = new Set<ImportedRejectionReason>(["mailing.invalid_input", "mailing.rejected", "mailing.unavailable", "mailing.suppressed"]);
+
+/** Rows written per statement. */
+const BATCH_SIZE = 500;
+
+export interface ImportedDelivery {
+  /** The scope `deliverOnce` will use for this mail: `campaign:<id>` for a campaign, else e.g. `billing.trial-ending:sub_42`. */
+  readonly scope: string;
+  /** The recipient's address; only its key is stored (any case or spacing gives the same key). */
+  readonly address: string;
+  readonly status: "sent" | "rejected";
+  /** When the delivery was closed; a `Date` or an ISO 8601 string, not in the future. */
+  readonly finishedAt: Date | string;
+  /** The provider's message id, when the app kept it. Only on `sent`. */
+  readonly providerMessageId?: string;
+  /** Why a rejected delivery is final. Only on `rejected`; default `mailing.rejected`. */
+  readonly reason?: ImportedRejectionReason;
+  /** The mail kind. Default `transactional`. */
+  readonly kind?: string;
+}
+
+export interface ImportProblem {
+  /** The row's index in the input (0-based). */
+  readonly index: number;
+  /** What is wrong, naming the field; never the address. */
+  readonly problem: string;
+}
+
+export interface ImportSummary {
+  /** Rows given. */
+  readonly rows: number;
+  /** Rows written now. */
+  readonly imported: number;
+  /** Rows whose scope and recipient the ledger already had (from an earlier import or a send); left as they were. */
+  readonly alreadyPresent: number;
+  /** Rows with the scope and recipient of an earlier row in the input; the first one counts. */
+  readonly duplicates: number;
+}
+
+/** The import's answer: a summary, or every problem (and nothing written). */
+export type ImportResult = { readonly ok: true; readonly value: ImportSummary } | { readonly ok: false; readonly problems: readonly ImportProblem[] };
+
+/** The checked rows, ready for the ledger, or every problem. */
+export type ImportCheck =
+  | { readonly ok: true; readonly value: { readonly ledgerRows: readonly LedgerRow[]; readonly duplicates: number } }
+  | { readonly ok: false; readonly problems: readonly ImportProblem[] };
+
+type LedgerRow = typeof deliveries.$inferInsert;
+
+/**
+ * Writes `rows` into `mailing.deliveries` as closed deliveries. Returns the problems, and writes nothing, when any
+ * row is invalid. Throws on a database failure; rows written before it stay, and a re-run skips them.
+ */
+export async function importDeliveries(ctx: DeliveryContext, rows: readonly ImportedDelivery[]): Promise<ImportResult> {
+  const checked = checkImportedDeliveries(ctx, rows);
+  if (!checked.ok) return checked;
+  const { ledgerRows, duplicates } = checked.value;
+
+  let imported = 0;
+  for (let start = 0; start < ledgerRows.length; start += BATCH_SIZE) {
+    const written = await ctx.db
+      .insert(deliveries)
+      .values(ledgerRows.slice(start, start + BATCH_SIZE))
+      .onConflictDoNothing({ target: [deliveries.scope, deliveries.recipientKey] })
+      .returning();
+    imported += written.length;
+  }
+  return { ok: true, value: { rows: rows.length, imported, alreadyPresent: ledgerRows.length - imported, duplicates } };
+}
+
+/**
+ * Checks every row and builds the ledger rows, without touching the database (e.g. for a dry run). The problems
+ * cover every invalid row, not only the first.
+ */
+export function checkImportedDeliveries(
+  ctx: Pick<DeliveryContext, "clock">,
+  rows: readonly ImportedDelivery[],
+): ImportCheck {
+  const now = ctx.clock.now();
+  const problems: ImportProblem[] = [];
+  const ledgerRows: LedgerRow[] = [];
+  const seen = new Set<string>();
+  let duplicates = 0;
+  rows.forEach((row, index) => {
+    const rowProblems = findRowProblems(row, now);
+    if (rowProblems.length > 0) {
+      problems.push(...rowProblems.map((problem) => ({ index, problem })));
+      return;
+    }
+    const recipientKey = getRecipientKey(row.address);
+    const key = `${row.scope}\n${recipientKey}`;
+    if (seen.has(key)) {
+      duplicates += 1;
+      return;
+    }
+    seen.add(key);
+    const finishedAt = new Date(row.finishedAt);
+    ledgerRows.push({
+      scope: row.scope,
+      recipientKey,
+      kind: row.kind ?? TRANSACTIONAL_KIND,
+      // Campaign rows are matched by scope; a campaign id would need the campaign's content, which history lacks.
+      campaignId: null,
+      status: row.status,
+      attempts: 1,
+      claimedAt: finishedAt,
+      finishedAt,
+      providerMessageId: row.status === "sent" ? (row.providerMessageId ?? null) : null,
+      reason: row.status === "rejected" ? (row.reason ?? "mailing.rejected") : null,
+      providerStatus: null,
+      createdAt: now,
+      importedAt: now,
+    });
+  });
+  return problems.length > 0 ? { ok: false, problems } : { ok: true, value: { ledgerRows, duplicates } };
+}
+
+function findRowProblems(row: ImportedDelivery, now: Date): string[] {
+  const problems: string[] = [];
+  if (!isDeliveryScope(row.scope)) problems.push("scope must be lowercase letters, digits and ._:- (at most 128 characters)");
+  if (!isSingleAddress(row.address.trim())) problems.push("address must be one email address");
+  if (row.status !== "sent" && row.status !== "rejected") problems.push('status must be "sent" or "rejected"');
+  const finishedAt = new Date(row.finishedAt);
+  if (Number.isNaN(finishedAt.getTime())) problems.push("finishedAt must be a date");
+  else if (finishedAt.getTime() > now.getTime()) problems.push("finishedAt must not be in the future");
+  if (row.providerMessageId !== undefined) {
+    if (row.status !== "sent") problems.push("providerMessageId belongs only to a sent row");
+    else if (row.providerMessageId.trim() === "" || row.providerMessageId.length > 256) problems.push("providerMessageId must be 1 to 256 characters");
+  }
+  if (row.reason !== undefined) {
+    if (row.status !== "rejected") problems.push("reason belongs only to a rejected row");
+    else if (!REJECTION_REASONS.has(row.reason)) problems.push(`reason must be one of ${[...REJECTION_REASONS].join(", ")}`);
+  }
+  if (row.kind !== undefined && !isMailKind(row.kind)) problems.push("kind must be kebab-case (at most 64 characters)");
+  return problems;
+}

package/src/server/index.ts

@@ -3,6 +3,7 @@
 export { getCampaignProblems, parseCampaignFile, parseRecipientList, type CampaignContent, type CampaignFile, type CampaignFileResult } from "./campaign-file.js";
 export {
   getCampaignContentHash,
+  listConfiguredCampaignRecipients,
   planCampaign,
   registerCampaign,
   sendCampaign,
@@ -17,6 +18,7 @@ export {
   DEFAULT_STALE_CLAIM_MS,
   DEFAULT_UNCERTAIN_CLAIM_MS,
   deliverOnce,
+  isDeliveryScope,
   type DeliverOptions,
   type Delivery,
   type DeliveryContext,
@@ -44,6 +46,16 @@ export {
   type SenderDnsReport,
 } from "./dns.js";
 export { checkMailingTables } from "./health.js";
+export {
+  checkImportedDeliveries,
+  importDeliveries,
+  type ImportCheck,
+  type ImportedDelivery,
+  type ImportedRejectionReason,
+  type ImportProblem,
+  type ImportResult,
+  type ImportSummary,
+} from "./import-deliveries.js";
 export { addHtmlFooter, addTextFooter, getListUnsubscribeHeaders, SIGNATURE_SEPARATOR } from "./list-mail.js";
 export { getMailingModule, getMailingOptions, getMailingRoutes, type MailingRoutes } from "./options.js";
 export { sendMail, type MailContext } from "./send-mail.js";

package/src/server/suppressions.ts

@@ -6,7 +6,7 @@
 import { err, ok, type ModuleContext, type Result } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import { and, eq, inArray } from "drizzle-orm";
-import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
+import type { SuppressionSource, UnsubscribeErrorCode, VerifiedUnsubscribeLink } from "../contract.js";
 import { suppressions } from "../schema.js";
 import { getMailingOptions } from "./options.js";
 import { getRecipientKey, readUnsubscribeSecrets, verifyUnsubscribeToken, type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubscribe-link.js";
@@ -67,26 +67,33 @@ export async function unsubscribe(
   source: Exclude<SuppressionSource, "operator">,
   env: Env = process.env,
 ): Promise<Result<undefined, UnsubscribeErrorCode>> {
-  const recipientKey = await verifyLink(ctx, link, env);
-  if (recipientKey === null) return err("mailing.invalid_link");
+  const verified = await verifyLink(ctx, link, env);
+  if (verified === null) return err("mailing.invalid_link");
+  const { recipientKey } = verified;
   const { onUnsubscribed } = getMailingOptions(ctx.config);
   await ctx.db.transaction(async (tx) => {
     const txCtx: SuppressionContext = { ...ctx, db: tx };
     await recordSuppression(txCtx, recipientKey, source);
-    await onUnsubscribed?.({ recipientKey, source }, txCtx);
+    await onUnsubscribed?.({ recipientKey, source, link: verified.link }, txCtx);
   });
   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> {
+interface VerifiedLink {
+  readonly recipientKey: string;
+  readonly link: VerifiedUnsubscribeLink;
+}
+
+/** The recipient key a link proves and the link it came through, or `null` when it proves none. */
+async function verifyLink(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, env: Env): Promise<VerifiedLink | 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;
+    return verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)) ? { recipientKey: token.recipientKey, link: { scheme: "signed" } } : 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;
+  if (typeof address !== "string" || address.trim() === "") return null;
+  return { recipientKey: getRecipientKey(address), link: { scheme: "legacy", values: link.values } };
 }

package/src/server/unsubscribe-link.ts

@@ -117,8 +117,9 @@ export interface LinkParams {
 /**
  * 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.
+ * `mailing({ legacyUnsubscribe })`, a link that has every required legacy parameter (non-empty, at most 512
+ * characters) is a legacy link; its values also hold the optional parameters it has (an empty one is absent, one
+ * over 512 characters makes the link invalid). 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) {
@@ -128,11 +129,17 @@ export function readUnsubscribeLink(params: LinkParams, config: SoftureConfig):
   const legacy = getMailingOptions(config).legacyUnsubscribe;
   if (legacy === undefined) return null;
   const values: Record<string, string> = {};
-  for (const name of legacy.params) {
+  for (const name of legacy.params.required) {
     const value = params.get(name);
     if (typeof value !== "string" || value === "" || value.length > MAX_LEGACY_VALUE_LENGTH) return null;
     values[name] = value;
   }
+  for (const name of legacy.params.optional) {
+    const value = params.get(name);
+    if (typeof value !== "string" || value === "") continue;
+    if (value.length > MAX_LEGACY_VALUE_LENGTH) return null;
+    values[name] = value;
+  }
   return { scheme: "legacy", values };
 }