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

package/CHANGELOG.md

@@ -1,3 +1,56 @@
+## @visulima/email [1.0.0-alpha.36](https://github.com/visulima/visulima/compare/@visulima/email@1.0.0-alpha.35...@visulima/email@1.0.0-alpha.36) (2026-06-13)
+
+### Bug Fixes
+
+* **email:** harden header sanitization, DSN fallback header, batch counts ([5629850](https://github.com/visulima/visulima/commit/5629850e2fe23710bc11d71820c867e5952c9a1d))
+* **email:** stop bcc disclosure and fix mime header/dsn handling ([70f0c70](https://github.com/visulima/visulima/commit/70f0c70fe441be5ba9cf15b3e94acbe7cc7af3c2))
+* **email:** unwrap juice ESM default export and align fs error expectation ([0bc2705](https://github.com/visulima/visulima/commit/0bc2705af39a0da641eb50a4e85eff0f954f267e))
+
+### Performance Improvements
+
+* **email:** lazy-load ical-generator on build ([b6b4466](https://github.com/visulima/visulima/commit/b6b4466d87ddaaed19e5726bef4583bf433403d0))
+
+### Miscellaneous Chores
+
+* **email:** clear baseline eslint violations ([1906b0b](https://github.com/visulima/visulima/commit/1906b0bed81cba8d979aa55b5e5d8518263b7b7b))
+
+### Tests
+
+* **email:** deepen middleware/queue/events tests ([be80a72](https://github.com/visulima/visulima/commit/be80a725e20661b24650f13b6b524891811b8af8))
+* **email:** restore precise toHaveBeenCalledWith assertions ([524d4bd](https://github.com/visulima/visulima/commit/524d4bd545c7440e1d26fbb201706a1a0bdc8023))
+
+### Build System
+
+* **deps:** update email dependencies ([5ce1f27](https://github.com/visulima/visulima/commit/5ce1f27ebecb9f7459db7503e4a8128b1ff8ac01))
+* regenerate bundled-license manifests and types ordering ([af26588](https://github.com/visulima/visulima/commit/af26588d75aaa937fd4862800560bd4070a4878c))
+
+
+### Dependencies
+
+* **@visulima/disposable-email-domains:** upgraded to 1.0.0-alpha.17
+* **@visulima/error:** upgraded to 6.0.0-alpha.33
+* **@visulima/fs:** upgraded to 5.0.0-alpha.32
+* **@visulima/path:** upgraded to 3.0.0-alpha.13
+
+## @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/LICENSE.md

@@ -459,6 +459,35 @@ Repository: git+https://github.com/visulima/visulima.git
 >
 > ---------------------------------------
 >
+> ## tinyglobby
+> License: MIT
+> By: Superchupu
+> Repository: git+https://github.com/SuperchupuDev/tinyglobby.git
+>
+> > MIT License
+> >
+> > Copyright (c) 2024 Madeline Gurriarán
+> >
+> > 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.
+>
+> ---------------------------------------
+>
 > ## yaml
 > License: ISC
 > By: Eemeli Aro
@@ -900,4 +929,32 @@ Repository: git+https://github.com/visulima/visulima.git
 > > See the License for the specific language governing permissions and
 > > limitations under the License.
 
+---------------------------------------
+
+## unstorage
+License: MIT
+Repository: unjs/unstorage
+
+> MIT License
+>
+> Copyright (c) Pooya Parsa <pooya@pi0.io>
+>
+> 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.
+
 <!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -1416,6 +1416,102 @@ 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).
+
+## Crypto (DKIM / S/MIME / ARC)
+
+Sign and encrypt messages with `@visulima/email/crypto`: `createDkimSigner` (DKIM-Signature header), `createSmimeSigner` / `createSmimeEncrypter` (S/MIME sign and encrypt, via the optional `pkijs` + `asn1js` peers), and `signArc` / `verifyArc` for ARC sealing on forwarded mail. Attach signers/encrypters to a `MailMessage` with `.sign(...)` / `.encrypt(...)`.
+
+```typescript
+import { MailMessage } from "@visulima/email";
+import { createDkimSigner } from "@visulima/email/crypto";
+
+const signer = createDkimSigner({
+    domainName: "example.com",
+    keySelector: "default",
+    privateKey: "file:///path/to/dkim.private.key", // or an inline PEM string
+});
+
+const message = new MailMessage().from({ email: "a@example.com" }).to({ email: "b@example.com" }).subject("Signed").html("<p>Hello</p>").sign(signer); // DKIM-Signature is added during build()
+```
+
+See [Crypto](https://visulima.com/docs/package/email/crypto/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-BY4j0TxM.js";import{DkimSigner as c,createDkimSigner as n}from"../packem_shared/DkimSigner-BuSbnos1.js";import{SmimeEncrypter as g,createSmimeEncrypter as p}from"../packem_shared/SmimeEncrypter-C7usORKF.js";import{SmimeSigner as s,createSmimeSigner as x}from"../packem_shared/SmimeSigner-DgAApLPS.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 @@
+import l from"../packem_shared/EmailError-B-sEf3bp.js";const g=a=>a==null?[]:Array.isArray(a)?a:[a],e=a=>{if(typeof a=="string")return a;if(typeof a=="number"||typeof a=="boolean")return String(a)},c=a=>{const r=e(a);if(r===void 0)return;const s=Number(r);return Number.isNaN(s)?void 0:s},f=a=>g(a).map(r=>({domain:e(r.domain),result:e(r.result)})),h=async a=>{let r;try{({XMLParser:r}=await import("fast-xml-parser"))}catch(t){throw t instanceof Error&&(t.code==="ERR_MODULE_NOT_FOUND"||t.message.includes("Cannot find module")||t.message.includes("Cannot find package"))?new l("deliverability","fast-xml-parser is not installed. Please install it: pnpm add fast-xml-parser",{cause:t}):new l("deliverability",`Failed to load fast-xml-parser: ${t.message}`,{cause:t})}let s;try{s=new r({ignoreAttributes:!0,parseTagValue:!1}).parse(a)}catch(t){throw new l("deliverability",`Failed to parse DMARC report: ${t.message}`,{cause:t})}const n=s.feedback??{},o=n.report_metadata??{},m=o.date_range??{},i=n.policy_published??{},y=g(n.record).map(t=>{const d=t.row??{},p=d.policy_evaluated??{},b=t.identifiers??{},u=t.auth_results??{};return{authResults:{dkim:f(u.dkim),spf:f(u.spf)},count:c(d.count)??0,disposition:e(p.disposition),dkim:e(p.dkim),headerFrom:e(b.header_from),sourceIp:e(d.source_ip),spf:e(p.spf)}});return{dateRangeBegin:e(m.begin),dateRangeEnd:e(m.end),email:e(o.email),organizationName:e(o.org_name),policyPublished:{adkim:e(i.adkim),aspf:e(i.aspf),domain:e(i.domain),p:e(i.p),pct:c(i.pct),sp:e(i.sp)},records:y,reportId:e(o.report_id)}};export{h as parseDmarcReport};