@softure-ai/mailing 0.0.0-stage → 0.1.6

package/dist/cli/run.js

@@ -0,0 +1,288 @@
+// `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 } from "@softure-ai/core";
+import { openCommandDatabase } from "@softure-ai/db";
+import { parseCampaignFile, parseRecipientList } from "../server/campaign-file.js";
+import { planCampaign, sendCampaign } from "../server/campaigns.js";
+import { checkSenderDns, getSenderDomain } from "../server/dns.js";
+import { getMailingOptions } from "../server/options.js";
+import { MIN_UNSUBSCRIBE_SECRET_LENGTH, readUnsubscribeSecrets, UNSUBSCRIBE_SECRET_ENV } from "../server/unsubscribe-link.js";
+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 = {
+    log: (line) => console.log(line),
+    error: (line) => console.error(line),
+};
+/** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
+export async function runMailCli(options) {
+    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) {
+    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;
+    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"].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"].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) {
+    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, options, output) {
+    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 = [
+        ["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, options, output) {
+    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;
+    try {
+        opened = await openDatabase(config.database, options.openDatabase);
+    }
+    catch (error) {
+        output.error(`softure-mail campaign: ${describeError(error)}`);
+        return EXIT_FAILED;
+    }
+    const ctx = { 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();
+    }
+}
+async function loadCampaign(contentPath, recipientsPath) {
+    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 = 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, loaded, output) {
+    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, loaded, pace, output) {
+    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) {
+    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, open) {
+    if (open === undefined)
+        return openCommandDatabase(database, { max: 1 });
+    const handle = await open(database.url);
+    return { handle, close: handle.close };
+}
+async function readText(path) {
+    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) {
+    if (!(error instanceof Error))
+        return String(error);
+    return error.cause instanceof Error ? error.cause.message : error.message;
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

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

package/dist/contract.d.ts

@@ -0,0 +1,102 @@
+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 declare 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>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

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

package/dist/contract.js

@@ -0,0 +1,3 @@
+/** The kind of every mail that is not list mail: sent whatever the recipient unsubscribed from. */
+export const TRANSACTIONAL_KIND = "transactional";
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAkBA,mGAAmG;AACnG,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+export declare const MODULE_ID = "mailing";
+/**
+ * Enables mail in `softure.config.ts`:
+ * `mailing({ from: "Plan <hello@mail.example.com>", replyTo: "support@example.com", provider: resend() })`.
+ */
+export declare const mailing: import("@softure-ai/core").ModuleFactory<{
+    unsubscribe: string;
+    oneClick: string;
+}, {
+    errors: {
+        mailing: {
+            invalid_input: string;
+            rejected: string;
+            unavailable: string;
+            suppressed: string;
+        };
+    };
+    footer: {
+        text: string;
+        htmlLead: string;
+        htmlLink: string;
+    };
+    unsubscribe: {
+        title: string;
+        lead: string;
+        submit: string;
+        doneTitle: string;
+        doneBody: string;
+        invalidTitle: string;
+        invalidBody: string;
+        failed: string;
+    };
+}, import("zod").ZodObject<{
+    from: import("zod").ZodString;
+    replyTo: import("zod").ZodOptional<import("zod").ZodString>;
+    provider: import("zod").ZodCustom<import("./contract.js").MailProvider, import("./contract.js").MailProvider>;
+    timeoutMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+    onUnsubscribed: import("zod").ZodOptional<import("zod").ZodCustom<import("./contract.js").OnUnsubscribedHook, import("./contract.js").OnUnsubscribedHook>>;
+}, import("zod/v4/core").$strict>>;
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,SAAS,YAAY,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kCAqClB,CAAC;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,QAAQ,EACR,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAE,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,59 @@
+// 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 { getMailingErrorMessage, mailingMessages } from "./messages/index.js";
+export { DEFAULT_TIMEOUT_MS } from "./options.js";
+export { resend, RESEND_API_KEY_ENV, RESEND_ENDPOINT } from "./providers/resend.js";
+export { campaigns, deliveries, mailingSchema, suppressions } from "./schema.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,mGAAmG;AACnG,mGAAmG;AACnG,mGAAmG;AACnG,gDAAgD;AAChD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,CAAC;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,YAAY,CAAC;IAClC,QAAQ,EAAE;QACR,EAAE,EAAE,SAAS;QACb,OAAO,EAAE,OAAO;QAChB,SAAS,EAAE,EAAE;QACb,QAAQ,EAAE,SAAS;QACnB,MAAM,EAAE,CAAC,cAAc,EAAE,WAAW,EAAE,YAAY,CAAC;QACnD,GAAG,EAAE;YACH;gBACE,IAAI,EAAE,gBAAgB;gBACtB,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,+GAA+G;aAC7H;YACD;gBACE,IAAI,EAAE,4BAA4B;gBAClC,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,6MAA6M;aAC3N;YACD;gBACE,IAAI,EAAE,qCAAqC;gBAC3C,QAAQ,EAAE,KAAK;gBACf,WAAW,EAAE,yGAAyG;aACvH;SACF;QACD,QAAQ,EAAE,EAAE;QACZ,MAAM,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,QAAQ,EAAE,0BAA0B,EAAE;QAC7E,KAAK,EAAE;YACL,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,EAAE,MAAM,EAAE,iBAAiB,EAAE;YAC7E,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,sCAAsC,EAAE,MAAM,EAAE,sBAAsB,EAAE;YACvG,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,sCAAsC,EAAE,MAAM,EAAE,qBAAqB,EAAE;SACvG;QACD,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE;KAC5C;IACD,QAAQ,EAAE,eAAe;IACzB,OAAO,EAAE,oBAAoB;IAC7B,UAAU,EAAE,EAAE,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,EAAE;IAC5E,MAAM,EAAE,kBAAkB;CAC3B,CAAC,CAAC;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,0BAA0B,EAC1B,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAenD,OAAO,EAAE,sBAAsB,EAAE,eAAe,EAAwB,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,kBAAkB,EAAiD,MAAM,cAAc,CAAC;AACjG,OAAO,EAAE,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAsB,MAAM,uBAAuB,CAAC;AACxG,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,YAAY,EAAuB,MAAM,aAAa,CAAC"}

package/dist/messages/en.d.ts

@@ -0,0 +1,26 @@
+export declare const en: {
+    errors: {
+        mailing: {
+            invalid_input: string;
+            rejected: string;
+            unavailable: string;
+            suppressed: string;
+        };
+    };
+    footer: {
+        text: string;
+        htmlLead: string;
+        htmlLink: string;
+    };
+    unsubscribe: {
+        title: string;
+        lead: string;
+        submit: string;
+        doneTitle: string;
+        doneBody: string;
+        invalidTitle: string;
+        invalidBody: string;
+        failed: string;
+    };
+};
+//# sourceMappingURL=en.d.ts.map

package/dist/messages/en.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"en.d.ts","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;CAwBd,CAAC"}

package/dist/messages/en.js

@@ -0,0 +1,26 @@
+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.",
+    },
+};
+//# sourceMappingURL=en.js.map

package/dist/messages/en.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"en.js","sourceRoot":"","sources":["../../src/messages/en.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,MAAM,EAAE;QACN,OAAO,EAAE;YACP,aAAa,EAAE,+DAA+D;YAC9E,QAAQ,EAAE,wCAAwC;YAClD,WAAW,EAAE,2DAA2D;YACxE,UAAU,EAAE,mEAAmE;SAChF;KACF;IACD,MAAM,EAAE;QACN,IAAI,EAAE,4CAA4C;QAClD,QAAQ,EAAE,0BAA0B;QACpC,QAAQ,EAAE,aAAa;KACxB;IACD,WAAW,EAAE;QACX,KAAK,EAAE,aAAa;QACpB,IAAI,EAAE,8GAA8G;QACpH,MAAM,EAAE,gBAAgB;QACxB,SAAS,EAAE,sBAAsB;QACjC,QAAQ,EAAE,6CAA6C;QACvD,YAAY,EAAE,yBAAyB;QACvC,WAAW,EAAE,gHAAgH;QAC7H,MAAM,EAAE,gDAAgD;KACzD;CACF,CAAC"}