@softure-ai/mailing 0.1.8 → 0.1.10

package/dist/server/unsubscribe-link.js

@@ -74,8 +74,9 @@ 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.
+ * `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, config) {
     if (params.get(RECIPIENT_PARAM) !== null && params.get(RECIPIENT_PARAM) !== undefined) {
@@ -86,12 +87,20 @@ export function readUnsubscribeLink(params, config) {
     if (legacy === undefined)
         return null;
     const values = {};
-    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 };
 }
 /** The query (or form) parameters that carry `link`, to send it back to the page. */

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/dist/server/validate-mail.d.ts

@@ -4,6 +4,8 @@ export interface ValidMail {
     readonly text: string;
     readonly html: string | null;
     readonly headers: Readonly<Record<string, string>>;
+    /** The mail's own reply-to; null to use the configured one. */
+    readonly replyTo: string | null;
     /** `transactional` or a list kind. */
     readonly kind: string;
     readonly idempotencyKey: string | null;
@@ -17,7 +19,7 @@ export type MailValidation = {
 };
 /**
  * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
- * `html`, `headers`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ * `html`, `headers`, `replyTo`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
  */
 export declare function validateMail(mail: unknown, options?: unknown): MailValidation;
 //# sourceMappingURL=validate-mail.d.ts.map

package/dist/server/validate-mail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-mail.d.ts","sourceRoot":"","sources":["../../src/server/validate-mail.ts"],"names":[],"mappings":"AAqCA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3I;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,OAAY,GAAG,cAAc,CAajF"}
+{"version":3,"file":"validate-mail.d.ts","sourceRoot":"","sources":["../../src/server/validate-mail.ts"],"names":[],"mappings":"AAsCA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3I;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,GAAE,OAAY,GAAG,cAAc,CAajF"}

package/dist/server/validate-mail.js

@@ -21,6 +21,7 @@ const mailSchema = z.object({
         .refine((html) => html.trim() !== "")
         .optional(),
     headers: headersSchema.optional(),
+    replyTo: z.string().trim().refine(isSingleAddress).optional(),
     kind: z.string().refine(isMailKind).default(TRANSACTIONAL_KIND),
 }).superRefine((mail, context) => {
     // The module writes these two on list mail; a second, unsigned copy would confuse clients.
@@ -33,7 +34,7 @@ const optionsSchema = z.object({
 });
 /**
  * Checks one mail and its send options. `fields` lists what failed (`to`, `subject`, `text`,
- * `html`, `headers`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
+ * `html`, `headers`, `replyTo`, `kind`, `idempotencyKey`, or `mail` when the input is not an object).
  */
 export function validateMail(mail, options = {}) {
     const parsedMail = mailSchema.safeParse(mail);
@@ -43,10 +44,10 @@ export function validateMail(mail, options = {}) {
         const fields = new Set(issues.map((issue) => (issue.path.length === 0 ? "mail" : String(issue.path[0]))));
         return { ok: false, fields: [...fields] };
     }
-    const { to, subject, text, html, headers, kind } = parsedMail.data;
+    const { to, subject, text, html, headers, replyTo, kind } = parsedMail.data;
     return {
         ok: true,
-        value: { to, subject, text, html: html ?? null, headers: headers ?? {}, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
+        value: { to, subject, text, html: html ?? null, headers: headers ?? {}, replyTo: replyTo ?? null, kind, idempotencyKey: parsedOptions.data.idempotencyKey ?? null },
     };
 }
 //# sourceMappingURL=validate-mail.js.map

package/dist/server/validate-mail.js.map

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

package/migrations/0004_allow_imported_deliveries.sql

@@ -0,0 +1,20 @@
+-- Lets an app seed the ledger with the deliveries it made before it adopted the module (importDeliveries), so the
+-- first deliverOnce or campaign run skips them. Its history rarely kept the provider's message id, so a `sent` row
+-- needs one only when the module sent it; an imported row is marked by imported_at. A row the module did not close
+-- still never has a message id.
+-- Rollback: DELETE FROM mailing.deliveries WHERE imported_at IS NOT NULL AND provider_message_id IS NULL;
+--   ALTER TABLE mailing.deliveries DROP CONSTRAINT deliveries_message_id_check;
+--   ALTER TABLE mailing.deliveries DROP CONSTRAINT deliveries_sent_message_id_check;
+--   ALTER TABLE mailing.deliveries DROP COLUMN imported_at;
+--   ALTER TABLE mailing.deliveries ADD CONSTRAINT deliveries_check1 CHECK ((status = 'sent') = (provider_message_id IS NOT NULL));
+--   DELETE FROM softure.migrations WHERE module = 'mailing' AND version = 4;
+
+-- When the row was imported; null for a delivery the module made. Only a closed row can be imported.
+ALTER TABLE deliveries ADD COLUMN imported_at timestamptz
+  CONSTRAINT deliveries_imported_at_check CHECK (imported_at IS NULL OR status IN ('sent', 'rejected'));
+
+-- Was: CHECK ((status = 'sent') = (provider_message_id IS NOT NULL)), unnamed in 0002.
+ALTER TABLE deliveries DROP CONSTRAINT deliveries_check1;
+ALTER TABLE deliveries ADD CONSTRAINT deliveries_message_id_check CHECK (provider_message_id IS NULL OR status = 'sent');
+ALTER TABLE deliveries ADD CONSTRAINT deliveries_sent_message_id_check
+  CHECK (status <> 'sent' OR provider_message_id IS NOT NULL OR imported_at IS NOT NULL);

package/module.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/mailing",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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

@@ -1,6 +1,6 @@
-// `softure-mail`: sends a campaign from a content file and checks the sender domain's DNS. The app
-// passes its validated config, so the same function serves the bin and an app script that a
-// bundler packs for a container:
+// `softure-mail`: sends a campaign from a content file, imports an app's delivery history into the
+// ledger and checks the sender domain's DNS. The app passes its validated config, so the same
+// function serves the bin and an app script that a bundler packs for a container:
 //
 //   // scripts/mail.ts
 //   import { runMailCli } from "@softure-ai/mailing/cli";
@@ -10,11 +10,13 @@ import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { systemClock, type SoftureConfig, type SoftureDatabaseConfig } from "@softure-ai/core";
+import { z } from "zod";
 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 { listConfiguredCampaignRecipients, planCampaign, sendCampaign, type CampaignSummary } from "../server/campaigns.js";
 import type { DeliveryContext, HaltingErrorCode } from "../server/deliveries.js";
 import { checkSenderDns, getSenderDomain, resendReturnPath, type DmarcAlignment, type DmarcExpectation, type DmarcPolicy, type DnsCheck, type ResolveCname, type ResolveMx, type ResolveTxt, type ReturnPathHost } from "../server/dns.js";
+import { checkImportedDeliveries, importDeliveries, type ImportedDelivery, type ImportProblem } from "../server/import-deliveries.js";
 import { getMailingOptions } from "../server/options.js";
 import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV, type Env } from "../server/unsubscribe-link.js";
 
@@ -24,7 +26,7 @@ export interface CliOutput {
 }
 
 export interface RunMailCliOptions {
-  /** The app's config. Needed by `campaign`, and by `dns` without `--domain`. */
+  /** The app's config. Needed by `campaign` and `import`, and by `dns` without `--domain`. */
   readonly config?: SoftureConfig;
   /** The arguments after the executable, e.g. `["campaign", "launch.md", "--recipients", "list.txt"]`. */
   readonly argv: readonly string[];
@@ -38,6 +40,8 @@ export interface RunMailCliOptions {
   readonly resolveCname?: ResolveCname;
   readonly sleep?: (ms: number) => Promise<void>;
   readonly env?: Env;
+  /** Reads all of standard input, for a file given as `-`. Default: `process.stdin`. */
+  readonly readStdin?: () => Promise<string>;
 }
 
 export const EXIT_OK = 0;
@@ -48,20 +52,30 @@ 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>] [--resend-uncertain]
+  softure-mail campaign <content-file> [--recipients <file>] [--dry-run] [--pause-ms <ms>] [--resend-uncertain]
+  softure-mail import <history-file> [--dry-run]
   softure-mail dns [--domain <domain>] [--dkim-selector <name>]... [--spf-host <host>]...
                    [--dmarc-policy <p>] [--dmarc-sp <p>] [--dmarc-adkim <a>] [--dmarc-aspf <a>]
                    [--reply-to <address>] [--return-path <host>]... [--resend-return-path]
 
 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. A refused
-          API key or a spent quota stops the run; the rest go out on the next one.
+          once each. Without --recipients, the recipients come from listCampaignRecipients in
+          the mailing options. 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.
+  --recipients <file>  the recipients, one address per line
   --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)
 
+import    Writes deliveries the app made before it adopted the module into the ledger, so
+          later sends skip them. <history-file> holds one JSON object per line: scope,
+          address, status (sent or rejected), finishedAt, and optional providerMessageId,
+          reason, kind. Rows already in the ledger are left as they are; any invalid row
+          stops the import before anything is written.
+  --dry-run            check the file and change nothing
+
 dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain of "from").
   --domain <domain>       check this domain instead
   --dkim-selector <name>  DKIM selector to look up (default resend; repeatable)
@@ -77,9 +91,12 @@ dns       Checks SPF, DKIM and DMARC for the sender domain (default: the domain
   --return-path <host>    a return-path host that must be a CNAME or have MX (repeatable)
   --resend-return-path    check Resend's send.<domain> and rsend.<domain> CNAMEs
 
-Options for both:
+Options for all:
   --config <file>    the app's softure.config file (bin only)
-  --help             show this help`;
+  --help             show this help
+
+A file given as - is read from standard input (one of them per command), e.g.
+  docker compose exec -T app npx softure-mail campaign - < launch.md`;
 
 const consoleOutput: CliOutput = {
   log: (line) => console.log(line),
@@ -91,11 +108,13 @@ type Command =
   | {
       readonly kind: "campaign";
       readonly contentFile: string;
-      readonly recipientsFile: string;
+      /** `null`: the module's `listCampaignRecipients`. */
+      readonly recipientsFile: string | null;
       readonly dryRun: boolean;
       readonly pauseMs: number;
       readonly resendUncertain: boolean;
     }
+  | { readonly kind: "import"; readonly historyFile: string; readonly dryRun: boolean }
   | {
       readonly kind: "dns";
       readonly domain: string | undefined;
@@ -109,6 +128,9 @@ type Command =
 
 const DMARC_POLICIES: readonly DmarcPolicy[] = ["quarantine", "reject"];
 const DMARC_ALIGNMENTS: readonly DmarcAlignment[] = ["r", "s"];
+/** A file name that means standard input. */
+const STDIN = "-";
+const CAMPAIGN_ONLY_OPTIONS = ["recipients", "pause-ms", "resend-uncertain"] as const;
 const DNS_ONLY_OPTIONS = ["domain", "dkim-selector", "spf-host", "dmarc-policy", "dmarc-sp", "dmarc-adkim", "dmarc-aspf", "reply-to", "return-path", "resend-return-path"] as const;
 
 /** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
@@ -128,14 +150,16 @@ export async function runMailCli(options: RunMailCliOptions): Promise<number> {
       return runDns(command, options, output);
     case "campaign":
       return runCampaign(command, options, output);
+    case "import":
+      return runImport(command, options, output);
   }
 }
 
 function parseCommand(argv: readonly string[]): Command | string {
   const [name, ...rest] = argv;
-  if (name === undefined) return "missing command; use campaign or dns";
+  if (name === undefined) return "missing command; use campaign, import or dns";
   if (name === "--help") return { kind: "help" };
-  if (name !== "campaign" && name !== "dns") return `unknown command "${name}"; use campaign or dns`;
+  if (name !== "campaign" && name !== "import" && name !== "dns") return `unknown command "${name}"; use campaign, import or dns`;
 
   let parsed: ReturnType<typeof parseCommandArgs>;
   try {
@@ -147,7 +171,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", "resend-uncertain"] as const).filter((option) => values[option] !== undefined);
+    const misplaced = ([...CAMPAIGN_ONLY_OPTIONS, "dry-run"] 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(" ")}"`;
     const expectDmarc = parseDmarcExpectation(values);
@@ -164,15 +188,24 @@ function parseCommand(argv: readonly string[]): Command | string {
     };
   }
 
+  if (name === "import") {
+    const misplaced = [...CAMPAIGN_ONLY_OPTIONS, ...DNS_ONLY_OPTIONS].filter((option) => values[option] !== undefined);
+    if (misplaced.length > 0) return `import does not take --${misplaced.join(", --")}`;
+    const [historyFile, ...extra] = positionals;
+    if (historyFile === undefined) return "import needs a history file (- for standard input)";
+    if (extra.length > 0) return `import takes one history file, got also "${extra.join(" ")}"`;
+    return { kind: "import", historyFile, dryRun: values["dry-run"] === true };
+  }
+
   const misplaced = DNS_ONLY_OPTIONS.filter((option) => values[option] !== undefined);
   if (misplaced.length > 0) return `campaign does not take --${misplaced.join(", --")}`;
   const [contentFile, ...extra] = positionals;
   if (contentFile === undefined) return "campaign needs a content file";
   if (extra.length > 0) return `campaign takes one content file, got also "${extra.join(" ")}"`;
-  if (values.recipients === undefined) return "campaign needs --recipients <file>";
+  if (contentFile === STDIN && values.recipients === STDIN) return "campaign can read only one of the content file and --recipients from standard input";
   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, resendUncertain: values["resend-uncertain"] === true };
+  return { kind: "campaign", contentFile, recipientsFile: values.recipients ?? null, dryRun: values["dry-run"] === true, pauseMs, resendUncertain: values["resend-uncertain"] === true };
 }
 
 function parseCommandArgs(args: readonly string[]) {
@@ -285,9 +318,19 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
     output.error("softure-mail campaign: needs the app's config");
     return EXIT_FAILED;
   }
-  const loaded = await loadCampaign(resolve(cwd, command.contentFile), resolve(cwd, command.recipientsFile));
-  if (typeof loaded === "string") {
-    output.error(`softure-mail campaign: ${loaded}`);
+  const input = createInputReader(cwd, options.readStdin ?? readProcessStdin);
+  const content = await loadCampaignContent(command.contentFile, input);
+  if (typeof content === "string") {
+    output.error(`softure-mail campaign: ${content}`);
+    return EXIT_FAILED;
+  }
+  const listed = command.recipientsFile === null ? null : await loadRecipientFile(command.recipientsFile, input);
+  if (typeof listed === "string") {
+    output.error(`softure-mail campaign: ${listed}`);
+    return EXIT_FAILED;
+  }
+  if (listed === null && getMailingOptions(config).listCampaignRecipients === undefined) {
+    output.error("softure-mail campaign: pass --recipients <file>, or set listCampaignRecipients in the mailing options");
     return EXIT_FAILED;
   }
   if (!command.dryRun && readUnsubscribeSecrets(options.env ?? process.env).current === null) {
@@ -308,6 +351,7 @@ async function runCampaign(command: Extract<Command, { kind: "campaign" }>, opti
   }
   const ctx: DeliveryContext = { db: opened.handle.db, clock: systemClock, config };
   try {
+    const loaded: LoadedCampaign = { campaign: content, recipients: listed ?? (await collectRecipients(ctx, content)) };
     return command.dryRun
       ? await reportPlan(ctx, loaded, command.resendUncertain, output)
       : await reportSend(ctx, loaded, { pauseMs: command.pauseMs, sleep: options.sleep, retakeUncertain: command.resendUncertain }, output);
@@ -325,22 +369,152 @@ interface LoadedCampaign {
   readonly recipients: readonly string[];
 }
 
-async function loadCampaign(contentPath: string, recipientsPath: string): Promise<LoadedCampaign | string> {
-  const source = await readText(contentPath);
-  if (source === null) return `cannot read the content file ${contentPath}`;
-  const parsed = parseCampaignFile(source);
-  if (!parsed.ok) return `${contentPath} is not a campaign:\n  ${parsed.problems.join("\n  ")}`;
+/** Reads a named file, or standard input for `-`; `name` is what messages call it. */
+interface InputReader {
+  readonly read: (file: string) => Promise<{ readonly text: string | null; readonly name: string; readonly dir: string }>;
+}
+
+function createInputReader(cwd: string, readStdin: () => Promise<string>): InputReader {
+  return {
+    read: async (file) => {
+      if (file === STDIN) return { text: await readStdin(), name: "standard input", dir: cwd };
+      const path = resolve(cwd, file);
+      return { text: await readText(path), name: path, dir: dirname(path) };
+    },
+  };
+}
+
+async function loadCampaignContent(file: string, input: InputReader): Promise<CampaignContent | string> {
+  const source = await input.read(file);
+  if (source.text === null) return `cannot read the content file ${source.name}`;
+  const parsed = parseCampaignFile(source.text);
+  if (!parsed.ok) return `${source.name} is not a campaign:\n  ${parsed.problems.join("\n  ")}`;
   const { htmlPath, ...content } = parsed.value;
   let html: string | null = null;
   if (htmlPath !== null) {
-    const htmlFile = resolve(dirname(contentPath), htmlPath);
+    // Next to the content file; for standard input, the working directory.
+    const htmlFile = resolve(source.dir, htmlPath);
     html = await readText(htmlFile);
     if (html === null) return `cannot read the HTML body ${htmlFile}`;
     if (html.trim() === "") return `the HTML body ${htmlFile} is empty`;
   }
-  const list = await readText(recipientsPath);
-  if (list === null) return `cannot read the recipients file ${recipientsPath}`;
-  return { campaign: { ...content, html }, recipients: parseRecipientList(list) };
+  return { ...content, html };
+}
+
+async function loadRecipientFile(file: string, input: InputReader): Promise<readonly string[] | string> {
+  const list = await input.read(file);
+  if (list.text === null) return `cannot read the recipients file ${list.name}`;
+  return parseRecipientList(list.text);
+}
+
+/** The recipients from `listCampaignRecipients`, which the caller checked is set. */
+async function collectRecipients(ctx: DeliveryContext, campaign: CampaignContent): Promise<readonly string[]> {
+  const recipients: string[] = [];
+  const source = await listConfiguredCampaignRecipients(ctx, campaign);
+  if (source === null) return recipients;
+  for await (const address of source) recipients.push(address);
+  return recipients;
+}
+
+/** One line of a history file. Unknown keys are refused, so a typo does not drop a field. */
+const historyRowSchema = z.strictObject({
+  scope: z.string(),
+  address: z.string(),
+  status: z.enum(["sent", "rejected"]),
+  finishedAt: z.string(),
+  providerMessageId: z.string().optional(),
+  reason: z.enum(["mailing.invalid_input", "mailing.rejected", "mailing.unavailable", "mailing.suppressed"]).optional(),
+  kind: z.string().optional(),
+});
+
+async function runImport(command: Extract<Command, { kind: "import" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
+  const config = options.config;
+  if (config === undefined) {
+    output.error("softure-mail import: needs the app's config");
+    return EXIT_FAILED;
+  }
+  const source = await createInputReader(options.cwd ?? process.cwd(), options.readStdin ?? readProcessStdin).read(command.historyFile);
+  if (source.text === null) {
+    output.error(`softure-mail import: cannot read the history file ${source.name}`);
+    return EXIT_FAILED;
+  }
+  const parsed = parseHistory(source.text);
+  if (parsed.problems.length > 0) return reportImportProblems(parsed.problems, output);
+  const rows = parsed.rows.map((row) => row.delivery);
+  const lineOf = (problem: ImportProblem) => parsed.rows[problem.index]?.line ?? 0;
+
+  // Checked before the database is opened, so a bad file costs no connection.
+  const checked = checkImportedDeliveries({ clock: systemClock }, rows);
+  if (!checked.ok) return reportImportProblems(checked.problems.map((problem) => ({ line: lineOf(problem), problem: problem.problem })), output);
+  if (command.dryRun) {
+    output.log(`import, dry run: nothing written; rows ${String(rows.length)}, duplicates ${String(checked.value.duplicates)}`);
+    return EXIT_OK;
+  }
+  if (config.database === null) {
+    output.error("softure-mail import: the config has no database; set database.url in softure.config");
+    return EXIT_FAILED;
+  }
+  let opened: CommandDatabase;
+  try {
+    opened = await openDatabase(config.database, options.openDatabase);
+  } catch (error) {
+    output.error(`softure-mail import: ${describeError(error)}`);
+    return EXIT_FAILED;
+  }
+  try {
+    const result = await importDeliveries({ db: opened.handle.db, clock: systemClock, config }, rows);
+    if (!result.ok) return reportImportProblems(result.problems.map((problem) => ({ line: lineOf(problem), problem: problem.problem })), output);
+    const summary = result.value;
+    output.log(`import: rows ${String(summary.rows)}, imported ${String(summary.imported)}, already present ${String(summary.alreadyPresent)}, duplicates ${String(summary.duplicates)}`);
+    return EXIT_OK;
+  } catch (error) {
+    output.error(`softure-mail import: ${describeError(error)} (did softure migrate run?)`);
+    return EXIT_FAILED;
+  } finally {
+    await opened.close();
+  }
+}
+
+interface LineProblem {
+  readonly line: number;
+  readonly problem: string;
+}
+
+/** The history file's rows with their line numbers; problems name lines and fields, never values. */
+function parseHistory(text: string): { readonly rows: readonly { readonly line: number; readonly delivery: ImportedDelivery }[]; readonly problems: readonly LineProblem[] } {
+  const rows: { line: number; delivery: ImportedDelivery }[] = [];
+  const problems: LineProblem[] = [];
+  text.split(/\r?\n/).forEach((source, index) => {
+    const line = index + 1;
+    if (source.trim() === "") return;
+    let value: unknown;
+    try {
+      value = JSON.parse(source);
+    } catch {
+      problems.push({ line, problem: "not a JSON object" });
+      return;
+    }
+    const parsed = historyRowSchema.safeParse(value);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        const field = issue.path.length === 0 ? "row" : issue.path.join(".");
+        problems.push({ line, problem: issue.code === "unrecognized_keys" ? `unknown field(s) ${issue.keys.join(", ")}` : `${field}: ${issue.message}` });
+      }
+      return;
+    }
+    const { providerMessageId, reason, kind, ...required } = parsed.data;
+    rows.push({
+      line,
+      delivery: { ...required, ...(providerMessageId === undefined ? {} : { providerMessageId }), ...(reason === undefined ? {} : { reason }), ...(kind === undefined ? {} : { kind }) },
+    });
+  });
+  return { rows, problems };
+}
+
+function reportImportProblems(problems: readonly LineProblem[], output: CliOutput): number {
+  output.error(`softure-mail import: nothing written, ${String(problems.length)} problem(s):`);
+  for (const { line, problem } of problems) output.error(`  line ${String(line)}: ${problem}`);
+  return EXIT_FAILED;
 }
 
 async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, retakeUncertain: boolean, output: CliOutput): Promise<number> {
@@ -433,6 +607,12 @@ async function openDatabase(database: SoftureDatabaseConfig, open: ((url: string
   return { handle, close: handle.close };
 }
 
+async function readProcessStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer));
+  return Buffer.concat(chunks).toString("utf8");
+}
+
 async function readText(path: string): Promise<string | null> {
   try {
     return await readFile(path, "utf8");

package/src/contract.ts

@@ -32,11 +32,18 @@ export const TRANSACTIONAL_KIND = "transactional";
 /** How an opt-out arrived: a mail client's one-click POST, the page's button, or an operator. */
 export type SuppressionSource = "one-click" | "page" | "operator";
 
-/** What `onUnsubscribed` receives: who opted out (never the address) and how. */
+/**
+ * The link an unsubscribe came through, once verified: the module's signed link, or a legacy link with the values
+ * the app's `verify` accepted (only the names the link carried), so a hook can find the row that link named.
+ */
+export type VerifiedUnsubscribeLink = { readonly scheme: "signed" } | { readonly scheme: "legacy"; readonly values: Readonly<Record<string, string>> };
+
+/** What `onUnsubscribed` receives: who opted out (never the address), how, and through which link. */
 export interface UnsubscribeEvent {
   /** The recipient key of the link: privacy's email key of the same address (`getEmailKey`). */
   readonly recipientKey: string;
   readonly source: Exclude<SuppressionSource, "operator">;
+  readonly link: VerifiedUnsubscribeLink;
 }
 
 /**
@@ -61,14 +68,32 @@ export interface CampaignRecipient {
  */
 export type CampaignRecipientFilter = (recipient: CampaignRecipient, ctx: ModuleContext<Queryable>) => Promise<boolean>;
 
+/**
+ * Lists the addresses a campaign goes to, from the app's own data (e.g. the people who opted in to its kind), so a
+ * campaign can run where the database is without a recipients file. Duplicates are fine; `filterCampaignRecipient`
+ * and the suppression list still apply. A throw stops the campaign. Set in `mailing({ listCampaignRecipients })`.
+ */
+export type CampaignRecipientSource = (
+  campaign: { readonly id: string; readonly kind: string },
+  ctx: ModuleContext<Queryable>,
+) => Iterable<string> | AsyncIterable<string> | Promise<Iterable<string>>;
+
+/**
+ * The query names of a legacy link. An array lists names the link must all carry. The object form adds names it
+ * may carry: a link is legacy when it has every `required` name, and the `optional` ones it has go to `verify` too.
+ * At most 8 names in all, none repeated, never `r` or `status`.
+ */
+export type LegacyUnsubscribeParams = readonly string[] | { readonly required: readonly string[]; readonly optional?: readonly string[] };
+
 /**
  * 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.
+ * such a link; `verify` receives the values the link carried (every required name, the optional names that are
+ * present and non-empty, 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 params: LegacyUnsubscribeParams;
   readonly verify: (values: Readonly<Record<string, string>>, ctx: ModuleContext<Queryable>) => Promise<string | null>;
 }
 
@@ -87,6 +112,11 @@ export interface OutgoingMail {
    * the body's encoding: reserved names are refused (`RESERVED_HEADERS`).
    */
   readonly headers?: Readonly<Record<string, string>>;
+  /**
+   * Where replies to this mail go, exactly one address (e.g. the buyer of a request mailed to the
+   * operator). Replaces `mailing({ replyTo })` for this mail; without it the configured one is used.
+   */
+  readonly replyTo?: string;
   /**
    * `transactional` (the default) for mail the recipient needs whatever they unsubscribed from:
    * password resets, receipts, account notices. Any other kebab-case name (e.g. `newsletter`) is
@@ -118,7 +148,7 @@ export type SendMailFailure = Err<MailingErrorCode> & { readonly httpStatus?: nu
 
 export type SendMailResult = Ok<SentMail> | SendMailFailure;
 
-/** What a provider receives: a validated mail with the sender and reply-to from the configuration. */
+/** What a provider receives: a validated mail with the sender from the configuration and the mail's or the configured reply-to. */
 export interface ProviderMessage {
   readonly from: string;
   readonly to: string;