@visulima/email 1.0.0-alpha.8 → 1.0.0

package/dist/deliverability/index.d.ts

@@ -0,0 +1,360 @@
+import { c as EmailAddress } from "../packem_shared/types.d-ejzh-xBP.js";
+import { S as SuppressionReason, a as SuppressionEntry, b as SuppressionStore } from "../packem_shared/types.d-CmoWvdZi.js";
+import 'node:buffer';
+/**
+* A parsed [ARF](https://www.rfc-editor.org/rfc/rfc5965) (Abuse Reporting Format) feedback report,
+* as delivered by mailbox-provider feedback loops (FBLs) on spam complaints.
+*/
+interface ArfReport {
+  /**
+  * When the offending message arrived, if reported.
+  */
+  arrivalDate?: string;
+  /**
+  * The type of feedback — `abuse` for spam complaints, `auth-failure`, `fraud`, etc.
+  */
+  feedbackType?: string;
+  /**
+  * All parsed fields from the `message/feedback-report` part, lower-cased keys.
+  */
+  fields: Record<string, string>;
+  /**
+  * The envelope sender of the original message, if reported.
+  */
+  originalMailFrom?: string;
+  /**
+  * The recipient(s) that complained — the address(es) to suppress.
+  */
+  originalRcptTo?: string;
+  /**
+  * The domain the report concerns.
+  */
+  reportedDomain?: string;
+  /**
+  * The source IP of the original message, if reported.
+  */
+  sourceIp?: string;
+}
+/**
+* Parses an ARF feedback-loop complaint report into a structured object.
+*
+* Pass either the full raw ARF email or just its `message/feedback-report` part. Use
+* {@link ArfReport.originalRcptTo} to drive suppression of complaining recipients.
+* @param raw The raw ARF email text.
+* @returns The parsed report. See {@link ArfReport}.
+*/
+declare const parseArfReport: (raw: string) => ArfReport;
+/**
+* A parsed DMARC DNS policy record (the `_dmarc.&lt;domain>` TXT record).
+*/
+interface DmarcRecord {
+  /**
+  * DKIM identifier alignment: `r` (relaxed, default) or `s` (strict).
+  */
+  adkim?: "r" | "s";
+  /**
+  * SPF identifier alignment: `r` (relaxed, default) or `s` (strict).
+  */
+  aspf?: "r" | "s";
+  /**
+  * Failure reporting options (`fo`): `0`, `1`, `d`, `s`, or a colon-joined combination.
+  */
+  fo?: string;
+  /**
+  * Percentage of messages the policy applies to (`pct`, 0–100).
+  */
+  percent?: number;
+  /**
+  * Requested policy (`p`): `none`, `quarantine`, or `reject`.
+  */
+  policy?: "none" | "quarantine" | "reject";
+  /**
+  * Aggregate report URIs (`rua`).
+  */
+  rua?: string[];
+  /**
+  * Failure (forensic) report URIs (`ruf`).
+  */
+  ruf?: string[];
+  /**
+  * Subdomain policy (`sp`).
+  */
+  subdomainPolicy?: "none" | "quarantine" | "reject";
+  /**
+  * All raw tag/value pairs, keyed by tag.
+  */
+  tags: Record<string, string>;
+  /**
+  * Whether the record is a syntactically valid DMARC1 record (starts with `v=DMARC1`).
+  */
+  valid: boolean;
+}
+/**
+* Parses a DMARC policy record (the TXT record at `_dmarc.&lt;domain>`).
+* @param record The raw TXT record value (e.g. `v=DMARC1; p=reject; rua=mailto:agg@example.com`).
+* @returns The parsed record. See {@link DmarcRecord}.
+*/
+declare const parseDmarcRecord: (record: string) => DmarcRecord;
+/**
+* Options for {@link buildListUnsubscribe}.
+*/
+interface ListUnsubscribeOptions {
+  /**
+  * A `mailto:` target the recipient can email to unsubscribe.
+  *
+  * Provide a bare address (`unsub@example.com`) or a full `mailto:` URI with query parameters.
+  */
+  mailto?: string;
+  /**
+  * The default `subject` to attach to a bare `mailto` address.
+  * @default "unsubscribe"
+  */
+  mailtoSubject?: string;
+  /**
+  * Enable [RFC 8058](https://www.rfc-editor.org/rfc/rfc8058) one-click unsubscribe.
+  *
+  * Requires {@link ListUnsubscribeOptions.url} to be an `https:` endpoint that accepts a POST with
+  * the body `List-Unsubscribe=One-Click`.
+  * @default false
+  */
+  oneClick?: boolean;
+  /**
+  * An `https:` URL the recipient (or their mail client) can use to unsubscribe.
+  */
+  url?: string;
+}
+/**
+* The headers produced by {@link buildListUnsubscribe}.
+*/
+interface ListUnsubscribeHeaders {
+  "List-Unsubscribe": string;
+  "List-Unsubscribe-Post"?: string;
+}
+/**
+* Builds `List-Unsubscribe` (and, when requested, `List-Unsubscribe-Post`) headers.
+*
+* Gmail and Yahoo's 2024 bulk-sender requirements expect bulk senders to expose a one-click
+* unsubscribe. Pass an `https:` {@link ListUnsubscribeOptions.url} with `oneClick: true` to emit the
+* RFC 8058 `List-Unsubscribe-Post: List-Unsubscribe=One-Click` header alongside it.
+* @param options At least one of `url` or `mailto` must be provided. See {@link ListUnsubscribeOptions}.
+* @returns The header record to merge into an email's headers.
+* @throws {TypeError} When neither `url` nor `mailto` is provided, or `oneClick` is set without an `https:` url.
+* @example
+* ```ts
+* const headers = buildListUnsubscribe({
+*   url: "https://example.com/unsub?id=abc",
+*   mailto: "unsubscribe@example.com",
+*   oneClick: true,
+* });
+* // {
+* //   "List-Unsubscribe": "<https://example.com/unsub?id=abc>, <mailto:unsubscribe@example.com?subject=unsubscribe>",
+* //   "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
+* // }
+* ```
+*/
+declare const buildListUnsubscribe: (options: ListUnsubscribeOptions) => ListUnsubscribeHeaders;
+/**
+* Parses a `List-Unsubscribe` header value into its individual targets.
+* @param header The raw `List-Unsubscribe` header value containing angle-bracketed targets.
+* @returns The list of unwrapped targets (URLs / mailto URIs).
+*/
+declare const parseListUnsubscribe: (header: string) => string[];
+/**
+* A parsed [MTA-STS](https://www.rfc-editor.org/rfc/rfc8461) policy
+* (`https://mta-sts.&lt;domain>/.well-known/mta-sts.txt`).
+*/
+interface MtaStsPolicy {
+  /**
+  * Maximum policy lifetime in seconds (`max_age`).
+  */
+  maxAge?: number;
+  /**
+  * Enforcement mode: `enforce`, `testing`, or `none`.
+  */
+  mode?: "enforce" | "none" | "testing";
+  /**
+  * Allowed MX host patterns (may include a leading `*.` wildcard).
+  */
+  mx: string[];
+  /**
+  * Whether the policy is a syntactically valid `STSv1` policy.
+  */
+  valid: boolean;
+  /**
+  * The policy version (`STSv1`).
+  */
+  version?: string;
+}
+/**
+* Parses an MTA-STS policy file.
+* @param policy The raw policy text.
+* @returns The parsed policy. See {@link MtaStsPolicy}.
+*/
+declare const parseMtaStsPolicy: (policy: string) => MtaStsPolicy;
+/**
+* Input for {@link buildMtaStsPolicy}.
+*/
+interface MtaStsPolicyInput {
+  /**
+  * Maximum policy lifetime in seconds (`max_age`), e.g. `604800` (one week).
+  */
+  maxAge: number;
+  /**
+  * Enforcement mode.
+  */
+  mode: "enforce" | "none" | "testing";
+  /**
+  * Allowed MX host patterns (a leading `*.` wildcard is permitted).
+  */
+  mx: string[];
+}
+/**
+* Generates an MTA-STS policy file to serve at `https://mta-sts.&lt;domain>/.well-known/mta-sts.txt`.
+* @param input The policy contents. See {@link MtaStsPolicyInput}.
+* @returns The policy file text (CRLF-terminated lines, per RFC 8461).
+*/
+declare const buildMtaStsPolicy: (input: MtaStsPolicyInput) => string;
+/**
+* An in-memory {@link SuppressionStore}, suitable for tests, single-process apps, and as a write-through
+* cache in front of a durable store.
+*/
+declare class MemorySuppressionStore implements SuppressionStore {
+  private readonly entries;
+  /**
+  * Seeds the store with existing entries.
+  * @param initial Optional addresses to pre-suppress.
+  */
+  constructor(initial?: Iterable<{
+    address: string;
+    metadata?: Record<string, unknown>;
+    reason: SuppressionReason;
+  }>);
+  /**
+  * Adds or refreshes an address on the suppression list.
+  * @param address The recipient address.
+  * @param reason Why it is suppressed.
+  * @param metadata Optional context to persist with the entry.
+  */
+  add(address: string, reason: SuppressionReason, metadata?: Record<string, unknown>): void;
+  /**
+  * Returns the suppression entry for an address, if present.
+  * @param address The recipient address.
+  * @returns The entry, or `undefined` when not suppressed.
+  */
+  get(address: string): SuppressionEntry | undefined;
+  /**
+  * Reports whether an address is currently suppressed.
+  * @param address The recipient address.
+  * @returns `true` when the address is on the list.
+  */
+  has(address: string): boolean;
+  /**
+  * Lists every suppression entry.
+  * @returns An iterable over the stored entries.
+  */
+  list(): Iterable<SuppressionEntry>;
+  /**
+  * Removes an address from the suppression list.
+  * @param address The recipient address.
+  * @returns `true` when an entry was removed.
+  */
+  remove(address: string): boolean;
+  /**
+  * The number of suppressed addresses.
+  */
+  get size(): number;
+}
+/**
+* Result of {@link filterSuppressed}.
+*/
+interface FilterSuppressedResult {
+  /**
+  * Recipients that are allowed (not suppressed).
+  */
+  allowed: EmailAddress[];
+  /**
+  * Recipients that were suppressed and removed.
+  */
+  suppressed: EmailAddress[];
+}
+/**
+* Partitions a recipient list into allowed and suppressed addresses.
+* @param recipients One or more recipients.
+* @param store The suppression store to check against.
+* @returns The allowed and suppressed recipients. See {@link FilterSuppressedResult}.
+*/
+declare const filterSuppressed: (recipients: EmailAddress | EmailAddress[], store: SuppressionStore) => Promise<FilterSuppressedResult>;
+/**
+* Convenience factory for an in-memory suppression store.
+* @param initial Optional addresses to pre-suppress.
+* @returns A new {@link MemorySuppressionStore}.
+*/
+declare const createSuppressionStore: (initial?: Iterable<{
+  address: string;
+  metadata?: Record<string, unknown>;
+  reason: SuppressionReason;
+}>) => MemorySuppressionStore;
+/**
+* A parsed TLS-RPT DNS record (`_smtp._tls.&lt;domain>` TXT record).
+*/
+interface TlsRptRecord {
+  /**
+  * Report destination URIs (`rua`): `mailto:` and/or `https:` endpoints.
+  */
+  rua: string[];
+  /**
+  * Whether the record is a syntactically valid `TLSRPTv1` record.
+  */
+  valid: boolean;
+  /**
+  * The record version (`TLSRPTv1`).
+  */
+  version?: string;
+}
+/**
+* A normalized [TLS-RPT](https://www.rfc-editor.org/rfc/rfc8460) report.
+*/
+interface TlsReport {
+  /**
+  * Report end timestamp (ISO 8601), from `date-range.end-datetime`.
+  */
+  endDate?: string;
+  /**
+  * The reporting organization (`organization-name`).
+  */
+  organizationName?: string;
+  /**
+  * The raw `policies` array, for provider-specific detail.
+  */
+  policies: unknown[];
+  /**
+  * The unique report id (`report-id`).
+  */
+  reportId?: string;
+  /**
+  * Report start timestamp (ISO 8601), from `date-range.start-datetime`.
+  */
+  startDate?: string;
+  /**
+  * Total failed TLS sessions across all policies.
+  */
+  totalFailure: number;
+  /**
+  * Total successful TLS sessions across all policies.
+  */
+  totalSuccessful: number;
+}
+/**
+* Parses a TLS-RPT policy record (the TXT record at `_smtp._tls.&lt;domain>`).
+* @param record The raw TXT record value (e.g. `v=TLSRPTv1; rua=mailto:tlsrpt@example.com`).
+* @returns The parsed record. See {@link TlsRptRecord}.
+*/
+declare const parseTlsRptRecord: (record: string) => TlsRptRecord;
+/**
+* Parses a TLS-RPT JSON report into a normalized summary.
+* @param report The report as a JSON string or already-parsed object.
+* @returns The normalized report. See {@link TlsReport}.
+* @throws {SyntaxError} When a string is provided that is not valid JSON.
+*/
+declare const parseTlsReport: (report: Record<string, unknown> | string) => TlsReport;
+export { type ArfReport, type DmarcRecord, type FilterSuppressedResult, type ListUnsubscribeHeaders, type ListUnsubscribeOptions, MemorySuppressionStore, type MtaStsPolicy, type MtaStsPolicyInput, type SuppressionEntry, type SuppressionReason, type SuppressionStore, type TlsReport, type TlsRptRecord, buildListUnsubscribe, buildMtaStsPolicy, createSuppressionStore, filterSuppressed, parseArfReport, parseDmarcRecord, parseListUnsubscribe, parseMtaStsPolicy, parseTlsReport, parseTlsRptRecord };

package/dist/deliverability/index.js

@@ -0,0 +1 @@
+import{parseArfReport as o}from"../packem_shared/parseArfReport-Ds6S3c4J.js";import{parseDmarcRecord as p}from"../packem_shared/parseDmarcRecord-DXZ-_rF0.js";import{buildListUnsubscribe as a,parseListUnsubscribe as i}from"../packem_shared/buildListUnsubscribe-Cdr8MvR_.js";import{buildMtaStsPolicy as m,parseMtaStsPolicy as c}from"../packem_shared/buildMtaStsPolicy-oEQg8y_C.js";import{createSuppressionStore as u,filterSuppressed as x}from"../packem_shared/createSuppressionStore-CeAZKCbY.js";import{parseTlsReport as b,parseTlsRptRecord as d}from"../packem_shared/parseTlsReport-wPe1lIDs.js";import{default as n}from"../packem_shared/MemorySuppressionStore-DZnbz-_B.js";export{n as MemorySuppressionStore,a as buildListUnsubscribe,m as buildMtaStsPolicy,u as createSuppressionStore,x as filterSuppressed,o as parseArfReport,p as parseDmarcRecord,i as parseListUnsubscribe,c as parseMtaStsPolicy,b as parseTlsReport,d as parseTlsRptRecord};

package/dist/events/index.d.ts

@@ -0,0 +1,31 @@
+import { E as EmailEvent, a as EventStore } from "../packem_shared/event-bus.d-DEl3w_EW.js";
+export { A as ALL_EVENTS, type b as EmailEventListener, type c as EmailEventType, d as EventBus } from "../packem_shared/event-bus.d-DEl3w_EW.js";
+/**
+* An in-memory {@link EventStore}. Events are grouped by `messageId`; events without one are kept
+* under a shared `__unkeyed` bucket so nothing is silently dropped.
+*/
+declare class MemoryEventStore implements EventStore {
+  private static readonly UNKEYED;
+  private readonly byMessage;
+  /**
+  * Appends an event to its message's bucket.
+  * @param event The event to store.
+  */
+  append(event: EmailEvent): void;
+  /**
+  * Reconstructs the time-ordered timeline for a single message.
+  * @param messageId The message to reconstruct.
+  * @returns The message's events, oldest first.
+  */
+  timeline(messageId: string): EmailEvent[];
+  /**
+  * Returns every stored event, ordered by timestamp.
+  * @returns All events.
+  */
+  all(): EmailEvent[];
+  /**
+  * Removes all stored events.
+  */
+  clear(): void;
+}
+export { type EmailEvent, type EventStore, MemoryEventStore };

package/dist/events/index.js

@@ -0,0 +1 @@
+import{ALL_EVENTS as r,EventBus as t}from"../packem_shared/ALL_EVENTS-3kwh5CBE.js";import{default as f}from"../packem_shared/MemoryEventStore-CuhfO9aj.js";export{r as ALL_EVENTS,t as EventBus,f as MemoryEventStore};