@softure-ai/mailing 0.0.0-stage → 0.1.6

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,6DAA6D;AAC7D,OAAO,EAAE,gBAAgB,EAA0E,MAAM,oBAAoB,CAAC;AAC9H,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/testing/outbox.d.ts

@@ -0,0 +1,6 @@
+import type { CapturedMail } from "./fake-provider.js";
+/** Every mail in the outbox, oldest first, optionally only those to `to`. A missing file is an empty outbox. */
+export declare function readMailOutbox(file: string, filter?: {
+    readonly to?: string;
+}): Promise<CapturedMail[]>;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/testing/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/testing/outbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAcvD,gHAAgH;AAChH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAajH"}

package/dist/testing/outbox.js

@@ -0,0 +1,32 @@
+// Reads the outbox file of `fakeMailProvider({ outboxFile })`, e.g. from a Playwright test.
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+const capturedMailSchema = z.object({
+    id: z.string(),
+    from: z.string(),
+    to: z.string(),
+    replyTo: z.string().nullable(),
+    subject: z.string(),
+    text: z.string(),
+    html: z.string().nullable(),
+    headers: z.record(z.string(), z.string()),
+    idempotencyKey: z.string().nullable(),
+});
+/** Every mail in the outbox, oldest first, optionally only those to `to`. A missing file is an empty outbox. */
+export async function readMailOutbox(file, filter = {}) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return text
+        .split("\n")
+        .filter((line) => line !== "")
+        .map((line) => capturedMailSchema.parse(JSON.parse(line)))
+        .filter((mail) => filter.to === undefined || mail.to === filter.to);
+}
+//# sourceMappingURL=outbox.js.map

package/dist/testing/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/testing/outbox.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;IACd,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IACzC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC,CAAC;AAEH,gHAAgH;AAChH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,SAAmC,EAAE;IACtF,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;SAC7B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;SACzD,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,KAAK,SAAS,IAAI,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/migrations/0001_create_suppressions.sql

@@ -0,0 +1,13 @@
+-- The recipients who unsubscribed from list mail (every kind but `transactional`). One row per
+-- address, global across kinds. The address itself is never stored: `recipient_key` is the
+-- base64url SHA-256 of the trimmed, lowercased address (getRecipientKey), the same value the
+-- signed unsubscribe link carries. A second unsubscribe keeps the first row.
+-- Rollback: DROP TABLE mailing.suppressions; then
+--   DELETE FROM softure.migrations WHERE module = 'mailing' AND version = 1;
+CREATE TABLE suppressions (
+  recipient_key text PRIMARY KEY CHECK (recipient_key ~ '^[A-Za-z0-9_-]{43}$'),
+  -- How the opt-out arrived: a mail client's one-click POST, the unsubscribe page's button, or an
+  -- operator (suppressRecipient from a script or another module).
+  source text NOT NULL CHECK (source IN ('one-click', 'page', 'operator')),
+  created_at timestamptz NOT NULL
+);

package/migrations/0002_create_campaigns_and_deliveries.sql

@@ -0,0 +1,41 @@
+-- The delivery ledger: every mail that must go out at most once to a recipient within a scope (a
+-- campaign, or a lifecycle event such as `billing.trial-ending:sub_42`). A sender claims the row
+-- before calling the provider and closes it with one outcome, `sent` or `rejected`; `pending` is a
+-- claim released after the provider was unavailable. Recipients are keys (getRecipientKey), never
+-- addresses, as in mailing.suppressions.
+-- Rollback: DROP TABLE mailing.deliveries; DROP TABLE mailing.campaigns; then
+--   DELETE FROM softure.migrations WHERE module = 'mailing' AND version = 2;
+
+-- A campaign pins its content: a second run with the same id and other content is refused.
+CREATE TABLE campaigns (
+  id text PRIMARY KEY CHECK (id ~ '^[a-z0-9]+(-[a-z0-9]+)*$' AND length(id) <= 64),
+  -- Campaigns are list mail: they carry the unsubscribe link and skip suppressed recipients.
+  kind text NOT NULL CHECK (kind ~ '^[a-z0-9]+(-[a-z0-9]+)*$' AND length(kind) <= 64 AND kind <> 'transactional'),
+  subject text NOT NULL CHECK (length(subject) BETWEEN 1 AND 998),
+  -- sha256 (hex) of the kind, subject, text and HTML bodies.
+  content_hash text NOT NULL CHECK (content_hash ~ '^[0-9a-f]{64}$'),
+  created_at timestamptz NOT NULL
+);
+
+CREATE TABLE deliveries (
+  scope text NOT NULL CHECK (scope ~ '^[a-z0-9][a-z0-9._:-]*$' AND length(scope) <= 128),
+  recipient_key text NOT NULL CHECK (recipient_key ~ '^[A-Za-z0-9_-]{43}$'),
+  kind text NOT NULL CHECK (kind ~ '^[a-z0-9]+(-[a-z0-9]+)*$' AND length(kind) <= 64),
+  campaign_id text REFERENCES campaigns (id),
+  status text NOT NULL CHECK (status IN ('pending', 'claimed', 'sent', 'rejected')),
+  -- Claims so far; an outcome is written only by the holder of the latest claim.
+  attempts integer NOT NULL CHECK (attempts >= 1),
+  claimed_at timestamptz NOT NULL,
+  finished_at timestamptz,
+  provider_message_id text,
+  -- Why a rejected delivery is final: a mailing.* error code of sendMail.
+  reason text CHECK (reason IN ('mailing.invalid_input', 'mailing.rejected', 'mailing.unavailable', 'mailing.suppressed')),
+  created_at timestamptz NOT NULL,
+  PRIMARY KEY (scope, recipient_key),
+  CHECK (campaign_id IS NULL OR scope = 'campaign:' || campaign_id),
+  CHECK ((status = 'sent') = (provider_message_id IS NOT NULL)),
+  CHECK ((status = 'rejected') = (reason IS NOT NULL)),
+  CHECK ((status IN ('sent', 'rejected')) = (finished_at IS NOT NULL))
+);
+
+CREATE INDEX deliveries_campaign_status ON deliveries (campaign_id, status) WHERE campaign_id IS NOT NULL;

package/module.json

@@ -0,0 +1,32 @@
+{
+  "id": "mailing",
+  "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 }
+}

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "@softure-ai/mailing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.6",
+  "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",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SOFTURE/AI.git",
+    "directory": "modules/mailing"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "migrations",
+    "module.json"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "softure-mail": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "@softure-ai/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "@softure-ai/source": "./src/server/index.ts",
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./next": {
+      "@softure-ai/source": "./src/next/index.ts",
+      "types": "./dist/next/index.d.ts",
+      "default": "./dist/next/index.js"
+    },
+    "./testing": {
+      "@softure-ai/source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./cli": {
+      "@softure-ai/source": "./src/cli/index.ts",
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@softure-ai/core": "^0.1.0",
+    "@softure-ai/db": "^0.1.0",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@softure-ai/ui": "^0.1.0",
+    "drizzle-orm": "^0.45.2",
+    "next": "^16.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@softure-ai/ui": "^0.1.7"
+  }
+}

package/src/address.ts

@@ -0,0 +1,89 @@
+// Address and header rules shared by the options schema and the mail validation.
+
+/**
+ * One address: an `@`, a dot-separated domain, no list separators, no whitespace, no angle
+ * brackets. Each part excludes its own separator, so matching stays linear on any input.
+ */
+const ADDRESS = /^[^\s@,;<>"]+@[^\s@,;<>".]+(?:\.[^\s@,;<>".]+)+$/;
+
+/**
+ * A display name: no commas, semicolons or quotes. Unquoted, RFC 5322 reads a comma as a second
+ * address, and quoting is left out on purpose.
+ */
+const DISPLAY_NAME = /^[^<>",;\r\n]+$/;
+
+/** The longest address SMTP carries (RFC 5321 path limit). */
+export const MAX_ADDRESS_LENGTH = 254;
+
+/** RFC 5322 field name: printable ASCII except the colon. */
+const HEADER_NAME = /^[!-9;-~]+$/;
+
+/**
+ * Headers that would take over the envelope, the sender or the body's encoding. The `headers`
+ * field is for list headers (RFC 8058) and similar; a different `From:` fails DMARC, an added
+ * recipient is mail nobody asked for.
+ */
+export const RESERVED_HEADERS: ReadonlySet<string> = new Set([
+  "from",
+  "sender",
+  "to",
+  "cc",
+  "bcc",
+  "reply-to",
+  "subject",
+  "return-path",
+  "content-type",
+  "content-transfer-encoding",
+  "mime-version",
+]);
+
+/**
+ * Headers the module writes on every list mail. A list mail that brings its own is refused: two
+ * `List-Unsubscribe` headers, one of them unsigned, is worse than none.
+ */
+export const LIST_MAIL_HEADERS: ReadonlySet<string> = new Set(["list-unsubscribe", "list-unsubscribe-post"]);
+
+/** A mail kind: kebab-case, 1 to 64 characters, e.g. `newsletter`. */
+const MAIL_KIND = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+export const MAX_MAIL_KIND_LENGTH = 64;
+
+export const MAX_SUBJECT_LENGTH = 998;
+export const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+
+export function isSingleAddress(value: string): boolean {
+  return value.length <= MAX_ADDRESS_LENGTH && ADDRESS.test(value);
+}
+
+/** `addr` or `Name <addr>`, on one line. */
+export function isMailbox(value: string): boolean {
+  if (hasLineBreak(value)) return false;
+  if (!value.endsWith(">")) return isSingleAddress(value);
+  const open = value.lastIndexOf("<");
+  const name = value.slice(0, Math.max(open, 0)).trim();
+  return open > 0 && name !== "" && DISPLAY_NAME.test(name) && isSingleAddress(value.slice(open + 1, -1));
+}
+
+export function hasLineBreak(value: string): boolean {
+  return /[\r\n]/.test(value);
+}
+
+export function isHeaderName(name: string): boolean {
+  return HEADER_NAME.test(name);
+}
+
+export function isReservedHeader(name: string): boolean {
+  return RESERVED_HEADERS.has(name.toLowerCase());
+}
+
+export function isListMailHeader(name: string): boolean {
+  return LIST_MAIL_HEADERS.has(name.toLowerCase());
+}
+
+export function isMailKind(kind: string): boolean {
+  return kind.length <= MAX_MAIL_KIND_LENGTH && MAIL_KIND.test(kind);
+}
+
+/** 1 to 256 visible ASCII characters. */
+export function isIdempotencyKey(key: string): boolean {
+  return key.length <= MAX_IDEMPOTENCY_KEY_LENGTH && /^[!-~]+$/.test(key);
+}

package/src/cli/bin.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// The `softure-mail` executable. All logic lives in command.ts and run.ts, which the tests call directly.
+import { runMailCommand } from "./command.js";
+
+process.exitCode = await runMailCommand({ argv: process.argv.slice(2), cwd: process.cwd() });

package/src/cli/command.ts

@@ -0,0 +1,44 @@
+// The `softure-mail` bin. It loads the app's config through `@softure-ai/core/cli`, like
+// `softure migrate` (@softure-ai/db): the file must be loadable by Node itself (`.js`/`.mjs`, or `.ts`
+// where Node strips types). Anything else uses an app script with `runMailCli` instead (see run.ts).
+import { loadAppConfig, takeConfigOption } from "@softure-ai/core/cli";
+import { EXIT_FAILED, EXIT_USAGE, MAIL_USAGE, runMailCli, type CliOutput } from "./run.js";
+
+export interface RunMailCommandOptions {
+  readonly argv: readonly string[];
+  readonly cwd: string;
+  readonly output?: CliOutput;
+}
+
+const APP_SCRIPT = { runner: "runMailCli", packageName: "@softure-ai/mailing" };
+
+const consoleOutput: CliOutput = {
+  log: (line) => console.log(line),
+  error: (line) => console.error(line),
+};
+
+/** Loads the config (unless the command needs none) and runs `runMailCli`. */
+export async function runMailCommand(options: RunMailCommandOptions): Promise<number> {
+  const output = options.output ?? consoleOutput;
+  const taken = takeConfigOption(options.argv);
+  if (!taken.ok) {
+    output.error(`softure-mail: ${taken.problem}`);
+    output.error(MAIL_USAGE);
+    return EXIT_USAGE;
+  }
+  const { configPath, argv } = taken;
+  if (!needsConfig(argv) && configPath === undefined) return runMailCli({ argv, cwd: options.cwd, output });
+
+  const loaded = await loadAppConfig({ cwd: options.cwd, configPath, appScript: APP_SCRIPT });
+  if (!loaded.ok) {
+    output.error(`softure-mail: ${loaded.problem}`);
+    return EXIT_FAILED;
+  }
+  return runMailCli({ config: loaded.config, argv, cwd: options.cwd, output });
+}
+
+/** `dns --domain` and help need no config; everything else reads it. */
+function needsConfig(argv: readonly string[]): boolean {
+  if (argv.length === 0 || argv.includes("--help")) return false;
+  return !(argv[0] === "dns" && argv.some((arg) => arg === "--domain" || arg.startsWith("--domain=")));
+}

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// `@softure-ai/mailing/cli`: the `softure-mail` command for app scripts and container bundles.
+export { runMailCommand, type RunMailCommandOptions } from "./command.js";
+export { DEFAULT_PAUSE_MS, EXIT_FAILED, EXIT_OK, EXIT_USAGE, MAIL_USAGE, runMailCli, type CliOutput, type RunMailCliOptions } from "./run.js";