@visulima/email 1.0.0-alpha.4 → 1.0.0-alpha.41

package/README.md

@@ -114,6 +114,46 @@ const message = new MailMessage().to("user@example.com").subject("Hello").html("
 await mail.send(message);
 ```
 
+### Capability Guard (fail-fast field support)
+
+Every provider declares which capabilities it supports through its `features` flags (attachments, tagging, scheduling, HTML, custom headers, reply-to, templates, ...). Before a message is handed to the provider, `Mail` runs a fail-fast check: if the message uses a capability the provider has **explicitly** declared unsupported (`features[x] === false`), the send is rejected locally — no wasted network round-trip and no silent data loss.
+
+```typescript
+import { createMail } from "@visulima/email";
+import { awsSesProvider } from "@visulima/email/providers/aws-ses";
+
+// AWS SES declares `tagging: false`
+const mail = createMail(awsSesProvider({ accessKeyId, secretAccessKey, region }));
+
+const result = await mail.send({
+    from: { email: "noreply@example.com" },
+    subject: "Hi",
+    tags: ["promo"], // not representable by AWS SES
+    text: "Body",
+    to: { email: "user@example.com" },
+});
+
+result.success; // false
+(result.error as { code?: string }).code; // "UNSUPPORTED_FEATURES"
+```
+
+Capabilities left `undefined` are treated as "unknown" and never rejected, so providers that publish a partial (or no) `features` map are never falsely blocked. The behaviour is configurable per `Mail` instance:
+
+```typescript
+createMail(provider, { featureCheck: "error" }); // default — reject unsupported fields
+createMail(provider, { featureCheck: "warn" }); // log a warning and send anyway
+createMail(provider, { featureCheck: "off" }); // skip the check entirely
+```
+
+You can also run the check standalone (e.g. inside a custom provider):
+
+```typescript
+import { checkFeatureSupport } from "@visulima/email";
+// or the focused entry point: "@visulima/email/validation/check-feature-support"
+
+const { supported, violations } = checkFeatureSupport(message, provider.features);
+```
+
 ### Creating Draft Emails
 
 You can create draft emails in EML (RFC 822) format without sending them. The `draft()` method returns the email as an EML string with an `X-Unsent: 1` header automatically added:
@@ -159,11 +199,7 @@ const smtpMail = createMail(smtp);
 const resendMail = createMail(resend);
 
 // Send via specific provider
-const message = new MailMessage()
-    .to("user@example.com")
-    .from("sender@example.com")
-    .subject("Hello")
-    .html("<h1>Hello World</h1>");
+const message = new MailMessage().to("user@example.com").from("sender@example.com").subject("Hello").html("<h1>Hello World</h1>");
 
 await resendMail.send(message);
 ```
@@ -876,6 +912,70 @@ const sendGridOptions: SendGridEmailOptions = {
 await mail.send(sendGridOptions);
 ```
 
+### SparkPost Provider
+
+SparkPost is a high-volume email delivery service. Universal runtime (Fetch API).
+
+```typescript
+import { createMail, sparkpostProvider } from "@visulima/email/providers/sparkpost";
+
+const mail = createMail(
+    sparkpostProvider({
+        apiKey: "your-sparkpost-api-key",
+        endpoint: "https://api.sparkpost.com/api/v1", // or https://api.eu.sparkpost.com/api/v1 (EU)
+    }),
+);
+
+await mail.send({
+    from: { email: "sender@example.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+    // SparkPost-specific: campaignId, templateId, trackOpens, trackClicks
+});
+```
+
+### Netcore Provider
+
+Netcore (formerly Pepipost) transactional email via the Email API v5.1. Universal runtime (Fetch API).
+
+```typescript
+import { createMail, netcoreProvider } from "@visulima/email/providers/netcore";
+
+const mail = createMail(netcoreProvider({ apiKey: "your-netcore-api-key" }));
+
+await mail.send({
+    from: { email: "sender@example.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+    // Netcore-specific: templateId, templateData
+});
+```
+
+### Outlook365 Provider
+
+Sends through Microsoft Graph `sendMail`. Universal runtime (Fetch API). Bring your own OAuth2 token (`Mail.Send` scope)
+via `accessToken` or `getAccessToken` — no auth SDK is bundled.
+
+```typescript
+import { createMail, outlook365Provider } from "@visulima/email/providers/outlook365";
+
+const mail = createMail(
+    outlook365Provider({
+        getAccessToken: async () => getGraphAccessToken(),
+        userId: "sender@contoso.com", // or "me" (default)
+    }),
+);
+
+await mail.send({
+    from: { email: "sender@contoso.com" },
+    to: { email: "user@example.com" },
+    subject: "Welcome",
+    html: "<h1>Welcome!</h1>",
+});
+```
+
 ### Plunk Provider
 
 Plunk is a modern email platform built on top of AWS SES, offering transactional emails, automations, and broadcasts.
@@ -1033,6 +1133,9 @@ const result = await mail.send(message);
 - **Round Robin** - Load balancing across multiple providers
 - **OpenTelemetry** - OpenTelemetry instrumentation wrapper for observability
 - **SendGrid** - Cloud-based email service for transactional and marketing emails
+- **SparkPost** - SparkPost Transmissions API
+- **Netcore** - Netcore (Pepipost) Email API
+- **Outlook365** - Microsoft Graph (Outlook365) `sendMail`
 - **SMTP** - Standard SMTP protocol
 - **Zeptomail** - Zeptomail email service
 
@@ -1063,6 +1166,9 @@ These providers work in **Node.js**, **Deno**, **Bun**, and **Cloudflare Workers
 - ✅ **Mailomat** - Uses Fetch API
 - ✅ **Sweego** - Uses Fetch API
 - ✅ **SendGrid** - Uses Fetch API
+- ✅ **SparkPost** - Uses Fetch API
+- ✅ **Netcore** - Uses Fetch API
+- ✅ **Outlook365** - Uses Fetch API (Microsoft Graph; bring your own OAuth2 token)
 - ✅ **Plunk** - Uses Fetch API
 - ✅ **Mock** - In-memory provider, works everywhere
 - ✅ **Failover** - Runtime depends on wrapped providers (works if all wrapped providers support the runtime)
@@ -1380,6 +1486,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,4 +1,304 @@
-export { createDkimSigner, DkimSigner } from "./dkim-signer.d.ts";
-export { createSmimeEncrypter, SmimeEncrypter } from "./smime-encrypter.d.ts";
-export { createSmimeSigner, SmimeSigner } from "./smime-signer.d.ts";
-export type { DkimOptions, EmailEncrypter, EmailSigner, SmimeEncryptOptions, SmimeSignOptions } from "./types.d.ts";
+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 {
+  /**
+  * Sanitizes a display name for use in quoted email headers per RFC 5322.
+  * Removes/replaces CR, LF, tabs with space, escapes backslashes and quotes,
+  * and strips non-printable control characters.
+  * @param name The display name to sanitize.
+  * @returns The sanitized display name, or empty string if nothing remains.
+  */
+  private static sanitizeDisplayName;
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address object to format.
+  * @param address.email The email address string.
+  * @param address.name Optional display name for the email address.
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  /**
+  * Formats email addresses for headers.
+  * @param addresses The email address(es) to format (single or array).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private static formatAddresses;
+  private readonly options;
+  /**
+  * Creates a new DKIM signer.
+  * @param options DKIM signing options.
+  */
+  constructor(options: DkimOptions);
+  /**
+  * Signs an email message with DKIM.
+  * @param email The email options to sign.
+  * @returns The email options with DKIM signature header added.
+  * @throws {Error} When signing fails (e.g., invalid private key).
+  */
+  sign(email: EmailOptions): Promise<EmailOptions>;
+}
+/**
+* Creates a DKIM signer instance.
+* @param options DKIM signing options.
+* @returns A new DkimSigner instance.
+*/
+declare const createDkimSigner: (options: DkimOptions) => DkimSigner;
+/**
+* S/MIME encrypter implementation using PKIjs
+* Note: Requires pkijs and asn1js for S/MIME operations
+* Uses Node.js crypto for all cryptographic operations
+*/
+declare class SmimeEncrypter implements EmailEncrypter {
+  /**
+  * Collects and normalizes all recipients (to, cc, bcc) from email options.
+  * Normalizes each to an array, extracts email addresses, and deduplicates.
+  * @param email The email options containing recipients.
+  * @returns An array of unique email addresses (strings).
+  */
+  private static collectRecipients;
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address to format (string or EmailAddress object).
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  /**
+  * Formats email addresses for use in email headers.
+  * @param addresses The email addresses to format (single or array, string or EmailAddress objects).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private static formatAddresses;
+  private readonly options;
+  /**
+  * Creates a new S/MIME encrypter.
+  * @param options S/MIME encryption options.
+  */
+  constructor(options: SmimeEncryptOptions);
+  /**
+  * Encrypts an email message with S/MIME.
+  * @param email The email options to encrypt.
+  * @returns The encrypted email options.
+  * @throws {Error} When encryption fails (e.g., invalid certificate).
+  */
+  encrypt(email: EmailOptions): Promise<EmailOptions>;
+  /**
+  * Builds the email message string from email options.
+  * @param email The email options to build the message from.
+  * @returns The formatted email message as a string.
+  */
+  private buildMessage;
+}
+/**
+* Creates a new S/MIME encrypter instance.
+* @param options The S/MIME encryption options.
+* @returns A new SmimeEncrypter instance ready to encrypt emails.
+*/
+declare const createSmimeEncrypter: (options: SmimeEncryptOptions) => SmimeEncrypter;
+/**
+* S/MIME signer implementation using PKIjs
+* Note: Requires pkijs and asn1js for S/MIME operations
+* Uses Node.js crypto for all cryptographic operations
+*/
+declare class SmimeSigner implements EmailSigner {
+  /**
+  * Formats an email address for use in email headers.
+  * @param address The email address object to format.
+  * @param address.email The email address string.
+  * @param address.name Optional display name for the email address.
+  * @returns The formatted email address string in RFC 5322 format.
+  */
+  private static formatAddress;
+  private readonly options;
+  /**
+  * Creates a new S/MIME signer.
+  * @param options S/MIME signing options.
+  */
+  constructor(options: SmimeSignOptions);
+  /**
+  * Signs an email message with S/MIME.
+  * @param email The email options to sign.
+  * @returns The email options with S/MIME signature.
+  * @throws {Error} When signing fails (e.g., invalid certificate/key).
+  */
+  sign(email: EmailOptions): Promise<EmailOptions>;
+  /**
+  * Builds the email message string from email options.
+  * @param email The email options to build the message from.
+  * @returns The formatted email message as a string.
+  */
+  private buildMessage;
+  /**
+  * Formats email addresses for use in email headers.
+  * @param addresses The email addresses to format (single or array).
+  * @returns The formatted email addresses string (comma-separated if multiple).
+  */
+  private formatAddresses;
+}
+/**
+* Creates a new S/MIME signer instance.
+* @param options The S/MIME signing options.
+* @returns A new SmimeSigner instance ready to sign emails.
+*/
+declare const createSmimeSigner: (options: SmimeSignOptions) => SmimeSigner;
+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-pFd4c3fZ.js";import{SmimeEncrypter as S,createSmimeEncrypter as n}from"../packem_shared/SmimeEncrypter-CBevU534.js";import{SmimeSigner as c,createSmimeSigner as p}from"../packem_shared/SmimeSigner-CObA4jzT.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};