@softure-ai/mailing 0.0.0-stage → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOFTURE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,350 @@
-# Temporary Holding Version
+# @softure-ai/mailing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Status:** wave 2 · transport (EN-1), unsubscribe (EN-2), delivery ledger, campaigns and sender DNS
+check (EN-3).
+
+Sends one mail to one recipient through a provider adapter and answers with a typed result, never a
+throw. Ported from FIRE_TRACKER `src/lib/mail.ts` (a hand-written Resend `fetch`, plain text only),
+with the sender, reply-to, provider and timeout taken from configuration, an HTML body, and a fake
+provider for tests. List mail gets signed one-click unsubscribe (RFC 8058) and a suppression list,
+ported from FIRE_TRACKER `src/lib/unsubscribe-*.ts` and `/wypisz`. A delivery ledger sends a mail
+at most once per scope and recipient, and `softure-mail` sends campaigns from a content file where
+FIRE ran deployment-specific scripts.
+
+## 1. What it provides
+
+- `mailing({ from, replyTo, provider, timeoutMs })` for `softure.config.ts`.
+- `sendMail(context, mail, options)` in `@softure-ai/mailing/server` and `sendMail(mail, options)` in
+  `@softure-ai/mailing/next` (on the registered config). The result is a core `Result`:
+
+  | Result | Meaning | What the caller does |
+  | --- | --- | --- |
+  | `ok({ id, provider })` | the provider accepted the mail | keep `id` if it needs one |
+  | `err("mailing.invalid_input")` | refused before anything left the process | fix the input; never retry |
+  | `err("mailing.rejected")` | the provider refused it (4xx: bad address, bad key, key reused with another body) | do not retry the same request |
+  | `err("mailing.unavailable")` | provider down (5xx), 408, 429, a busy idempotency key, network, timeout, an answer without an id, no API key; for list mail also no unsubscribe secret or an unreadable suppression list | retry later with the same `idempotencyKey` |
+  | `err("mailing.suppressed")` | a list mail to a recipient who unsubscribed; nothing was sent | skip the recipient; never retry |
+
+- **List mail.** `kind: "transactional"` (the default) is mail the recipient needs whatever they
+  unsubscribed from: resets, receipts, account notices. Any other kebab-case kind (`newsletter`,
+  `product-updates`) is list mail: `sendMail` appends a footer with a signed unsubscribe link to the
+  text and HTML bodies, adds `List-Unsubscribe: <one-click URL>` and
+  `List-Unsubscribe-Post: List-Unsubscribe=One-Click`, and refuses the mail with `mailing.suppressed`
+  when the recipient unsubscribed. An unsubscribe covers every list kind.
+- The unsubscribe page (`/unsubscribe`) and the one-click route (`/api/mailing/unsubscribe`) in `/next`,
+  each mounted with one line (section 4).
+- `@softure-ai/mailing/server`: `isSuppressed(ctx, address)`, `suppressRecipient(ctx, address)` (for
+  scripts, bounce or complaint handlers), `unsubscribe(ctx, token, source)`,
+  `liftSuppression(ctx, address)` (a new explicit consent lifts the person's own opt-out),
+  `buildUnsubscribeLinks`, `getRecipientKey`, and the footer and header helpers.
+- **An `onUnsubscribed` hook**, run in the opt-out's transaction, so the consent ledger can record
+  the withdrawal (section 10).
+- **Sending once.** `deliverOnce(ctx, { scope, mail })` (`/server`, and `deliverOnce({ scope, mail })`
+  in `/next`) sends a mail at most once per scope and recipient through the delivery ledger.
+- **Campaigns.** `sendCampaign`, `planCampaign` and the content file parser in `/server`; the
+  `softure-mail campaign` command sends a campaign from a content file.
+- **Sender DNS.** `checkSenderDns(domain)` and `softure-mail dns` report SPF, DKIM and DMARC.
+- The `MailProvider` contract and `resend()`, the first adapter.
+- `@softure-ai/mailing/testing`: `fakeMailProvider()` and `readMailOutbox(file)`.
+
+```ts
+import { sendMail } from "@softure-ai/mailing/next";
+
+const result = await sendMail(
+  { to: user.email, subject: messages.summary.subject, text, html },
+  { idempotencyKey: `weekly-summary:${user.id}:${week}` },
+);
+if (!result.ok) return result; // a code; the UI shows getMailingErrorMessage(messages, result.error)
+
+// List mail: footer, headers and the suppression check come with the kind.
+await sendMail({ to: user.email, subject, text, html, kind: "newsletter" }, { idempotencyKey: `newsletter-12:${user.id}` });
+```
+
+From scripts and other modules, `/server` takes the context: `sendMail({ config }, mail)` for
+transactional mail, `sendMail({ config, db }, mail)` for list mail (the suppression check reads
+the database; list mail without `db` throws, as a wiring bug).
+
+Rules that hold for every send:
+
+- **One recipient.** `to` is exactly one address; a list is a loop. No cc or bcc.
+- **Text always, HTML optionally.** `text` is required; `html` is a string the app rendered (from a
+  template string or React email components rendered to a string: the module does not render).
+- **Headers cannot take over the mail.** `headers` is for headers like `List-Unsubscribe`;
+  `From`, `Sender`, `To`, `Cc`, `Bcc`, `Reply-To`, `Subject`, `Return-Path`, `Content-Type`,
+  `Content-Transfer-Encoding` and `MIME-Version` are refused in any case, as are line breaks in
+  values and the subject.
+- **Nothing of the mail is logged.** One line per failure:
+  `mailing: send failed provider=resend reason=rejected status=422` (with `fields=to,subject` for
+  invalid input). Provider refusal messages are never read: they can echo the address.
+- **Timeout.** After `timeoutMs` the provider's signal aborts and the send answers `unavailable`,
+  even when the provider ignores the signal.
+- **List mail fails closed.** No secret or an unreadable suppression list means nothing is sent.
+  A list mail cannot bring its own `List-Unsubscribe` or `List-Unsubscribe-Post`: the module writes
+  them (`invalid_input`).
+
+**How a link works.** The link carries `r`, the base64url SHA-256 of the trimmed, lowercased
+address, and `t`, the base64url HMAC-SHA256 of a fixed prefix plus `r` under
+`MAILING_UNSUBSCRIBE_SECRET`. The address never appears in a URL, and the suppression table stores
+only `r`. The page (footer link) shows a button and changes nothing on open: mail scanners open
+links. The one-click route takes a mail client's POST without a session, verifies before touching
+the database and answers 200 (recorded, also again), 400 (link does not verify) or 500 (database
+failure, so the client retries); a GET redirects to the page. The whole link is a credential: it is
+never logged.
+
+### Sending once: the delivery ledger
+
+`deliverOnce` claims a row in `mailing.deliveries` for the scope and the recipient before it calls
+`sendMail`, and closes it with one outcome. A second call for the same scope and recipient (any
+case or spacing of the address) sends nothing:
+
+```ts
+import { deliverOnce } from "@softure-ai/mailing/next";
+
+const outcome = await deliverOnce({
+  scope: `billing.trial-ending:${subscription.id}`,
+  mail: { to: user.email, subject, text, kind: "account-notices" },
+});
+```
+
+| Outcome | Meaning |
+| --- | --- |
+| `{ status: "sent", id }` | sent now |
+| `{ status: "rejected", reason }` | refused now, for good: `mailing.suppressed`, `rejected`, `invalid_input`, or `unavailable` on the last attempt |
+| `{ status: "done", outcome }` | an earlier call closed it (`sent` or `rejected`); nothing sent |
+| `{ status: "in-flight" }` | another sender holds a fresh claim; nothing sent |
+| `{ status: "retry-later" }` | the provider was unavailable; the claim is released, call again later |
+
+- **Scopes** name what the mail is about and are the only registration a lifecycle mail needs:
+  `<module>.<event>:<entity>` (`billing.trial-ending:sub_42`, `waitlist.welcome:<signup id>`).
+  Lowercase letters, digits and `._:-`, at most 128 characters. Campaigns use `campaign:<id>`.
+- **Idempotency key.** The ledger sends with `<scope>:<recipient key>`; callers do not pass one.
+- **Retries.** `unavailable` releases the claim (`pending`); the fifth attempt (`maxAttempts`) that
+  is still unavailable closes the row as `rejected`. A process that dies between the send and the
+  outcome leaves a claim; after 15 minutes (`staleClaimMs`) another call takes it over and sends
+  again with the same idempotency key, which the provider folds into the first send while it keeps
+  the key (Resend: 24 hours). Outcomes are fenced by the attempt number, so a sender that lost its
+  claim cannot overwrite the one that took over.
+- A malformed scope or kind throws (a bug); a database failure propagates.
+
+### Campaigns: `softure-mail campaign`
+
+A campaign is one list mail to many recipients through the ledger. The content file is frontmatter
+and a plain-text body; `html` (optional) names a file next to it:
+
+```text
+---
+id: 2026-10-launch
+kind: newsletter
+subject: Something new in Plan
+html: launch.html
+---
+Hello,
+
+we shipped something.
+```
+
+```bash
+softure-mail campaign launch.md --recipients recipients.txt --dry-run   # counts, sends nothing
+softure-mail campaign launch.md --recipients recipients.txt              # sends
+```
+
+- The recipients file holds one address per line (`#` comments and blank lines skipped).
+- The command loads `softure.config.*` like `softure migrate` (or `--config <file>`), opens its own
+  database connection (`database.url`) and needs `MAILING_UNSUBSCRIBE_SECRET` (campaigns are list
+  mail). Run `softure migrate` first.
+- Sends go one at a time with a 500 ms pause (`--pause-ms`; Resend allows 2 requests per second by
+  default). Unsubscribed recipients are rejected without a send and never retried.
+- **Re-runs are safe.** Recipients with an outcome are skipped; the command exits 1 while some have
+  none yet (`retry later`, `in flight`): run the same command again. `mailing.campaigns` pins the
+  content by hash: other content under the same id is refused, so a changed campaign needs a new id.
+- From a script (a bundled container, a list built from the database), call
+  `runMailCli({ config, argv })` from `@softure-ai/mailing/cli`, or `sendCampaign(ctx, { campaign,
+  recipients })` from `/server`, where `recipients` may be an async iterable.
+
+### Sender DNS check: `softure-mail dns`
+
+```bash
+softure-mail dns                                       # the domain of `from` in the config
+softure-mail dns --domain mail.example.com --spf-host send.mail.example.com
+```
+
+It reads TXT records and reports each check as `pass`, `warn` or `fail`, exiting 1 on any `fail`:
+SPF (one `v=spf1` record on the domain or each `--spf-host`; `+all` warns), DKIM (a non-empty `p=`
+at `<selector>._domainkey.<domain>`; selector `resend` unless `--dkim-selector` is given) and DMARC
+(`_dmarc.<domain>` or a parent domain's record; `p=none` warns: it only reports). Resend publishes
+SPF on `send.<domain>`. It cannot see whether the provider signs with the published key.
+
+## 2. Installation
+
+```bash
+npm install @softure-ai/mailing @softure-ai/core @softure-ai/db @softure-ai/ui drizzle-orm
+```
+
+Peer dependencies: `drizzle-orm`, and `next` and `react` for the `/next` adapter. The module needs a
+database (its suppression list). The `/testing` entry imports `node:fs`.
+
+## 3. Configuration
+
+```ts
+import { mailing, resend } from "@softure-ai/mailing";
+
+// in defineSoftureConfig({ modules: [...] }):
+mailing({
+  from: "Plan <hello@mail.example.com>",
+  replyTo: "support@example.com",
+  provider: resend(),
+}),
+```
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `from` | `string` | required | `addr` or `Name <addr>` (no commas, semicolons or quotes in the name). Must be on the domain the provider signs (DKIM); with DMARC `adkim=s` exactly that subdomain. |
+| `replyTo` | `string` | none | One address for replies; may be on another domain (DMARC does not check it). |
+| `provider` | `MailProvider` | required | `resend()`, `fakeMailProvider()` or your own adapter. |
+| `timeoutMs` | `number` | `10000` | 1000 to 60000. |
+| `onUnsubscribed` | `(event, ctx) => Promise<void>` | — | Runs on every verified unsubscribe, in its transaction (section 10). |
+| `routes` | `{ unsubscribe?, oneClick? }` | `/unsubscribe`, `/api/mailing/unsubscribe` | Where you mount the page and the route; links are built on `appOrigin` plus these paths. |
+
+`resend({ apiKey?, endpoint?, fetch? })`: without `apiKey` it reads `RESEND_API_KEY` on every send,
+so the configuration loads at build time without the secret.
+
+**Your own provider:**
+
+```ts
+const provider: MailProvider = {
+  name: "postmark",
+  async send(message, { signal }) {
+    const response = await fetch(URL, { method: "POST", body: toBody(message), signal });
+    if (response.ok) return { status: "sent", id: (await response.json()).MessageID };
+    return { status: response.status >= 500 || response.status === 429 ? "unavailable" : "rejected", httpStatus: response.status };
+  },
+};
+```
+
+A provider receives a validated `ProviderMessage` (`from`, `to`, `replyTo`, `subject`, `text`, `html`,
+`headers`, `idempotencyKey`, nulls for what is absent). A throw reads as `unavailable`.
+
+## 4. Mounting
+
+Two files, one line each:
+
+```ts
+// app/unsubscribe/page.tsx
+export { UnsubscribePage as default } from "@softure-ai/mailing/next";
+```
+
+```ts
+// app/api/mailing/unsubscribe/route.ts
+export { getUnsubscribeRoute as GET, postUnsubscribeRoute as POST } from "@softure-ai/mailing/next";
+```
+
+Both must stay public: keep them out of the auth guard's `protect` list. The route has no per-IP
+rate limit on purpose: mail providers post from a few shared addresses that act for millions of
+people, so a bucket would refuse real unsubscribes; the signature is checked before any database
+access and the only write is an idempotent insert. Behind a proxy that logs failed requests with
+their query, a 500 puts the link in that log; it is the one place it can appear.
+
+Call `sendMail` from server actions, route handlers (`/next`) or scripts and other modules
+(`/server`, with `{ config }` or `{ config, db }`).
+
+## 5. Migrations and tables
+
+Schema `mailing`, applied by `softure migrate`:
+
+| Migration | Table | What it holds |
+| --- | --- | --- |
+| `0001_create_suppressions.sql` | `mailing.suppressions` | `recipient_key` (primary key, 43-character base64url), `source` (`one-click`, `page`, `operator`), `created_at`. One row per address, the first opt-out kept. |
+| `0002_create_campaigns_and_deliveries.sql` | `mailing.campaigns` | `id` (kebab-case), `kind` (never `transactional`), `subject`, `content_hash` (sha256 of kind, subject and bodies), `created_at`. |
+| | `mailing.deliveries` | primary key (`scope`, `recipient_key`), `kind`, `campaign_id` (then `scope` is `campaign:<id>`), `status` (`pending`, `claimed`, `sent`, `rejected`), `attempts`, `claimed_at`, `finished_at`, `provider_message_id` (exactly when sent), `reason` (exactly when rejected). |
+
+The health check (`checkMailingTables`) runs `select 1 from mailing.<table> limit 0` for the three
+tables.
+
+## 6. Environment variables
+
+| Variable | Required | What it does |
+| --- | --- | --- |
+| `RESEND_API_KEY` | with `resend()` and no `apiKey` | Resend API key. Missing at send time: `unavailable` and a log line naming the variable. |
+| `MAILING_UNSUBSCRIBE_SECRET` | to send list mail | Signs and verifies unsubscribe links; at least 32 characters (`openssl rand -base64 32`), a shorter one counts as missing. Missing at send time: list mail answers `unavailable` with a log line naming the variable; transactional mail is unaffected. |
+| `MAILING_UNSUBSCRIBE_SECRET_PREVIOUS` | during a rotation | The secret before the current one: verifies links in mail already sent, never signs. |
+
+**Rotating the secret.** Links live as long as the mail that carries them. Never replace the
+secret outright: move the current value to `MAILING_UNSUBSCRIBE_SECRET_PREVIOUS`, set a new
+`MAILING_UNSUBSCRIBE_SECRET`, and keep the previous one for as long as old mail may still be
+clicked. Losing the secret means every link already sent stops working.
+
+## 7. Switches
+
+None.
+
+## 8. Appearance
+
+The unsubscribe page is a `Card` from `@softure-ai/ui` with a plain form (no client JavaScript),
+styled by the app's tokens.
+
+## 9. Copy
+
+`src/messages/{en,pl}.ts`: `errors.mailing.{invalid_input,rejected,unavailable,suppressed}`,
+`footer.{text,htmlLead,htmlLink}` (the list-mail footer, in the app's locale) and
+`unsubscribe.*` (the page). `getMailingErrorMessage(messages, code)` returns the copy for a code;
+override any text with `mailing({ messages: { en: { footer: { text: "…" } } } })`.
+
+## 10. Hooks
+
+The provider is the extension point (section 3).
+
+**`onUnsubscribed(event, ctx)`** runs on every verified unsubscribe (the page's button or a mail
+client's one-click POST), also a repeated one, in the transaction that stores the opt-out:
+`event` is `{ recipientKey, source }` (the key is privacy's email key of the same address, never the
+address), `ctx.db` is the transaction. A throw rolls the opt-out back: the route answers 500 and the
+page offers a retry, so the opt-out and what the hook records never disagree. It does not run for
+`suppressRecipient` (a bounce or a script is not the person's choice). Wire the waitlist's handler,
+which withdraws its consents in privacy's ledger:
+
+```ts
+import { withdrawWaitlistConsents } from "@softure-ai/waitlist/server";
+
+mailing({ from: "…", provider: resend(), onUnsubscribed: withdrawWaitlistConsents }),
+```
+
+**`liftSuppression(ctx, address)`** is the other direction: a module that has just recorded a new
+explicit consent (the waitlist's sign-up) calls it in that consent's transaction. It deletes the
+row only when its source is `page` or `one-click`; an `operator` row stays. It returns whether it
+lifted one.
+
+**Tests and e2e:** `fakeMailProvider()` keeps accepted mail in `provider.sent` (with the id it
+answered) and honours idempotency keys like a real provider. `respond: (message) => ({ status:
+"rejected" })` simulates failures. With `outboxFile` it also appends each mail as one JSON line, so a
+test in another process (Playwright against `next start`) reads it with `readMailOutbox(file, { to })`.
+Without an outbox file it refuses to run under `NODE_ENV=production`, where in-memory mail would
+vanish. The example app sets `MAIL_OUTBOX` for its e2e (`examples/next-app/e2e/mailing-transport.spec.ts`).
+
+## 11. GDPR
+
+Addresses and content go to the provider only; never to logs or results. The suppression list
+stores a SHA-256 of the address, not the address: pseudonymous data (it can be matched against a
+known address), kept after an account is deleted because it records the person's objection to
+mail. The delivery ledger also stores recipient keys, never addresses, and campaigns hold no
+personal data. So the module neither exports nor deletes per user (`privacy: { exports: false, deletes: false }`).
+
+## 12. Limitations
+
+- One recipient per call; no cc, bcc or attachments.
+- `sendMail` does not retry: the caller retries `unavailable` with the same `idempotencyKey` (Resend
+  keeps keys for 24 hours), or uses `deliverOnce`, which keeps the state between runs.
+- Exactly-once ends where the provider's idempotency window ends: a sender that dies after the
+  provider accepted a mail and before the outcome was written, with the row taken over more than
+  24 hours later, sends that mail twice. No delivery, bounce or complaint webhooks yet.
+- Campaigns have no personalisation, scheduling or markdown: the body is sent as written.
+- Suppression is global per address: no per-list preferences. A person comes back in through a
+  module's explicit consent (`liftSuppression`, e.g. a new waitlist sign-up); an operator row is
+  removed by hand (`getRecipientKey(address)`).
+- Lowercasing the whole address merges `Ada@` and `ada@` (allowed to differ by RFC 5321, never in
+  practice); an unsubscribe then covers both.
+- The display name in `from` cannot contain commas, semicolons or quotes (no RFC 5322 quoting).
+- Address checks are structural (one `@`, a dot in the domain, no separators); the provider has the
+  last word.
+
+## Build
+
+`npm run build -w modules/mailing` runs `tsc -p tsconfig.build.json`.

package/dist/address.d.ts

@@ -0,0 +1,27 @@
+/** The longest address SMTP carries (RFC 5321 path limit). */
+export declare const MAX_ADDRESS_LENGTH = 254;
+/**
+ * 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 declare const RESERVED_HEADERS: ReadonlySet<string>;
+/**
+ * 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 declare const LIST_MAIL_HEADERS: ReadonlySet<string>;
+export declare const MAX_MAIL_KIND_LENGTH = 64;
+export declare const MAX_SUBJECT_LENGTH = 998;
+export declare const MAX_IDEMPOTENCY_KEY_LENGTH = 256;
+export declare function isSingleAddress(value: string): boolean;
+/** `addr` or `Name <addr>`, on one line. */
+export declare function isMailbox(value: string): boolean;
+export declare function hasLineBreak(value: string): boolean;
+export declare function isHeaderName(name: string): boolean;
+export declare function isReservedHeader(name: string): boolean;
+export declare function isListMailHeader(name: string): boolean;
+export declare function isMailKind(kind: string): boolean;
+/** 1 to 256 visible ASCII characters. */
+export declare function isIdempotencyKey(key: string): boolean;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAcA,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAKtC;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAY/C,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAA0D,CAAC;AAI7G,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,4CAA4C;AAC5C,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAMhD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,yCAAyC;AACzC,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/address.js

@@ -0,0 +1,76 @@
+// 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 = 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 = 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) {
+    return value.length <= MAX_ADDRESS_LENGTH && ADDRESS.test(value);
+}
+/** `addr` or `Name <addr>`, on one line. */
+export function isMailbox(value) {
+    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) {
+    return /[\r\n]/.test(value);
+}
+export function isHeaderName(name) {
+    return HEADER_NAME.test(name);
+}
+export function isReservedHeader(name) {
+    return RESERVED_HEADERS.has(name.toLowerCase());
+}
+export function isListMailHeader(name) {
+    return LIST_MAIL_HEADERS.has(name.toLowerCase());
+}
+export function isMailKind(kind) {
+    return kind.length <= MAX_MAIL_KIND_LENGTH && MAIL_KIND.test(kind);
+}
+/** 1 to 256 visible ASCII characters. */
+export function isIdempotencyKey(key) {
+    return key.length <= MAX_IDEMPOTENCY_KEY_LENGTH && /^[!-~]+$/.test(key);
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,iFAAiF;AAEjF;;;GAGG;AACH,MAAM,OAAO,GAAG,kDAAkD,CAAC;AAEnE;;;GAGG;AACH,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAEvC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,6DAA6D;AAC7D,MAAM,WAAW,GAAG,aAAa,CAAC;AAElC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IAC3D,MAAM;IACN,QAAQ;IACR,IAAI;IACJ,IAAI;IACJ,KAAK;IACL,UAAU;IACV,SAAS;IACT,aAAa;IACb,cAAc;IACd,2BAA2B;IAC3B,cAAc;CACf,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,CAAC,kBAAkB,EAAE,uBAAuB,CAAC,CAAC,CAAC;AAE7G,sEAAsE;AACtE,MAAM,SAAS,GAAG,iCAAiC,CAAC;AACpD,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AACtC,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAE9C,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,MAAM,IAAI,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,IAAI,YAAY,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACtD,OAAO,IAAI,GAAG,CAAC,IAAI,IAAI,KAAK,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1G,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,MAAM,IAAI,oBAAoB,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,OAAO,GAAG,CAAC,MAAM,IAAI,0BAA0B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1E,CAAC"}

package/dist/cli/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":""}

package/dist/cli/bin.js

@@ -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() });
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AACA,0GAA0G;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,CAAC,QAAQ,GAAG,MAAM,cAAc,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC"}

package/dist/cli/command.d.ts

@@ -0,0 +1,9 @@
+import { type CliOutput } from "./run.js";
+export interface RunMailCommandOptions {
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly output?: CliOutput;
+}
+/** Loads the config (unless the command needs none) and runs `runMailCli`. */
+export declare function runMailCommand(options: RunMailCommandOptions): Promise<number>;
+//# sourceMappingURL=command.d.ts.map

package/dist/cli/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmD,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE3F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AASD,8EAA8E;AAC9E,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBpF"}

package/dist/cli/command.js

@@ -0,0 +1,36 @@
+// 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 } from "./run.js";
+const APP_SCRIPT = { runner: "runMailCli", packageName: "@softure-ai/mailing" };
+const consoleOutput = {
+    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) {
+    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) {
+    if (argv.length === 0 || argv.includes("--help"))
+        return false;
+    return !(argv[0] === "dns" && argv.some((arg) => arg === "--domain" || arg.startsWith("--domain=")));
+}
+//# sourceMappingURL=command.js.map

package/dist/cli/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../../src/cli/command.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,uGAAuG;AACvG,qGAAqG;AACrG,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAkB,MAAM,UAAU,CAAC;AAQ3F,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,qBAAqB,EAAE,CAAC;AAEhF,MAAM,aAAa,GAAc;IAC/B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;CACrC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAA8B;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAC/C,MAAM,KAAK,GAAG,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,MAAM,CAAC,KAAK,CAAC,iBAAiB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC/C,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACzB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;IAE1G,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;IAC5F,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,iBAAiB,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAChD,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,OAAO,UAAU,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;AAC/E,CAAC;AAED,wEAAwE;AACxE,SAAS,WAAW,CAAC,IAAuB;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/D,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,UAAU,IAAI,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;AACvG,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+// `@softure-ai/mailing/cli`: the `softure-mail` command for app scripts and container bundles.
+export { runMailCommand } from "./command.js";
+export { DEFAULT_PAUSE_MS, EXIT_FAILED, EXIT_OK, EXIT_USAGE, MAIL_USAGE, runMailCli } from "./run.js";
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,OAAO,EAAE,cAAc,EAA8B,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAA0C,MAAM,UAAU,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,31 @@
+import { type SoftureConfig } from "@softure-ai/core";
+import { type DatabaseHandle } from "@softure-ai/db";
+import { type ResolveTxt } from "../server/dns.js";
+import { 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: `createDatabase(url, { max: 1 })`. */
+    readonly openDatabase?: (url: string) => Promise<DatabaseHandle>;
+    readonly resolveTxt?: ResolveTxt;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly env?: Env;
+}
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+/** Pause between sends: Resend's default limit is two requests per second. */
+export declare const DEFAULT_PAUSE_MS = 500;
+export declare const MAIL_USAGE: string;
+/** Runs the command and returns the process exit code: 0 done, 1 failed or incomplete, 2 usage error. */
+export declare function runMailCli(options: RunMailCliOptions): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAWA,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrE,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnG,OAAO,EAAiF,KAAK,GAAG,EAAE,MAAM,+BAA+B,CAAC;AAExI,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,wGAAwG;IACxG,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;CACpB;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,eAAO,MAAM,UAAU,QAkBa,CAAC;AAYrC,yGAAyG;AACzG,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB5E"}