@visulima/email 1.0.0-alpha.34 → 1.0.0-alpha.35

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+## @visulima/email [1.0.0-alpha.35](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.34...@visulima/email@1.0.0-alpha.35) (2026-06-04)
+
+### Features
+
+* **email:** inbound, webhooks, deliverability, middleware, queue, events, testing + ARC/i18n/batch ([#671](https://github.com/visulima/visulima/issues/671)) ([2ca23f2](https://github.com/visulima/visulima/commit/2ca23f27ecc5064d693c16bd3f44ccaeaf050888))
+
+### Bug Fixes
+
+* **email:** 5 bug fixes ([4e87c42](https://github.com/visulima/visulima/commit/4e87c429a56d68d7a0a09325484ed299ffe6493c))
+* **lint:** clear pre-existing eslint rot across packages ([#674](https://github.com/visulima/visulima/issues/674)) ([5354253](https://github.com/visulima/visulima/commit/5354253b163bd50bcefaf8a3fddf831bdb5df32b))
+
+
+### Dependencies
+
+* **@visulima/disposable-email-domains:** upgraded to 1.0.0-alpha.16
+* **@visulima/error:** upgraded to 6.0.0-alpha.32
+* **@visulima/fs:** upgraded to 5.0.0-alpha.30
+* **@visulima/path:** upgraded to 3.0.0-alpha.12
+
 ## @visulima/email [1.0.0-alpha.34](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.33...@visulima/email@1.0.0-alpha.34) (2026-06-02)
 
 ### Features

package/README.md

@@ -1416,6 +1416,83 @@ normalizeEmailAliases("user+tag@gmx.com"); // "user@gmx.com"
 normalizeEmailAliases("user@example.com"); // "user@example.com"
 ```
 
+## Batch Sending & Result Helpers
+
+Send one message per recipient from a shared base, with optional per-recipient template rendering, via `mail.sendBatch(base, personalizations, options?)`. Every `send` returns a `Result<EmailResult>`; the `isOk`/`isErr`/`unwrap`/`unwrapOr`/`mapOk`/`tryAsync` helpers (exported from the root and `@visulima/email/utils/result`) make handling it ergonomic.
+
+```typescript
+import { createMail, isOk, unwrapOr } from "@visulima/email";
+
+const mail = createMail(provider);
+
+for await (const receipt of mail.sendBatch(
+    { from: { email: "news@example.com" }, subject: "Hi {{name}}", html: "<p>Hello {{name}}</p>" },
+    [{ to: { email: "a@example.com" }, data: { name: "Ada" } }],
+    { render: (template, data) => renderHandlebars(template, data) },
+)) {
+    if (receipt.successful) console.log("sent", receipt.messageId);
+}
+```
+
+See [Sending Mail](https://visulima.com/docs/package/email/getting-started/sending-mail).
+
+## Middleware
+
+Attach resilience middleware with `mail.use(...)`: retry (full-jitter backoff + dead-letter), rate limiting (with per-provider presets), circuit breaker, deduplication, OAuth2 token refresh, and PII-redacting logging.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { circuitBreakerMiddleware, RATE_LIMIT_PRESETS, rateLimitMiddleware, retryMiddleware } from "@visulima/email/middleware";
+
+const mail = createMail(provider)
+    .use(rateLimitMiddleware({ rate: RATE_LIMIT_PRESETS.resend }))
+    .use(circuitBreakerMiddleware())
+    .use(retryMiddleware({ retries: 3 }));
+```
+
+See [Middleware](https://visulima.com/docs/package/email/middleware/introduction).
+
+## Queue & Worker
+
+Durable background sending via the `EmailQueue` interface: an in-memory `MemoryQueue`, an `UnstorageQueue` (`@visulima/email/queue/unstorage`) backed by any [unstorage](https://unstorage.unjs.io/) store (Redis/FS/KV/Postgres), and a `createWorker(...)` with bounded concurrency, retry/backoff and dead-lettering.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { createWorker, MemoryQueue } from "@visulima/email/queue";
+
+const queue = new MemoryQueue();
+const mail = createMail(provider);
+
+await queue.enqueue({ from: { email: "a@x.com" }, to: { email: "b@x.com" }, subject: "Hi", text: "yo" });
+createWorker({ queue, send: mail.send.bind(mail), concurrency: 5 }).start();
+```
+
+See [Queue](https://visulima.com/docs/package/email/queue/introduction).
+
+## Webhook Verification
+
+Verify provider webhook signatures with `@visulima/email/webhooks`: `verifyStandardWebhook`/`verifyResendWebhook` (Svix/Standard Webhooks), `verifyMailgunWebhook`, `verifySendGridWebhook` (ECDSA + replay window), `verifyPostmarkWebhook` (Basic Auth), and `verifySnsMessage` (AWS SES via SNS, with a tight `sns.<region>.amazonaws.com` cert allowlist). All return `{ valid, reason? }` — always pass the **raw** request body.
+
+See [Webhooks](https://visulima.com/docs/package/email/webhooks/introduction).
+
+## Inbound Parsing
+
+Normalize inbound webhooks from Postmark, SendGrid, Mailgun, Cloudflare Email and SES into one `InboundEmail` shape, then strip quoted history with `extractReply()` (EN/DE/FR/ES/TR) and group conversations with `stitchThreads()`.
+
+See [Inbound](https://visulima.com/docs/package/email/inbound/introduction).
+
+## Deliverability
+
+2024 bulk-sender tooling in `@visulima/email/deliverability`: RFC 8058 one-click `buildListUnsubscribe`, suppression stores (`MemorySuppressionStore` + `filterSuppressed`), and parsers for DMARC records, MTA-STS policies, TLS-RPT records/reports, and ARF feedback-loop complaints. ARC sealing (`signArc`) lives in `@visulima/email/crypto`.
+
+See [Deliverability](https://visulima.com/docs/package/email/deliverability/introduction).
+
+## Events & Testing
+
+A unified `EmailEvent` stream (`EventBus` + `MemoryEventStore` in `@visulima/email/events`), and a test harness (`@visulima/email/test`): `createTestEmail()` plus Vitest matchers `toHaveSentTo` / `toHaveSentWithSubject` / `toHaveSentWithAttachment` / `toHaveSentMatching`.
+
+See [Events](https://visulima.com/docs/package/email/events/introduction) and [Testing](https://visulima.com/docs/package/email/testing/introduction).
+
 ## Related
 
 ## Supported Node.js Versions

package/dist/crypto/index.d.ts

@@ -1,7 +1,164 @@
-import { E as EmailOptions } from "../packem_shared/types.d-wwpgA3to.js";
-import { D as DkimOptions, E as EmailSigner, S as SmimeEncryptOptions, a as EmailEncrypter, b as SmimeSignOptions } from "../packem_shared/types.d-CNnnk-Ya.js";
+import { KeyObject } from 'node:crypto';
+import { E as EmailOptions } from "../packem_shared/types.d-ejzh-xBP.js";
+import { D as DkimOptions, E as EmailSigner, S as SmimeEncryptOptions, a as EmailEncrypter, b as SmimeSignOptions } from "../packem_shared/types.d-BId55FW2.js";
 import 'node:buffer';
 /**
+* The signature algorithm for the ARC headers. RSA per RFC 8617, Ed25519 per RFC 8463.
+*/
+type ArcAlgorithm = "ed25519-sha256" | "rsa-sha256";
+/**
+* Options for {@link signArc}.
+*/
+interface ArcSealOptions {
+  /**
+  * Signature algorithm (`a=`). `rsa-sha256` (default) or `ed25519-sha256` (RFC 8463).
+  * @default "rsa-sha256"
+  */
+  algorithm?: ArcAlgorithm;
+  /**
+  * The `Authentication-Results` value to chain (authserv-id plus method results),
+  * e.g. `example.com; spf=pass smtp.mailfrom=...; dkim=pass header.d=...`.
+  */
+  authenticationResults: string;
+  /**
+  * Chain validation status for the seal (`cv`). For an originating sealer (instance 1) this is
+  * always `none`.
+  * @default "none"
+  */
+  cv?: "fail" | "none" | "pass";
+  /**
+  * The signing domain (`d`).
+  */
+  domainName: string;
+  /**
+  * Lower-cased header names covered by the ARC-Message-Signature (`h`).
+  * @default from, to, cc, subject, date, message-id, mime-version
+  */
+  headersToSign?: string[];
+  /**
+  * The ARC instance number (`i`). Only `1` (originating sealer) is supported.
+  * @default 1
+  */
+  instance?: number;
+  /**
+  * The DKIM/ARC key selector (`s`).
+  */
+  keySelector: string;
+  /**
+  * Passphrase for an encrypted private key.
+  */
+  passphrase?: string;
+  /**
+  * Private key (PEM string, or a `file://` path). RSA or Ed25519 to match `algorithm`.
+  */
+  privateKey: string;
+  /**
+  * Signature timestamp (`t`) in unix seconds. Defaults to now.
+  */
+  timestamp?: number;
+}
+/**
+* The three ARC header fields produced for one instance.
+*/
+interface ArcHeaderSet {
+  "ARC-Authentication-Results": string;
+  "ARC-Message-Signature": string;
+  "ARC-Seal": string;
+}
+/**
+* Options for {@link verifyArc}.
+*/
+interface ArcVerifyOptions {
+  /**
+  * The ARC/DKIM public key for the signing domain+selector — a PEM string or a `KeyObject`. Look it
+  * up at `<selector>._domainkey.<d>` (the `p=` tag), decoded to SPKI.
+  */
+  publicKey: KeyObject | string;
+}
+/**
+* The outcome of {@link verifyArc}.
+*/
+interface ArcVerifyResult {
+  /**
+  * Per-component verification: the ARC-Message-Signature, the ARC-Seal, and the body hash.
+  */
+  components: {
+    ams: boolean;
+    bodyHash: boolean;
+    seal: boolean;
+  };
+  /**
+  * The chain-validation status (`cv`) from the ARC-Seal.
+  */
+  cv?: string;
+  /**
+  * A machine-readable reason when `valid` is `false`.
+  */
+  reason?: string;
+  /**
+  * Whether the whole instance verified (signature + seal + body hash).
+  */
+  valid: boolean;
+}
+/**
+* Computes the exact byte string that the ARC-Message-Signature `b=` value signs.
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param email The email being sealed.
+* @param options The seal options.
+* @returns The AMS header (without the `b=` value) and the data signed.
+*/
+declare const arcMessageSignatureBase: (email: EmailOptions, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Computes the exact byte string that the ARC-Seal `b=` value signs (for an originating, i=1 seal).
+*
+* Exposed so ARC verifiers (and tests) can re-derive the signing input.
+* @param aarValue The ARC-Authentication-Results value.
+* @param amsValue The full ARC-Message-Signature value (including its `b=` signature).
+* @param options The signing domain, selector, instance, timestamp and chain-validation status.
+* @returns The ARC-Seal header (without the `b=` value) and the data signed.
+*/
+declare const arcSealBase: (aarValue: string, amsValue: string, options: ArcSealOptions) => {
+  header: string;
+  signBase: string;
+};
+/**
+* Seals a message with an ARC (Authenticated Received Chain, RFC 8617) header set for an originating
+* sealer (instance `i=1`).
+*
+* Adds `ARC-Authentication-Results`, `ARC-Message-Signature`, and `ARC-Seal` headers. Use this when
+* your service forwards mail and wants downstream receivers to trust the authentication results you
+* observed. Supports RSA (default) and Ed25519 (`algorithm: "ed25519-sha256"`, RFC 8463) keys.
+*
+* IMPORTANT: the body hash (`bh=`) is computed over `text` + "\n\n" + `html` with relaxed
+* canonicalization — the same simplification as the DKIM signer. For a third-party ARC verifier to
+* accept the seal, the body actually transmitted on the wire must canonicalize to this same value, so
+* apply ARC at the point where the MIME body is finalized (or feed in the exact rendered body).
+* @param email The email to seal.
+* @param options The seal options. See {@link ArcSealOptions}.
+* @returns The email with the ARC header set added, and the raw {@link ArcHeaderSet}.
+* @throws {Error} When the private key cannot be loaded or signing fails.
+*/
+declare const signArc: (email: EmailOptions, options: ArcSealOptions) => Promise<{
+  email: EmailOptions;
+  headers: ArcHeaderSet;
+}>;
+/**
+* Verifies an originating (i=1) ARC header set against the signing domain's public key.
+*
+* Re-derives the AMS and ARC-Seal signing inputs from `email` + the supplied ARC headers, recomputes
+* the body hash, and checks all three. The public key must be the one published for the seal's
+* `s=`/`d=` (the DKIM-style `&lt;selector>._domainkey.&lt;domain>` TXT `p=` value).
+* @param email The message that was sealed (same fields used when signing).
+* @param headers The ARC header set (or any record containing the three `ARC-*` headers).
+* @param options Verification options. See {@link ArcVerifyOptions}.
+* @returns The verification result. See {@link ArcVerifyResult}.
+*/
+declare const verifyArc: (email: EmailOptions, headers: ArcHeaderSet | Record<string, string>, options: ArcVerifyOptions) => ArcVerifyResult;
+/**
 * DKIM signer implementation
 */
 declare class DkimSigner implements EmailSigner {
@@ -144,4 +301,4 @@ declare class SmimeSigner implements EmailSigner {
 * @returns A new SmimeSigner instance ready to sign emails.
 */
 declare const createSmimeSigner: (options: SmimeSignOptions) => SmimeSigner;
-export { type DkimOptions, DkimSigner, type EmailEncrypter, type EmailSigner, type SmimeEncryptOptions, SmimeEncrypter, type SmimeSignOptions, SmimeSigner, createDkimSigner, createSmimeEncrypter, createSmimeSigner };
+export { type ArcAlgorithm, type ArcHeaderSet, type ArcSealOptions, type ArcVerifyOptions, type ArcVerifyResult, type DkimOptions, DkimSigner, type EmailEncrypter, type EmailSigner, type SmimeEncryptOptions, SmimeEncrypter, type SmimeSignOptions, SmimeSigner, arcMessageSignatureBase, arcSealBase, createDkimSigner, createSmimeEncrypter, createSmimeSigner, signArc, verifyArc };

package/dist/crypto/index.js

@@ -1 +1 @@
-import{DkimSigner as m,createDkimSigner as i}from"../packem_shared/DkimSigner-CT2DSHD1.js";import{SmimeEncrypter as S,createSmimeEncrypter as n}from"../packem_shared/SmimeEncrypter-ZhHEgDwY.js";import{SmimeSigner as c,createSmimeSigner as p}from"../packem_shared/SmimeSigner-CYSVF6ez.js";export{m as DkimSigner,S as SmimeEncrypter,c as SmimeSigner,i as createDkimSigner,n as createSmimeEncrypter,p as createSmimeSigner};
+import{arcMessageSignatureBase as m,arcSealBase as i,signArc as a,verifyArc as t}from"../packem_shared/arcMessageSignatureBase-Cpdnv-H8.js";import{DkimSigner as c,createDkimSigner as n}from"../packem_shared/DkimSigner-dKZ45Csc.js";import{SmimeEncrypter as g,createSmimeEncrypter as p}from"../packem_shared/SmimeEncrypter-BirIsrip.js";import{SmimeSigner as s,createSmimeSigner as x}from"../packem_shared/SmimeSigner-CkyaShTs.js";export{c as DkimSigner,g as SmimeEncrypter,s as SmimeSigner,m as arcMessageSignatureBase,i as arcSealBase,n as createDkimSigner,p as createSmimeEncrypter,x as createSmimeSigner,a as signArc,t as verifyArc};

package/dist/deliverability/dmarc-report.d.ts

@@ -0,0 +1,95 @@
+/**
+* A DKIM/SPF auth result inside a DMARC aggregate record.
+*/
+interface DmarcAuthResult {
+  domain?: string;
+  result?: string;
+}
+/**
+* One `<record>` row of a DMARC aggregate report.
+*/
+interface DmarcRecordRow {
+  /**
+  * The per-mechanism auth results.
+  */
+  authResults: {
+    dkim: DmarcAuthResult[];
+    spf: DmarcAuthResult[];
+  };
+  /**
+  * Number of messages this row represents.
+  */
+  count: number;
+  /**
+  * The policy disposition applied (`none` / `quarantine` / `reject`).
+  */
+  disposition?: string;
+  /**
+  * The DKIM alignment result (`pass` / `fail`).
+  */
+  dkim?: string;
+  /**
+  * The `From:` header domain.
+  */
+  headerFrom?: string;
+  /**
+  * The source IP that sent the messages.
+  */
+  sourceIp?: string;
+  /**
+  * The SPF alignment result (`pass` / `fail`).
+  */
+  spf?: string;
+}
+/**
+* A parsed DMARC aggregate (RUA) report.
+*/
+interface DmarcAggregateReport {
+  /**
+  * Report window start (`date_range.begin`, unix seconds as a string).
+  */
+  dateRangeBegin?: string;
+  /**
+  * Report window end (`date_range.end`, unix seconds as a string).
+  */
+  dateRangeEnd?: string;
+  /**
+  * The reporter's contact email.
+  */
+  email?: string;
+  /**
+  * The reporting organization.
+  */
+  organizationName?: string;
+  /**
+  * The published policy the report was evaluated against.
+  */
+  policyPublished?: {
+    adkim?: string;
+    aspf?: string;
+    domain?: string;
+    p?: string;
+    pct?: number;
+    sp?: string;
+  };
+  /**
+  * The per-source rows.
+  */
+  records: DmarcRecordRow[];
+  /**
+  * The unique report id.
+  */
+  reportId?: string;
+}
+/**
+* Parses a DMARC aggregate (RUA) report XML document into a structured object.
+*
+* Reports arrive gzipped/zipped — decompress to the XML string first. `fast-xml-parser` is an optional
+* peer dependency (`pnpm add fast-xml-parser`), loaded only via this `./deliverability/dmarc-report`
+* entry point so the rest of the deliverability tooling stays dependency-free.
+* @param xml The DMARC aggregate report XML.
+* @returns The parsed report. See {@link DmarcAggregateReport}.
+* @throws {EmailError} When `fast-xml-parser` is not installed or the XML cannot be parsed.
+*/
+declare const parseDmarcReport: (xml: string) => Promise<DmarcAggregateReport>;
+export { type DmarcAggregateReport, type DmarcAuthResult, type DmarcRecordRow, parseDmarcReport };

package/dist/deliverability/dmarc-report.js

@@ -0,0 +1 @@
+var R=Object.defineProperty;var f=(e,t)=>R(e,"name",{value:t,configurable:!0});import m from"../packem_shared/EmailError-zm2ffVav.js";var v=Object.defineProperty,o=f((e,t)=>v(e,"name",{value:t,configurable:!0}),"a");const b=o(e=>e==null?[]:Array.isArray(e)?e:[e],"toArray"),r=o(e=>{if(typeof e=="string")return e;if(typeof e=="number"||typeof e=="boolean")return String(e)},"asString"),g=o(e=>{const t=r(e);if(t===void 0)return;const i=Number(t);return Number.isNaN(i)?void 0:i},"asNumber"),y=o(e=>b(e).map(t=>({domain:r(t.domain),result:r(t.result)})),"toAuthResults"),k=o(async e=>{let t;try{({XMLParser:t}=await import("fast-xml-parser"))}catch(a){throw a instanceof Error&&(a.code==="ERR_MODULE_NOT_FOUND"||a.message.includes("Cannot find module")||a.message.includes("Cannot find package"))?new m("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:a}):new m("deliverability",`Failed to load fast-xml-parser: ${a.message}`,{cause:a})}let i;try{i=new t({ignoreAttributes:!0,parseTagValue:!1}).parse(e)}catch(a){throw new m("deliverability",`Failed to parse DMARC report: ${a.message}`,{cause:a})}const d=i.feedback??{},n=d.report_metadata??{},u=n.date_range??{},s=d.policy_published??{},h=b(d.record).map(a=>{const p=a.row??{},l=p.policy_evaluated??{},_=a.identifiers??{},c=a.auth_results??{};return{authResults:{dkim:y(c.dkim),spf:y(c.spf)},count:g(p.count)??0,disposition:r(l.disposition),dkim:r(l.dkim),headerFrom:r(_.header_from),sourceIp:r(p.source_ip),spf:r(l.spf)}});return{dateRangeBegin:r(u.begin),dateRangeEnd:r(u.end),email:r(n.email),organizationName:r(n.org_name),policyPublished:{adkim:r(s.adkim),aspf:r(s.aspf),domain:r(s.domain),p:r(s.p),pct:g(s.pct),sp:r(s.sp)},records:h,reportId:r(n.report_id)}},"parseDmarcReport");export{k as parseDmarcReport};