@softure-ai/mailing 0.0.0-stage → 0.1.6

package/src/cli/run.ts

@@ -0,0 +1,317 @@
+// `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:
+//
+//   // scripts/mail.ts
+//   import { runMailCli } from "@softure-ai/mailing/cli";
+//   import config from "../softure.config";
+//   process.exitCode = await runMailCli({ config, argv: process.argv.slice(2) });
+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 { 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 { 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";
+
+export interface CliOutput {
+  readonly log: (line: string) => void;
+  readonly error: (line: string) => void;
+}
+
+export interface RunMailCliOptions {
+  /** The app's config. Needed by `campaign`, 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[];
+  /** Relative paths resolve against it. Default: `process.cwd()`. */
+  readonly cwd?: string;
+  readonly output?: CliOutput;
+  /** Opens the campaign's database connection. Default: the config's `database.handle`, else `createDatabase(url, { max: 1 })`. */
+  readonly openDatabase?: (url: string) => Promise<DatabaseHandle>;
+  readonly resolveTxt?: ResolveTxt;
+  readonly sleep?: (ms: number) => Promise<void>;
+  readonly env?: Env;
+}
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+
+/** Pause between sends: Resend's default limit is two requests per second. */
+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 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)})
+
+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)
+  --spf-host <host>       where SPF is published (default the domain; repeatable;
+                          Resend publishes it on send.<domain>)
+
+Options for both:
+  --config <file>    the app's softure.config file (bin only)
+  --help             show this help`;
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+type Command =
+  | { readonly kind: "help" }
+  | { readonly kind: "campaign"; readonly contentFile: string; readonly recipientsFile: string; readonly dryRun: boolean; readonly pauseMs: number }
+  | { 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. */
+export async function runMailCli(options: RunMailCliOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const command = parseCommand(options.argv);
+  if (typeof command === "string") {
+    output.error(`softure-mail: ${command}`);
+    output.error(MAIL_USAGE);
+    return EXIT_USAGE;
+  }
+  switch (command.kind) {
+    case "help":
+      output.log(MAIL_USAGE);
+      return EXIT_OK;
+    case "dns":
+      return runDns(command, options, output);
+    case "campaign":
+      return runCampaign(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 === "--help") return { kind: "help" };
+  if (name !== "campaign" && name !== "dns") return `unknown command "${name}"; use campaign or dns`;
+
+  let parsed: ReturnType<typeof parseCommandArgs>;
+  try {
+    parsed = parseCommandArgs(rest);
+  } catch (error) {
+    return describeError(error);
+  }
+  const { values, positionals } = parsed;
+  if (values.help === true) return { kind: "help" };
+
+  if (name === "dns") {
+    const misplaced = (["recipients", "dry-run", "pause-ms"] 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"] };
+  }
+
+  const misplaced = (["domain", "dkim-selector", "spf-host"] as const).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>";
+  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 };
+}
+
+function parseCommandArgs(args: readonly string[]) {
+  return parseArgs({
+    args: [...args],
+    options: {
+      recipients: { type: "string" },
+      "dry-run": { type: "boolean" },
+      "pause-ms": { type: "string" },
+      domain: { type: "string" },
+      "dkim-selector": { type: "string", multiple: true },
+      "spf-host": { type: "string", multiple: true },
+      help: { type: "boolean" },
+    },
+    strict: true,
+    allowPositionals: true,
+  });
+}
+
+async function runDns(command: Extract<Command, { kind: "dns" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
+  let domain = command.domain;
+  if (domain === undefined) {
+    if (options.config === undefined) {
+      output.error("softure-mail dns: pass --domain <domain>, or run it with the app's config to check the sender's domain");
+      return EXIT_FAILED;
+    }
+    domain = getSenderDomain(getMailingOptions(options.config).from);
+  }
+  const report = await checkSenderDns(domain, {
+    ...(command.dkimSelectors === undefined ? {} : { dkimSelectors: command.dkimSelectors }),
+    ...(command.spfHosts === undefined ? {} : { spfHosts: command.spfHosts }),
+    ...(options.resolveTxt === undefined ? {} : { resolveTxt: options.resolveTxt }),
+  });
+  const checks: [string, DnsCheck][] = [
+    ["SPF", report.spf],
+    ["DKIM", report.dkim],
+    ["DMARC", report.dmarc],
+  ];
+  output.log(`sender domain ${report.domain}`);
+  for (const [name, check] of checks) {
+    const line = `${name.padEnd(6)}${check.status.padEnd(6)}${check.finding.padEnd(15)}${check.host}${check.record === null ? "" : `  ${check.record}`}`;
+    if (check.status === "fail") output.error(line);
+    else output.log(line);
+  }
+  const failed = checks.filter(([, check]) => check.status === "fail").length;
+  output.log(failed === 0 ? "receivers can authenticate mail from this domain" : `${String(failed)} check(s) failed: list mail from this domain will land in spam or be refused`);
+  return failed === 0 ? EXIT_OK : EXIT_FAILED;
+}
+
+async function runCampaign(command: Extract<Command, { kind: "campaign" }>, options: RunMailCliOptions, output: CliOutput): Promise<number> {
+  const cwd = options.cwd ?? process.cwd();
+  const config = options.config;
+  if (config === undefined) {
+    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}`);
+    return EXIT_FAILED;
+  }
+  if (!command.dryRun && readUnsubscribeSecrets(options.env ?? process.env).current === null) {
+    output.error(`softure-mail campaign: campaigns are list mail; set ${UNSUBSCRIBE_SECRET_ENV} (at least ${String(MIN_UNSUBSCRIBE_SECRET_LENGTH)} characters) to sign their unsubscribe links`);
+    return EXIT_FAILED;
+  }
+  if (config.database === null) {
+    output.error("softure-mail campaign: 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 campaign: ${describeError(error)}`);
+    return EXIT_FAILED;
+  }
+  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);
+  } 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?)`);
+    return EXIT_FAILED;
+  } finally {
+    await opened.close();
+  }
+}
+
+interface LoadedCampaign {
+  readonly campaign: CampaignContent;
+  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  ")}`;
+  const { htmlPath, ...content } = parsed.value;
+  let html: string | null = null;
+  if (htmlPath !== null) {
+    const htmlFile = resolve(dirname(contentPath), 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) };
+}
+
+async function reportPlan(ctx: DeliveryContext, loaded: LoadedCampaign, output: CliOutput): Promise<number> {
+  const plan = await planCampaign(ctx, loaded);
+  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)}`);
+  if (plan.contentChanged) {
+    output.error(`campaign ${loaded.campaign.id} was sent with other content; give this content a new id`);
+    return EXIT_FAILED;
+  }
+  return EXIT_OK;
+}
+
+async function reportSend(
+  ctx: DeliveryContext,
+  loaded: LoadedCampaign,
+  pace: { readonly pauseMs: number; readonly sleep: ((ms: number) => Promise<void>) | undefined },
+  output: CliOutput,
+): Promise<number> {
+  let handled = 0;
+  const total = loaded.recipients.length;
+  const result = await sendCampaign(ctx, loaded, {
+    pauseMs: pace.pauseMs,
+    ...(pace.sleep === undefined ? {} : { sleep: pace.sleep }),
+    onDelivery: () => {
+      handled += 1;
+      if (handled % 100 === 0) output.log(`progress ${String(handled)}/${String(total)}`);
+    },
+  });
+  if (!result.ok) {
+    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) {
+    output.error(`${String(open)} recipient(s) have no outcome yet; run the same command again later`);
+    return EXIT_FAILED;
+  }
+  return EXIT_OK;
+}
+
+function formatSummary(summary: CampaignSummary): string {
+  const rejected = Object.entries(summary.rejected).filter(([, count]) => count > 0);
+  const rejectedTotal = rejected.reduce((sum, [, count]) => sum + count, 0);
+  const reasons = rejected.length === 0 ? "" : ` (${rejected.map(([code, count]) => `${code.slice("mailing.".length)} ${String(count)}`).join(", ")})`;
+  return [
+    `recipients ${String(summary.recipients)}`,
+    `sent ${String(summary.sent)}`,
+    `rejected ${String(rejectedTotal)}${reasons}`,
+    `already done ${String(summary.done)}`,
+    `in flight ${String(summary.inFlight)}`,
+    `retry later ${String(summary.retryLater)}`,
+  ].join(", ");
+}
+
+async function openDatabase(database: SoftureDatabaseConfig, open: ((url: string) => Promise<DatabaseHandle>) | undefined): Promise<CommandDatabase> {
+  if (open === undefined) return openCommandDatabase(database, { max: 1 });
+  const handle = await open(database.url);
+  return { handle, close: handle.close };
+}
+
+async function readText(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    // The caller names the path; the error code adds nothing an operator can act on.
+    return null;
+  }
+}
+
+/**
+ * The driver's own message. Drizzle wraps it in "Failed query: <sql> params: <values>", and the
+ * values hold recipient keys, so the wrapper is dropped.
+ */
+function describeError(error: unknown): string {
+  if (!(error instanceof Error)) return String(error);
+  return error.cause instanceof Error ? error.cause.message : error.message;
+}

package/src/contract.ts

@@ -0,0 +1,108 @@
+// 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 { Queryable } from "@softure-ai/db";
+
+export type MailingErrorCode =
+  /** The mail or its options were refused before anything left the process. Fix the input; do not retry. */
+  | "mailing.invalid_input"
+  /** The provider refused the mail. Retrying the same request will not help. */
+  | "mailing.rejected"
+  /** 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";
+
+/** Why an unsubscribe link was refused: missing, malformed, or not signed by a current secret. */
+export type UnsubscribeErrorCode = "mailing.invalid_link";
+
+/** The kind of every mail that is not list mail: sent whatever the recipient unsubscribed from. */
+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. */
+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">;
+}
+
+/**
+ * Called on every verified unsubscribe, in the suppression's transaction (`ctx.db` is that
+ * transaction): a throw rolls the opt-out back and the unsubscribe fails, so the consent ledger
+ * and the suppression list never disagree. Set in `mailing({ onUnsubscribed })`.
+ */
+export type OnUnsubscribedHook = (event: UnsubscribeEvent, ctx: ModuleContext<Queryable>) => Promise<void>;
+
+/** 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`. */
+  readonly to: string;
+  /** One line, 1 to 998 characters. */
+  readonly subject: string;
+  /** The plain-text body. Required: every mail carries a text part. */
+  readonly text: string;
+  /** The HTML body, already rendered to a string. */
+  readonly html?: string;
+  /**
+   * Extra headers, for example `List-Unsubscribe`. They cannot replace the envelope, the sender or
+   * the body's encoding: reserved names are refused (`RESERVED_HEADERS`).
+   */
+  readonly headers?: Readonly<Record<string, 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
+   * list mail: it gets a signed unsubscribe link in a footer and the RFC 8058 headers, and is
+   * refused with `mailing.suppressed` for a recipient who unsubscribed. Unsubscribing covers every
+   * list kind.
+   */
+  readonly kind?: string;
+}
+
+export interface SendMailOptions {
+  /**
+   * Makes a retry safe: the provider treats requests with the same key as one mail (Resend keeps a
+   * key for 24 hours). 1 to 256 visible ASCII characters, e.g. `campaign-42:recipient-7`.
+   */
+  readonly idempotencyKey?: string;
+}
+
+/** A mail the provider accepted. */
+export interface SentMail {
+  /** The provider's message id. */
+  readonly id: string;
+  /** The provider's name, e.g. `resend`. */
+  readonly provider: string;
+}
+
+export type SendMailResult = Result<SentMail, MailingErrorCode>;
+
+/** What a provider receives: a validated mail with the sender and reply-to from the configuration. */
+export interface ProviderMessage {
+  readonly from: string;
+  readonly to: string;
+  readonly replyTo: string | null;
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly idempotencyKey: string | null;
+}
+
+/** What a provider answers. `httpStatus` is logged; the mail never is. */
+export type ProviderOutcome =
+  | { readonly status: "sent"; readonly id: string }
+  | { readonly status: "rejected"; readonly httpStatus?: number }
+  | { readonly status: "unavailable"; readonly httpStatus?: number };
+
+/**
+ * A mail service adapter. `send` should resolve with an outcome for every failure it knows; a
+ * throw reads as `unavailable`. It receives a signal that aborts at the configured timeout.
+ */
+export interface MailProvider {
+  /** A short lowercase name for logs and `SentMail.provider`. */
+  readonly name: string;
+  send(message: ProviderMessage, context: { readonly signal: AbortSignal }): Promise<ProviderOutcome>;
+}

package/src/index.ts

@@ -0,0 +1,85 @@
+// Public API of @softure-ai/mailing: the module factory for softure.config.ts, the provider
+// contract, the Resend adapter, types, messages and the tables. Sending, the suppression list, the
+// delivery ledger and campaigns are in `@softure-ai/mailing/server` (and `/next` on the registered
+// config, with the unsubscribe page and one-click route); the `softure-mail` command is in `/cli`;
+// the fake provider for tests is in `/testing`.
+import { defineModule, resolveMigrationsDir } from "@softure-ai/core";
+import { mailingMessages } from "./messages/index.js";
+import { mailingOptionsSchema } from "./options.js";
+import { checkMailingTables } from "./server/health.js";
+
+export const MODULE_ID = "mailing";
+
+/**
+ * Enables mail in `softure.config.ts`:
+ * `mailing({ from: "Plan <hello@mail.example.com>", replyTo: "support@example.com", provider: resend() })`.
+ */
+export const mailing = defineModule({
+  manifest: {
+    id: MODULE_ID,
+    version: "0.1.6",
+    dependsOn: {},
+    dbSchema: "mailing",
+    tables: ["suppressions", "campaigns", "deliveries"],
+    env: [
+      {
+        name: "RESEND_API_KEY",
+        required: false,
+        description: "API key of the resend() provider, read on every send; not needed with resend({ apiKey }) or another provider.",
+      },
+      {
+        name: "MAILING_UNSUBSCRIBE_SECRET",
+        required: false,
+        description: "Signs and verifies unsubscribe links, at least 32 characters; required to send list mail (any kind but transactional). Never change it without moving the old value to MAILING_UNSUBSCRIBE_SECRET_PREVIOUS.",
+      },
+      {
+        name: "MAILING_UNSUBSCRIBE_SECRET_PREVIOUS",
+        required: false,
+        description: "The secret before a rotation, at least 32 characters: verifies links in mail already sent, never signs.",
+      },
+    ],
+    switches: [],
+    routes: { unsubscribe: "/unsubscribe", oneClick: "/api/mailing/unsubscribe" },
+    mount: [
+      { kind: "page", path: "app/unsubscribe/page.tsx", export: "UnsubscribePage" },
+      { kind: "route-handler", path: "app/api/mailing/unsubscribe/route.ts", export: "postUnsubscribeRoute" },
+      { kind: "route-handler", path: "app/api/mailing/unsubscribe/route.ts", export: "getUnsubscribeRoute" },
+    ],
+    privacy: { exports: false, deletes: false },
+  },
+  messages: mailingMessages,
+  options: mailingOptionsSchema,
+  migrations: { dir: resolveMigrationsDir(import.meta.url, "../migrations/") },
+  health: checkMailingTables,
+});
+
+export {
+  isMailbox,
+  isMailKind,
+  isSingleAddress,
+  LIST_MAIL_HEADERS,
+  MAX_ADDRESS_LENGTH,
+  MAX_IDEMPOTENCY_KEY_LENGTH,
+  MAX_MAIL_KIND_LENGTH,
+  MAX_SUBJECT_LENGTH,
+  RESERVED_HEADERS,
+} from "./address.js";
+export { TRANSACTIONAL_KIND } from "./contract.js";
+export type {
+  MailingErrorCode,
+  MailProvider,
+  OnUnsubscribedHook,
+  OutgoingMail,
+  ProviderMessage,
+  ProviderOutcome,
+  SendMailOptions,
+  SendMailResult,
+  SentMail,
+  SuppressionSource,
+  UnsubscribeErrorCode,
+  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 { 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

@@ -0,0 +1,25 @@
+export const en = {
+  errors: {
+    mailing: {
+      invalid_input: "This message cannot be sent. Check the address and try again.",
+      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.",
+    },
+  },
+  footer: {
+    text: "Don't want these emails? Unsubscribe here:",
+    htmlLead: "Don't want these emails?",
+    htmlLink: "Unsubscribe",
+  },
+  unsubscribe: {
+    title: "Unsubscribe",
+    lead: "You will stop getting these emails from us. Mail about your account, such as password resets, still arrives.",
+    submit: "Unsubscribe me",
+    doneTitle: "You are unsubscribed",
+    doneBody: "We will not send you these emails any more.",
+    invalidTitle: "This link does not work",
+    invalidBody: "Open the link from the email again, the whole of it. If it still fails, reply to the email and ask us to stop.",
+    failed: "We could not save that. Try again in a moment.",
+  },
+};

package/src/messages/index.ts

@@ -0,0 +1,15 @@
+import type { MailingErrorCode } from "../contract.js";
+import { en } from "./en.js";
+import { pl } from "./pl.js";
+
+/** Complete default dictionaries; apps pass partial overrides per locale. */
+export const mailingMessages = { en, pl };
+
+export type MailingMessages = typeof en;
+
+/** The copy for a mailing error code; a code the dictionary does not know reads as `unavailable`. */
+export function getMailingErrorMessage(messages: MailingMessages, code: MailingErrorCode): string {
+  const group: Readonly<Record<string, string>> = messages.errors.mailing;
+  const name = code.slice("mailing.".length);
+  return (Object.hasOwn(group, name) ? group[name] : undefined) ?? messages.errors.mailing.unavailable;
+}

package/src/messages/pl.ts

@@ -0,0 +1,28 @@
+import type { en } from "./en.js";
+
+// Polish copy lives only in message dictionaries; the language gate exempts `messages/` folders.
+export const pl: typeof en = {
+  errors: {
+    mailing: {
+      invalid_input: "Tej wiadomości nie da się wysłać. Sprawdź adres i spróbuj ponownie.",
+      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.",
+    },
+  },
+  footer: {
+    text: "Nie chcesz więcej takich wiadomości? Wypisz się tutaj:",
+    htmlLead: "Nie chcesz więcej takich wiadomości?",
+    htmlLink: "Wypisz się",
+  },
+  unsubscribe: {
+    title: "Wypisanie",
+    lead: "Przestaniesz dostawać od nas takie wiadomości. Poczta o Twoim koncie, na przykład reset hasła, nadal będzie przychodzić.",
+    submit: "Wypisz mnie",
+    doneTitle: "Wypisano",
+    doneBody: "Nie wyślemy Ci już takich wiadomości.",
+    invalidTitle: "Ten odnośnik nie działa",
+    invalidBody: "Otwórz jeszcze raz odnośnik z wiadomości, w całości. Jeśli dalej nie działa, odpisz na wiadomość i poproś o wypisanie.",
+    failed: "Nie udało się tego zapisać. Spróbuj ponownie za chwilę.",
+  },
+};

package/src/next/actions.ts

@@ -0,0 +1,35 @@
+"use server";
+
+// The unsubscribe page's server action. It takes the signed link from the form (the same values
+// the page got in its URL), records the opt-out and redirects to the page's outcome. No session is
+// involved: the signature is the authorization. Next refuses an action whose Origin does not match
+// the host.
+import { errorLogLabel } from "@softure-ai/core";
+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 { 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);
+  let status: UnsubscribeStatus;
+  try {
+    const result = await unsubscribe(await getMailingContext(config), token, "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.
+    console.error(`@softure-ai/mailing: unsubscribe failed: ${errorLogLabel(error)}`);
+    status = "failed";
+  }
+  const query = new URLSearchParams({ [UNSUBSCRIBE_STATUS_PARAM]: status });
+  if (status === "failed" && token !== 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);
+  }
+  redirect(`${getMailingRoutes(config).unsubscribe}?${query.toString()}`);
+}

package/src/next/context.ts

@@ -0,0 +1,15 @@
+// What the adapter hands the server functions: the registered config, the process-wide database
+// handle and the wall clock.
+import { systemClock, type SoftureConfig } from "@softure-ai/core";
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { getConfiguredDatabase } from "@softure-ai/db";
+import type { SuppressionContext } from "../server/suppressions.js";
+
+export async function getMailingContext(config: SoftureConfig = getSoftureConfig()): Promise<SuppressionContext> {
+  if (config.database === null) {
+    // Unreachable for a validated config: the module has a database schema.
+    throw new Error("@softure-ai/mailing: softure.config.ts has no database; mailing needs one");
+  }
+  const { db } = await getConfiguredDatabase(config.database);
+  return { db, clock: systemClock, config };
+}

package/src/next/deliver-once.ts

@@ -0,0 +1,10 @@
+// `deliverOnce` on the app's registered configuration and the shared database, for server actions
+// and route handlers that send a mail at most once (a welcome mail, a lifecycle notice).
+import type { Delivery, DeliverOptions, DeliveryOutcome } from "../server/deliveries.js";
+import { deliverOnce as deliverOnceWithContext } from "../server/deliveries.js";
+import { getMailingContext } from "./context.js";
+
+/** Sends one mail at most once per scope and recipient; see `deliverOnce` in `@softure-ai/mailing/server`. */
+export async function deliverOnce(delivery: Delivery, options: DeliverOptions = {}): Promise<DeliveryOutcome> {
+  return deliverOnceWithContext(await getMailingContext(), delivery, options);
+}

package/src/next/index.ts

@@ -0,0 +1,10 @@
+// The Next.js adapter of @softure-ai/mailing: sending (and sending once, through the ledger) on the
+// registered configuration, the unsubscribe page with its action, and the one-click route
+// (docs/02-module-standard.md §8).
+export { unsubscribeAction } from "./actions.js";
+export { deliverOnce } from "./deliver-once.js";
+export { getMailingMessages } from "./messages.js";
+export { UnsubscribePage, type UnsubscribePageProps } from "./pages.js";
+export { UNSUBSCRIBE_STATUS_PARAM, type UnsubscribeStatus } from "./params.js";
+export { getUnsubscribeRoute, postUnsubscribeRoute } from "./route.js";
+export { sendMail } from "./send-mail.js";

package/src/next/messages.ts

@@ -0,0 +1,9 @@
+import type { SoftureConfig } from "@softure-ai/core";
+import type { MailingMessages } from "../messages/index.js";
+import { getMailingModule } from "../server/options.js";
+
+/** The module's copy in the app's locale, with the app's overrides applied. */
+export function getMailingMessages(config: SoftureConfig): MailingMessages {
+  // The module factory merged the dictionaries; their shape is the module's own.
+  return getMailingModule(config).messages[config.locale] as MailingMessages;
+}