@softure-ai/mailing 0.1.6 → 0.1.7

package/dist/server/suppressions.d.ts

@@ -1,7 +1,7 @@
 import { type ModuleContext, type Result } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 import type { SuppressionSource, UnsubscribeErrorCode } from "../contract.js";
-import { type Env, type UnsubscribeToken } from "./unsubscribe-link.js";
+import { type Env, type UnsubscribeLink, type UnsubscribeToken } from "./unsubscribe-link.js";
 export type SuppressionContext = ModuleContext<Queryable>;
 /** Whether `address` unsubscribed. Throws on a database failure: callers decide how to fail. */
 export declare function isSuppressed(ctx: Pick<SuppressionContext, "db">, address: string): Promise<boolean>;
@@ -18,10 +18,12 @@ export declare function suppressRecipient(ctx: SuppressionContext, address: stri
  */
 export declare function liftSuppression(ctx: Pick<SuppressionContext, "db">, address: string): Promise<boolean>;
 /**
- * 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 declare function unsubscribe(ctx: SuppressionContext, token: UnsubscribeToken | null, source: Exclude<SuppressionSource, "operator">, env?: Env): Promise<Result<undefined, UnsubscribeErrorCode>>;
+export declare function unsubscribe(ctx: SuppressionContext, link: UnsubscribeLink | UnsubscribeToken | null, source: Exclude<SuppressionSource, "operator">, env?: Env): Promise<Result<undefined, UnsubscribeErrorCode>>;
 //# sourceMappingURL=suppressions.d.ts.map

package/dist/server/suppressions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suppressions.d.ts","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,OAAO,EAAmE,KAAK,GAAG,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzI,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAE1D,gGAAgG;AAChG,wBAAsB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzG;AAOD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,iBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvI;AAKD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5G;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,gBAAgB,GAAG,IAAI,EAC9B,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAC9C,GAAG,GAAE,GAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAUlD"}
+{"version":3,"file":"suppressions.d.ts","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"AAKA,OAAO,EAAW,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,OAAO,EAAmE,KAAK,GAAG,EAAE,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE/J,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAE1D,gGAAgG;AAChG,wBAAsB,YAAY,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOzG;AAOD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,iBAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvI;AAKD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAM5G;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,kBAAkB,EACvB,IAAI,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,EAC/C,MAAM,EAAE,OAAO,CAAC,iBAAiB,EAAE,UAAU,CAAC,EAC9C,GAAG,GAAE,GAAiB,GACrB,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAUlD"}

package/dist/server/suppressions.js

@@ -44,16 +44,18 @@ export async function liftSuppression(ctx, address) {
     return lifted.length > 0;
 }
 /**
- * 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, token, source, env = process.env) {
-    if (token === null || !verifyUnsubscribeToken(token, readUnsubscribeSecrets(env)))
+export async function unsubscribe(ctx, link, source, env = process.env) {
+    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 = { ...ctx, db: tx };
         await recordSuppression(txCtx, recipientKey, source);
@@ -61,4 +63,18 @@ export async function unsubscribe(ctx, token, source, env = process.env) {
     });
     return ok();
 }
+/** The recipient key a link proves, or `null` when it proves none. */
+async function verifyLink(ctx, link, env) {
+    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 = await legacy.verify(link.values, ctx);
+    return typeof address === "string" && address.trim() !== "" ? getRecipientKey(address) : null;
+}
 //# sourceMappingURL=suppressions.js.map

package/dist/server/suppressions.js.map

@@ -1 +1 @@
-{"version":3,"file":"suppressions.js","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"suppressions.js","sourceRoot":"","sources":["../../src/server/suppressions.ts"],"names":[],"mappings":"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"}

package/dist/server/unsubscribe-link.d.ts

@@ -44,6 +44,29 @@ export declare function readUnsubscribeSecrets(env?: Env): UnsubscribeSecrets;
 export declare function verifyUnsubscribeToken(token: UnsubscribeToken, secrets: UnsubscribeSecrets): boolean;
 /** The two links for `address`, on the app's origin and the module's routes. */
 export declare function buildUnsubscribeLinks(config: SoftureConfig, address: string, secret: string): UnsubscribeLinks;
+/** A legacy link's value longer than this makes the link invalid before the app's `verify` sees it. */
+export declare 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 declare function readUnsubscribeLink(params: LinkParams, config: SoftureConfig): UnsubscribeLink | null;
+/** The query (or form) parameters that carry `link`, to send it back to the page. */
+export declare function getUnsubscribeLinkParams(link: UnsubscribeLink): Record<string, string>;
 /** The token in a link's query (or a form), when both parameters are present once. */
 export declare function readUnsubscribeToken(params: {
     get(name: string): unknown;

package/dist/server/unsubscribe-link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unsubscribe-link.d.ts","sourceRoot":"","sources":["../../src/server/unsubscribe-link.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,yCAAyC;AACzC,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AACnE,sEAAsE;AACtE,eAAO,MAAM,+BAA+B,wCAAwC,CAAC;AACrF,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,0CAA0C;AAC1C,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,eAAe,MAAM,CAAC;AAWnC,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE/D,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,GAAiB,GAAG,kBAAkB,CAEjF;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAWpG;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQ9G;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,gBAAgB,GAAG,IAAI,CAIpG"}
+{"version":3,"file":"unsubscribe-link.d.ts","sourceRoot":"","sources":["../../src/server/unsubscribe-link.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,yCAAyC;AACzC,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AACnE,sEAAsE;AACtE,eAAO,MAAM,+BAA+B,wCAAwC,CAAC;AACrF,kFAAkF;AAClF,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,0CAA0C;AAC1C,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,eAAe,MAAM,CAAC;AAWnC,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE/D,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wCAAwC;AACxC,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,GAAG,GAAE,GAAiB,GAAG,kBAAkB,CAEjF;AAMD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAWpG;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAQ9G;AAED,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,6GAA6G;AAC7G,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAC;AAErF,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,eAAe,GAAG,IAAI,CAcrG;AAED,qFAAqF;AACrF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEtF;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,gBAAgB,GAAG,IAAI,CAIpG"}

package/dist/server/unsubscribe-link.js

@@ -4,7 +4,7 @@
 // during a rotation. The whole link is a credential: whoever has it can unsubscribe that address,
 // so it never reaches a log, an error or a result.
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-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";
 /** Optional: verifies links signed before a rotation, never signs. */
@@ -69,6 +69,35 @@ export function buildUnsubscribeLinks(config, address, secret) {
         oneClick: `${config.appOrigin}${routes.oneClick}?${query.toString()}`,
     };
 }
+/** 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 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, config) {
+    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 = {};
+    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) {
+    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) {
     const recipientKey = params.get(RECIPIENT_PARAM);

package/dist/server/unsubscribe-link.js.map

@@ -1 +1 @@
-{"version":3,"file":"unsubscribe-link.js","sourceRoot":"","sources":["../../src/server/unsubscribe-link.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"unsubscribe-link.js","sourceRoot":"","sources":["../../src/server/unsubscribe-link.ts"],"names":[],"mappings":"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"}

package/migrations/0003_add_delivery_provider_status.sql

@@ -0,0 +1,13 @@
+-- Keeps the provider's HTTP status with a delivery (the last failed answer, also on a released claim), and lets a
+-- released claim give its attempt back: a halt (refused key, spent quota) says nothing about the mail, so a
+-- `pending` row may hold 0 attempts until it is claimed again.
+-- Rollback: ALTER TABLE mailing.deliveries DROP COLUMN provider_status;
+--   UPDATE mailing.deliveries SET attempts = 1 WHERE attempts = 0;
+--   ALTER TABLE mailing.deliveries DROP CONSTRAINT deliveries_attempts_check;
+--   ALTER TABLE mailing.deliveries ADD CONSTRAINT deliveries_attempts_check CHECK (attempts >= 1);
+--   DELETE FROM softure.migrations WHERE module = 'mailing' AND version = 3;
+
+ALTER TABLE deliveries ADD COLUMN provider_status integer CHECK (provider_status BETWEEN 100 AND 599);
+
+ALTER TABLE deliveries DROP CONSTRAINT deliveries_attempts_check;
+ALTER TABLE deliveries ADD CONSTRAINT deliveries_attempts_check CHECK (attempts >= 1 OR (attempts = 0 AND status = 'pending'));

package/module.json

@@ -1,6 +1,6 @@
 {
   "id": "mailing",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "dependsOn": {},
   "dbSchema": "mailing",
   "tables": ["suppressions", "campaigns", "deliveries"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/mailing",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "SOFTURE AI mailing module: sendMail over a provider adapter (Resend first) with plain-text and HTML bodies, sender and reply-to from config, idempotency keys, a timeout and a typed result; signed one-click unsubscribe (RFC 8058) with a suppression list for list mail; an exactly-once delivery ledger, campaigns sent from a content file by the softure-mail command, and a sender DNS check; a fake provider for tests.",
   "license": "MIT",
   "type": "module",

package/src/cli/run.ts

@@ -13,7 +13,7 @@ import { systemClock, type SoftureConfig, type SoftureDatabaseConfig } from "@so
 import { openCommandDatabase, type CommandDatabase, type DatabaseHandle } from "@softure-ai/db";
 import { parseCampaignFile, parseRecipientList, type CampaignContent } from "../server/campaign-file.js";
 import { planCampaign, sendCampaign, type CampaignSummary } from "../server/campaigns.js";
-import type { DeliveryContext } from "../server/deliveries.js";
+import type { DeliveryContext, HaltingErrorCode } from "../server/deliveries.js";
 import { checkSenderDns, getSenderDomain, type DnsCheck, type ResolveTxt } from "../server/dns.js";
 import { getMailingOptions } from "../server/options.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "../server/unsubscribe-link.js";
@@ -46,14 +46,17 @@ export const EXIT_USAGE = 2;
 export const DEFAULT_PAUSE_MS = 500;
 
 export const MAIL_USAGE = `Usage:
-  softure-mail campaign <content-file> --recipients <file> [--dry-run] [--pause-ms <ms>]
+  softure-mail campaign <content-file> --recipients <file> [--dry-run] [--pause-ms <ms>] [--resend-uncertain]
   softure-mail dns [--domain <domain>] [--dkim-selector <name>]... [--spf-host <host>]...
 
 campaign  Sends the campaign in <content-file> (frontmatter id, kind, subject, optional html,
           then the text body) to every address in the recipients file (one per line), at most
-          once each. Re-running sends only to recipients without an outcome yet.
-  --dry-run          count what would be sent and change nothing
-  --pause-ms <ms>    pause after every send (default ${String(DEFAULT_PAUSE_MS)})
+          once each. Re-running sends only to recipients without an outcome yet. A refused
+          API key or a spent quota stops the run; the rest go out on the next one.
+  --dry-run            count what would be sent and change nothing
+  --pause-ms <ms>      pause after every send (default ${String(DEFAULT_PAUSE_MS)})
+  --resend-uncertain   also send to recipients whose send was interrupted long ago
+                       (it may have gone out: they may get the mail twice)
 
 dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain of "from").
   --domain <domain>       check this domain instead
@@ -72,7 +75,14 @@ const consoleOutput: CliOutput = {
 
 type Command =
   | { readonly kind: "help" }
-  | { readonly kind: "campaign"; readonly contentFile: string; readonly recipientsFile: string; readonly dryRun: boolean; readonly pauseMs: number }
+  | {
+      readonly kind: "campaign";
+      readonly contentFile: string;
+      readonly recipientsFile: string;
+      readonly dryRun: boolean;
+      readonly pauseMs: number;
+      readonly resendUncertain: boolean;
+    }
   | { readonly kind: "dns"; readonly domain: string | undefined; readonly dkimSelectors: readonly string[] | undefined; readonly spfHosts: readonly string[] | undefined };
 
 /** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
@@ -111,7 +121,7 @@ function parseCommand(argv: readonly string[]): Command | string {
   if (values.help === true) return { kind: "help" };
 
   if (name === "dns") {
-    const misplaced = (["recipients", "dry-run", "pause-ms"] as const).filter((option) => values[option] !== undefined);
+    const misplaced = (["recipients", "dry-run", "pause-ms", "resend-uncertain"] as const).filter((option) => values[option] !== undefined);
     if (misplaced.length > 0) return `dns does not take --${misplaced.join(", --")}`;
     if (positionals.length > 0) return `dns takes no file, got "${positionals.join(" ")}"`;
     return { kind: "dns", domain: values.domain, dkimSelectors: values["dkim-selector"], spfHosts: values["spf-host"] };
@@ -125,7 +135,7 @@ function parseCommand(argv: readonly string[]): Command | string {
   if (values.recipients === undefined) return "campaign needs --recipients <file>";
   const pauseMs = values["pause-ms"] === undefined ? DEFAULT_PAUSE_MS : Number(values["pause-ms"]);
   if (!Number.isInteger(pauseMs) || pauseMs < 0 || pauseMs > 60_000) return `--pause-ms expects whole milliseconds from 0 to 60000, got "${values["pause-ms"] ?? ""}"`;
-  return { kind: "campaign", contentFile, recipientsFile: values.recipients, dryRun: values["dry-run"] === true, pauseMs };
+  return { kind: "campaign", contentFile, recipientsFile: values.recipients, dryRun: values["dry-run"] === true, pauseMs, resendUncertain: values["resend-uncertain"] === true };
 }
 
 function parseCommandArgs(args: readonly string[]) {
@@ -135,6 +145,7 @@ function parseCommandArgs(args: readonly string[]) {
       recipients: { type: "string" },
       "dry-run": { type: "boolean" },
       "pause-ms": { type: "string" },
+      "resend-uncertain": { type: "boolean" },
       domain: { type: "string" },
       "dkim-selector": { type: "string", multiple: true },
       "spf-host": { type: "string", multiple: true },
@@ -205,7 +216,9 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
   }
   const ctx: DeliveryContext = { db: opened.handle.db, clock: systemClock, config };
   try {
-    return command.dryRun ? await reportPlan(ctx, loaded, output) : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep }, output);
+    return command.dryRun
+      ? await reportPlan(ctx, loaded, command.resendUncertain, output)
+      : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep, retakeUncertain: command.resendUncertain }, output);
   } catch (error) {
     // Driver errors: the message only, never a stack, an address or the database URL.
     output.error(`softure-mail campaign: ${describeError(error)} (did softure migrate run?)`);
@@ -238,10 +251,19 @@ async function loadCampaign(contentPath: string, recipientsPath: string): Promis
   return { campaign: { ...content, html }, recipients: parseRecipientList(list) };
 }
 
-async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, output: CliOutput): Promise<number> {
-  const plan = await planCampaign(ctx, loaded);
+async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, retakeUncertain: boolean, output: CliOutput): Promise<number> {
+  const plan = await planCampaign(ctx, loaded, { retakeUncertain });
   output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}), dry run: nothing sent or written`);
-  output.log(`recipients ${String(plan.recipients)}, already done ${String(plan.done)}, unsubscribed ${String(plan.suppressed)}, to send ${String(plan.toSend)}`);
+  output.log(
+    [
+      `recipients ${String(plan.recipients)}`,
+      `already done ${String(plan.done)}`,
+      `unsubscribed ${String(plan.suppressed)}`,
+      `filtered out ${String(plan.filtered)}`,
+      `uncertain ${String(plan.uncertain)}`,
+      `to send ${String(plan.toSend)}`,
+    ].join(", "),
+  );
   if (plan.contentChanged) {
     output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
     return EXIT_FAILED;
@@ -252,13 +274,14 @@ async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, output:
 async function reportSend(
   ctx: DeliveryContext,
   loaded: LoadedCampaign,
-  pace: { readonly pauseMs: number; readonly sleep: ((ms: number) => Promise<void>) | undefined },
+  pace: { readonly pauseMs: number; readonly sleep: ((ms: number) => Promise<void>) | undefined; readonly retakeUncertain: boolean },
   output: CliOutput,
 ): Promise<number> {
   let handled = 0;
   const total = loaded.recipients.length;
   const result = await sendCampaign(ctx, loaded, {
     pauseMs: pace.pauseMs,
+    retakeUncertain: pace.retakeUncertain,
     ...(pace.sleep === undefined ? {} : { sleep: pace.sleep }),
     onDelivery: () => {
       handled += 1;
@@ -269,15 +292,33 @@ async function reportSend(
     output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
     return EXIT_FAILED;
   }
-  output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}): ${formatSummary(result.value)}`);
-  const open = result.value.inFlight + result.value.retryLater;
-  if (open > 0) {
+  const summary = result.value;
+  output.log(`campaign ${loaded.campaign.id} (${loaded.campaign.kind}): ${formatSummary(summary)}`);
+  let code = EXIT_OK;
+  if (summary.halted !== null) {
+    const status = summary.halted.httpStatus === undefined ? "" : ` (HTTP ${String(summary.halted.httpStatus)})`;
+    output.error(`stopped: ${HALT_EXPLANATIONS[summary.halted.reason]}${status}; the remaining recipients were not touched, run the same command again once it is fixed`);
+    code = EXIT_FAILED;
+  }
+  const open = summary.inFlight + summary.retryLater;
+  if (open > 0 && summary.halted === null) {
     output.error(`${String(open)} recipient(s) have no outcome yet; run the same command again later`);
-    return EXIT_FAILED;
+    code = EXIT_FAILED;
   }
-  return EXIT_OK;
+  if (summary.uncertain > 0) {
+    output.error(
+      `${String(summary.uncertain)} recipient(s) are uncertain: a send was interrupted long ago and may have gone out; check the provider's log, then run again with --resend-uncertain to send them anyway`,
+    );
+    code = EXIT_FAILED;
+  }
+  return code;
 }
 
+const HALT_EXPLANATIONS: Readonly<Record<HaltingErrorCode, string>> = {
+  "mailing.provider_refused": "the provider refused the account (check the API key and the account)",
+  "mailing.quota_exceeded": "the account's sending quota is spent",
+};
+
 function formatSummary(summary: CampaignSummary): string {
   const rejected = Object.entries(summary.rejected).filter(([, count]) => count > 0);
   const rejectedTotal = rejected.reduce((sum, [, count]) => sum + count, 0);
@@ -289,6 +330,8 @@ function formatSummary(summary: CampaignSummary): string {
     `already done ${String(summary.done)}`,
     `in flight ${String(summary.inFlight)}`,
     `retry later ${String(summary.retryLater)}`,
+    `filtered out ${String(summary.filtered)}`,
+    `uncertain ${String(summary.uncertain)}`,
   ].join(", ");
 }
 

package/src/contract.ts

@@ -1,6 +1,6 @@
 // Result types, error codes and the provider contract of the mailing module. No user-facing copy
 // here: the UI translates codes through `messages` (docs/02-module-standard.md §6).
-import type { ModuleContext, Result } from "@softure-ai/core";
+import type { Err, ModuleContext, Ok } from "@softure-ai/core";
 import type { Queryable } from "@softure-ai/db";
 
 export type MailingErrorCode =
@@ -11,7 +11,17 @@ export type MailingErrorCode =
   /** The provider could not be reached or did not answer in time. Retry later, with the same idempotency key. */
   | "mailing.unavailable"
   /** A list mail to a recipient who unsubscribed. Nothing was sent; do not retry. */
-  | "mailing.suppressed";
+  | "mailing.suppressed"
+  /**
+   * The provider refuses the sender, not the mail: a wrong or revoked API key, a suspended or restricted account
+   * (HTTP 401/403). Every other mail would fail the same way: stop sending, fix the account, then retry.
+   */
+  | "mailing.provider_refused"
+  /** The account's sending quota is spent (HTTP 429 that is not a rate limit). Stop sending; retry when it renews. */
+  | "mailing.quota_exceeded";
+
+/** The codes that are about the sending account, not the mail: a run of sends stops at the first one. */
+export const HALTING_ERROR_CODES: ReadonlySet<MailingErrorCode> = new Set(["mailing.provider_refused", "mailing.quota_exceeded"]);
 
 /** Why an unsubscribe link was refused: missing, malformed, or not signed by a current secret. */
 export type UnsubscribeErrorCode = "mailing.invalid_link";
@@ -36,6 +46,32 @@ export interface UnsubscribeEvent {
  */
 export type OnUnsubscribedHook = (event: UnsubscribeEvent, ctx: ModuleContext<Queryable>) => Promise<void>;
 
+/** What `filterCampaignRecipient` receives for each recipient of a campaign. */
+export interface CampaignRecipient {
+  readonly address: string;
+  /** The recipient key of the address (`getRecipientKey`). */
+  readonly recipientKey: string;
+  readonly campaign: { readonly id: string; readonly kind: string };
+}
+
+/**
+ * Decides whether a campaign goes to a recipient, e.g. by the consent scope the app stored for the address. A
+ * recipient it refuses is skipped before the ledger is touched, so a later re-run sends to them once they qualify.
+ * A throw stops the campaign, like a database failure. Set in `mailing({ filterCampaignRecipient })`.
+ */
+export type CampaignRecipientFilter = (recipient: CampaignRecipient, ctx: ModuleContext<Queryable>) => Promise<boolean>;
+
+/**
+ * Unsubscribe links an app sent before it adopted the module, in its own scheme. `params` are the query names of
+ * such a link; `verify` receives their values (all present once, each at most 512 characters) and returns the
+ * recipient's address when the link is genuine, else `null`. It must check the link's signature itself: whatever
+ * address it returns is unsubscribed. A throw reads as a failure (the person may try again), not as a bad link.
+ */
+export interface LegacyUnsubscribe {
+  readonly params: readonly string[];
+  readonly verify: (values: Readonly<Record<string, string>>, ctx: ModuleContext<Queryable>) => Promise<string | null>;
+}
+
 /** One mail to one recipient. A mail to a list is a loop over recipients, never a list in `to`. */
 export interface OutgoingMail {
   /** Exactly one address: `ada@example.com`. */
@@ -77,7 +113,10 @@ export interface SentMail {
   readonly provider: string;
 }
 
-export type SendMailResult = Result<SentMail, MailingErrorCode>;
+/** A failed send: the code, and the provider's HTTP status when it answered with one. */
+export type SendMailFailure = Err<MailingErrorCode> & { readonly httpStatus?: number };
+
+export type SendMailResult = Ok<SentMail> | SendMailFailure;
 
 /** What a provider receives: a validated mail with the sender and reply-to from the configuration. */
 export interface ProviderMessage {
@@ -91,11 +130,15 @@ export interface ProviderMessage {
   readonly idempotencyKey: string | null;
 }
 
-/** What a provider answers. `httpStatus` is logged; the mail never is. */
+/**
+ * What a provider answers. `httpStatus` is logged and returned with the failure; the mail never is. `refused` is the
+ * provider refusing the sender (key, account), `quota_exceeded` a spent sending quota; `rejected` is about this mail.
+ */
 export type ProviderOutcome =
   | { readonly status: "sent"; readonly id: string }
-  | { readonly status: "rejected"; readonly httpStatus?: number }
-  | { readonly status: "unavailable"; readonly httpStatus?: number };
+  | { readonly status: ProviderFailureStatus; readonly httpStatus?: number };
+
+export type ProviderFailureStatus = "rejected" | "unavailable" | "refused" | "quota_exceeded";
 
 /**
  * A mail service adapter. `send` should resolve with an outcome for every failure it knows; a

package/src/index.ts

@@ -17,7 +17,7 @@ export const MODULE_ID = "mailing";
 export const mailing = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.1.6",
+    version: "0.1.7",
     dependsOn: {},
     dbSchema: "mailing",
     tables: ["suppressions", "campaigns", "deliveries"],
@@ -64,14 +64,19 @@ export {
   MAX_SUBJECT_LENGTH,
   RESERVED_HEADERS,
 } from "./address.js";
-export { TRANSACTIONAL_KIND } from "./contract.js";
+export { HALTING_ERROR_CODES, TRANSACTIONAL_KIND } from "./contract.js";
 export type {
+  CampaignRecipient,
+  CampaignRecipientFilter,
+  LegacyUnsubscribe,
   MailingErrorCode,
   MailProvider,
   OnUnsubscribedHook,
   OutgoingMail,
+  ProviderFailureStatus,
   ProviderMessage,
   ProviderOutcome,
+  SendMailFailure,
   SendMailOptions,
   SendMailResult,
   SentMail,
@@ -80,6 +85,6 @@ export type {
   UnsubscribeEvent,
 } from "./contract.js";
 export { getMailingErrorMessage, mailingMessages, type MailingMessages } from "./messages/index.js";
-export { DEFAULT_TIMEOUT_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";
+export { DEFAULT_STALE_CLAIM_MS, DEFAULT_TIMEOUT_MS, DEFAULT_UNCERTAIN_CLAIM_MS, type MailingOptions, type MailingOptionsInput } from "./options.js";
 export { resend, RESEND_API_KEY_ENV, RESEND_ENDPOINT, type ResendOptions } from "./providers/resend.js";
 export { campaigns, deliveries, mailingSchema, suppressions, type DeliveryStatus } from "./schema.js";

package/src/messages/en.ts

@@ -5,6 +5,8 @@ export const en = {
       rejected: "The mail service refused this message.",
       unavailable: "The mail service is not answering. Try again in a moment.",
       suppressed: "This address unsubscribed from these emails, so nothing was sent.",
+      provider_refused: "The mail service refused our account, so nothing was sent. We need to fix it on our side.",
+      quota_exceeded: "We reached our sending limit for now. Try again later.",
     },
   },
   footer: {

package/src/messages/pl.ts

@@ -8,6 +8,8 @@ export const pl: typeof en = {
       rejected: "Usługa pocztowa odrzuciła tę wiadomość.",
       unavailable: "Usługa pocztowa nie odpowiada. Spróbuj ponownie za chwilę.",
       suppressed: "Ten adres wypisał się z takich wiadomości, więc nic nie wysłano.",
+      provider_refused: "Usługa pocztowa odrzuciła nasze konto, więc nic nie wysłano. Musimy to naprawić po naszej stronie.",
+      quota_exceeded: "Wyczerpaliśmy na razie limit wysyłki. Spróbuj ponownie później.",
     },
   },
   footer: {

package/src/next/actions.ts

@@ -9,16 +9,16 @@ import { getSoftureConfig } from "@softure-ai/core/next";
 import { redirect } from "next/navigation";
 import { getMailingRoutes } from "../server/options.js";
 import { unsubscribe } from "../server/suppressions.js";
-import { RECIPIENT_PARAM, readUnsubscribeToken, SIGNATURE_PARAM } from "../server/unsubscribe-link.js";
+import { getUnsubscribeLinkParams, readUnsubscribeLink } from "../server/unsubscribe-link.js";
 import { getMailingContext } from "./context.js";
 import { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";
 
 export async function unsubscribeAction(formData: FormData): Promise<void> {
   const config = getSoftureConfig();
-  const token = readUnsubscribeToken(formData);
+  const link = readUnsubscribeLink(formData, config);
   let status: UnsubscribeStatus;
   try {
-    const result = await unsubscribe(await getMailingContext(config), token, "page");
+    const result = await unsubscribe(await getMailingContext(config), link, "page");
     status = result.ok ? "done" : "invalid";
   } catch (error) {
     // The label names the kind of failure, never its text: that can carry the link's values.
@@ -26,10 +26,9 @@ export async function unsubscribeAction(formData: FormData): Promise<void> {
     status = "failed";
   }
   const query = new URLSearchParams({ [UNSUBSCRIBE_STATUS_PARAM]: status });
-  if (status === "failed" && token !== null) {
+  if (status === "failed" && link !== null) {
     // The form comes back with the same link, so the person can try again.
-    query.set(RECIPIENT_PARAM, token.recipientKey);
-    query.set(SIGNATURE_PARAM, token.signature);
+    for (const [name, value] of Object.entries(getUnsubscribeLinkParams(link))) query.set(name, value);
   }
   redirect(`${getMailingRoutes(config).unsubscribe}?${query.toString()}`);
 }