tsdmarc 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2700 @@
+import { Socket } from "node:dgram";
+import { Socket as Socket$1 } from "node:net";
+import { ConnectionOptions } from "node:tls";
+type ReportType = "aggregate" | "failure" | "smtp_tls";
+interface AggregateReportMetadata {
+  orgName: string;
+  orgEmail: string;
+  orgExtraContactInfo: string | null;
+  reportId: string;
+  beginDate: string;
+  endDate: string;
+  timespanRequiresNormalization: boolean;
+  /** A `bigint` only beyond ±2^53 (Python ints are unbounded). */
+  originalTimespanSeconds: number | bigint;
+  errors: string[];
+  generator: string | null;
+}
+interface AggregatePolicyPublished {
+  domain: string;
+  adkim: string;
+  aspf: string;
+  p: string;
+  sp: string;
+  pct: string | null;
+  fo: string | null;
+  np: string | null;
+  testing: string | null;
+  discoveryMethod: string | null;
+}
+interface IPSourceInfo {
+  ipAddress: string;
+  country: string | null;
+  reverseDns: string | null;
+  baseDomain: string | null;
+  name: string | null;
+  type: string | null;
+  asn: number | null;
+  asName: string | null;
+  asDomain: string | null;
+}
+/** Same shape as {@link IPSourceInfo}; returned by `getIpAddressInfo()`. */
+type IPAddressInfo = IPSourceInfo;
+interface ReverseDNSService {
+  name: string;
+  type: string | null;
+}
+/** Base domain → service, loaded from `base_reverse_dns_map.csv`. */
+type ReverseDNSMap = Map<string, ReverseDNSService>;
+interface AggregateAlignment {
+  spf: boolean;
+  dkim: boolean;
+  dmarc: boolean;
+}
+interface AggregateIdentifiers {
+  headerFrom: string;
+  envelopeFrom: string | null;
+  envelopeTo: string | null;
+}
+interface AggregatePolicyOverrideReason {
+  type: string | null;
+  comment: string | null;
+}
+interface AggregateAuthResultDKIM {
+  domain: string;
+  result: string;
+  selector: string;
+  humanResult: string | null;
+}
+interface AggregateAuthResultSPF {
+  domain: string;
+  result: string;
+  scope: string;
+  humanResult: string | null;
+}
+interface AggregateAuthResults {
+  dkim: AggregateAuthResultDKIM[];
+  spf: AggregateAuthResultSPF[];
+}
+interface AggregatePolicyEvaluated {
+  disposition: string;
+  dkim: string;
+  spf: string;
+  policyOverrideReasons: AggregatePolicyOverrideReason[];
+}
+interface AggregateRecord {
+  intervalBegin: string;
+  intervalEnd: string;
+  /** True when the record was split into daily buckets. */
+  normalizedTimespan: boolean;
+  source: IPSourceInfo;
+  /** A `bigint` only beyond 2^53 (Python ints are unbounded). */
+  count: number | bigint;
+  alignment: AggregateAlignment;
+  policyEvaluated: AggregatePolicyEvaluated;
+  disposition: string;
+  identifiers: AggregateIdentifiers;
+  authResults: AggregateAuthResults;
+}
+interface AggregateReport {
+  xmlSchema: string;
+  xmlNamespace: string | null;
+  reportMetadata: AggregateReportMetadata;
+  policyPublished: AggregatePolicyPublished;
+  records: AggregateRecord[];
+}
+interface EmailAddress {
+  displayName: string | null;
+  address: string;
+  local: string | null;
+  domain: string | null;
+}
+interface EmailAttachment {
+  filename?: string | null;
+  /** The filename reduced to a safe basename, or null (mail-parser). */
+  safeFilename?: string | null;
+  mailContentType?: string | null;
+  sha256?: string | null;
+  payload?: string;
+  contentTransferEncoding?: string;
+  binary?: boolean;
+  charset?: string | null;
+  [key: string]: unknown;
+}
+/**
+ * One Received header of a parsed email, as mail-parser reports it (the
+ * first hop first). Clause keys (`from`, `by`, `with`, `id`, `for`, `via`)
+ * hold the clause text; `raw` replaces them when the header is unparseable.
+ */
+interface EmailReceivedHop {
+  hop: number;
+  delay: number;
+  date?: string;
+  dateUtc?: string;
+  envelopeFrom?: string;
+  envelopeSender?: string;
+  raw?: string;
+  [key: string]: unknown;
+}
+/**
+ * A parsed email, in the shape parsedmarc builds from mail-parser's JSON
+ * (`parse_email()`). Only the fields parsedmarc relies on are typed; other
+ * header-derived keys may be present. `headers` maps raw header names to
+ * values and is copied verbatim to the output (its keys are not converted).
+ */
+interface ParsedEmail {
+  headers: Record<string, unknown>;
+  subject: string | null;
+  filenameSafeSubject: string | null;
+  date: string | null;
+  from: EmailAddress | null;
+  to: EmailAddress[];
+  cc: EmailAddress[];
+  bcc: EmailAddress[];
+  replyTo: EmailAddress[];
+  deliveredTo?: EmailAddress[];
+  attachments: EmailAttachment[];
+  body: string | null;
+  hasDefects?: boolean;
+  defects?: unknown;
+  defectsCategories?: unknown;
+  received?: EmailReceivedHop[];
+  /** Domains of the To and Reply-To addresses. */
+  toDomains?: string[];
+  /** UTC offset of the Date header in hours (`"+2.0"`). */
+  timezone?: string;
+  addressHeaderDefects?: unknown[];
+  receivedHeaderDefects?: unknown[];
+  dateHeaderDefects?: unknown[];
+  [key: string]: unknown;
+}
+interface FailureReport {
+  feedbackType: string | null;
+  userAgent: string | null;
+  version: string | null;
+  originalEnvelopeId: string | null;
+  originalMailFrom: string | null;
+  originalRcptTo: string | null;
+  arrivalDate: string;
+  arrivalDateUtc: string;
+  authenticationResults: string | null;
+  deliveryResult: string | null;
+  authFailure: string[];
+  authenticationMechanisms: string[];
+  dkimDomain: string | null;
+  reportedDomain: string;
+  sampleHeadersOnly: boolean;
+  source: IPSourceInfo;
+  sample: string;
+  parsedSample: ParsedEmail;
+  /** The `Message-ID` field of the feedback report, when present. */
+  messageId?: string;
+  /** The `Reported-URI` field of the feedback report, when present. */
+  reportedUri?: string;
+  /**
+   * Every other field of the feedback report is kept, keyed by its name
+   * lowercased with `-` → `_` and then camelCased (`Incidents` →
+   * `incidents`, `X-Custom-Field` → `xCustomField`).
+   */
+  [field: string]: unknown;
+}
+/** Backward-compatible alias of {@link FailureReport}. */
+type ForensicReport = FailureReport;
+interface SMTPTLSFailureDetails {
+  resultType: string;
+  /** A `bigint` only beyond 2^53 (the report's JSON integer, exact). */
+  failedSessionCount: number | bigint;
+  sendingMtaIp?: string;
+  receivingIp?: string;
+  receivingMxHostname?: string;
+  receivingMxHelo?: string;
+  additionalInfoUri?: string;
+  failureReasonCode?: string;
+  ipAddress?: string;
+}
+interface SMTPTLSPolicy {
+  policyDomain: string;
+  policyType: string;
+  /** A `bigint` only beyond 2^53 (the report's JSON integer, exact). */
+  successfulSessionCount: number | bigint;
+  /** A `bigint` only beyond 2^53 (the report's JSON integer, exact). */
+  failedSessionCount: number | bigint;
+  policyStrings?: string[];
+  mxHostPatterns?: string[];
+  failureDetails?: SMTPTLSFailureDetails[];
+}
+interface SMTPTLSReport {
+  organizationName: string;
+  beginDate: string;
+  endDate: string;
+  contactInfo: string | string[];
+  reportId: string;
+  policies: SMTPTLSPolicy[];
+}
+interface AggregateParsedReport {
+  reportType: "aggregate";
+  report: AggregateReport;
+}
+interface FailureParsedReport {
+  reportType: "failure";
+  report: FailureReport;
+}
+/** Backward-compatible alias of {@link FailureParsedReport}. */
+type ForensicParsedReport = FailureParsedReport;
+interface SMTPTLSParsedReport {
+  reportType: "smtp_tls";
+  report: SMTPTLSReport;
+}
+type ParsedReport = AggregateParsedReport | FailureParsedReport | SMTPTLSParsedReport;
+interface ParsingResults {
+  aggregateReports: AggregateReport[];
+  failureReports: FailureReport[];
+  smtpTlsReports: SMTPTLSReport[];
+}
+interface ExpiringDictOptions {
+  maxLen: number;
+  maxAgeSeconds: number;
+}
+/**
+ * An insertion-ordered map whose entries expire after `maxAgeSeconds` and
+ * which drops its oldest entry when full. Port of Python's `ExpiringDict`.
+ */
+export declare class ExpiringDict<K, V> {
+  readonly maxLen: number;
+  readonly maxAgeSeconds: number;
+  private readonly entries;
+  constructor(options: ExpiringDictOptions);
+  private isExpired;
+  /**
+   * Drop expired entries. Python's `ExpiringDict` only does so for a key
+   * being read, so unread entries live as long as the process. Entries are
+   * kept in `setAt` order (see `set()`), so the expired ones are at the
+   * front and each is visited once.
+   */
+  private prune;
+  get size(): number;
+  has(key: K): boolean;
+  get(key: K): V | undefined;
+  set(key: K, value: V): this;
+  delete(key: K): boolean;
+  clear(): void;
+  keys(): IterableIterator<K>;
+}
+type IPAddressCache = ExpiringDict<string, IPAddressInfo>;
+type SeenAggregateReportIds = ExpiringDict<string, boolean>;
+/** IP address info cache: 10,000 entries, 4 hour expiry. */
+export declare function newIpAddressCache(): IPAddressCache;
+/** Seen aggregate report ID cache: 100,000,000 entries, 1 hour expiry. */
+export declare function newSeenAggregateReportIds(): SeenAggregateReportIds;
+/** Module-default IP address info cache. */
+export declare const IP_ADDRESS_CACHE: IPAddressCache;
+/** Module-default seen aggregate report ID cache. */
+export declare const SEEN_AGGREGATE_REPORT_IDS: SeenAggregateReportIds;
+/** Module-default reverse DNS map. */
+export declare const REVERSE_DNS_MAP: ReverseDNSMap;
+/** Parsing and enrichment options (everything except the caches). */
+interface ParserOptions {
+  /** Do not make online requests (DNS, IP database, reverse DNS map, PSL overrides). */
+  offline: boolean;
+  /** Path to a local MMDB file from IPinfo, MaxMind or DBIP. */
+  ipDbPath: string | null;
+  /** Always use local/bundled files instead of downloading them. */
+  alwaysUseLocalFiles: boolean;
+  /** Path to a local reverse DNS map file. */
+  reverseDnsMapPath: string | null;
+  /** URL of a reverse DNS map file. */
+  reverseDnsMapUrl: string | null;
+  /** Path to a local PSL overrides file. */
+  pslOverridesPath: string | null;
+  /** URL of a PSL overrides file. */
+  pslOverridesUrl: string | null;
+  /** Nameservers for DNS queries (`null`: Cloudflare's public resolvers). */
+  nameservers: string[] | null;
+  /** DNS query timeout, in seconds. */
+  dnsTimeout: number;
+  /** Times to retry a DNS query after a timeout or other transient error. */
+  dnsRetries: number;
+  /** Remove attachment payloads from parsed email results. */
+  stripAttachmentPayloads: boolean;
+  /** Aggregate reports spanning more hours than this are normalized/split. */
+  normalizeTimespanThresholdHours: number;
+  /**
+   * Largest email accepted, in bytes (UTF-8 for text input); `0` disables
+   * the check. Larger emails raise `EmailTooLargeError` and mailboxes move
+   * them to the invalid folder, without downloading them where the backend
+   * reports the size first. Not in parsedmarc. Default: 50 MiB.
+   */
+  maxEmailSize: number;
+  /**
+   * Most MIME parts accepted in an email; `0` disables the check. Lines
+   * starting with `--` (an upper bound on boundary parts) are counted before
+   * parsing, and the parser counts every message it creates, so parts that
+   * need no boundary line count too. Not in parsedmarc. Default: 10,000.
+   */
+  maxMimeParts: number;
+  /**
+   * Most header lines accepted in an email, over all its parts (folded
+   * lines included); `0` disables the check. Not in parsedmarc.
+   * Default: 100,000.
+   */
+  maxHeaderLines: number;
+  /**
+   * Most text, in characters, that re-serializing the parts of one email
+   * may produce; text with a character outside Latin-1 counts each of its
+   * characters twice, as it takes twice the memory. Every part is counted
+   * once per level it is flattened at, so this bounds size × nesting
+   * depth, which `maxEmailSize` does not; `0` disables the check. Not in
+   * parsedmarc. Default: 512 MiB.
+   */
+  maxExpandedEmailSize: number;
+  /**
+   * Most source IPs of one aggregate report looked up over the network
+   * (reverse DNS, IPinfo API); `0` disables the check. Later IPs get no
+   * reverse DNS and only the IP database. Cached IPs don't count. Not in
+   * parsedmarc. Default: 100,000.
+   */
+  maxLookupsPerReport: number;
+  /**
+   * Most reverse DNS lookups of one aggregate report that may time out or
+   * fail (an address with no PTR is an answer, not a failure); `0`
+   * disables the check. Later IPs are handled as in
+   * {@link ParserOptions.maxLookupsPerReport}. A failed lookup can take
+   * seconds, and the report's sender can choose addresses that fail. Not
+   * in parsedmarc. Default: 256.
+   */
+  maxFailedLookupsPerReport: number;
+  /**
+   * Seconds of network lookups (reverse DNS, IPinfo API) one aggregate
+   * report may use in total; `0` disables the check. Later IPs are handled
+   * as in {@link ParserOptions.maxLookupsPerReport}. An answer that is not a
+   * failure can still be slow, and a sender can make every record cost one.
+   * Not in parsedmarc. Default: 600.
+   */
+  maxLookupTimePerReport: number;
+  /**
+   * Most records an aggregate report may have once its timespan is
+   * normalized into daily buckets; `0` disables the check. Sender-chosen
+   * dates and counts turn one `<record>` into one record per day, for up to
+   * 2.9 million days. A record with few messages only takes as many days as
+   * it has messages. Larger reports raise `InvalidAggregateReport`. Not in
+   * parsedmarc. Default: 250,000.
+   */
+  maxNormalizedRecords: number;
+  /**
+   * Deepest element nesting accepted in an aggregate report's XML; `0`
+   * disables the check. Deeper reports raise `InvalidAggregateReport`. Not
+   * in parsedmarc. Default: 100,000.
+   */
+  maxXmlDepth: number;
+  /**
+   * Most elements and attributes accepted in an aggregate report's XML; `0`
+   * disables the check. Larger reports raise `InvalidAggregateReport`. Not
+   * in parsedmarc. Default: 5,000,000.
+   */
+  maxXmlNodes: number;
+  /**
+   * Largest SMTP TLS report accepted, in bytes of JSON (UTF-16 code units
+   * for text input); `0` disables the check. Larger reports raise
+   * `InvalidSMTPTLSReport`. Not in parsedmarc. Default: 10 MiB.
+   */
+  maxSmtpTlsReportSize: number;
+  /**
+   * Seconds one email or file may take to parse; `0` disables the check. A
+   * worker past it is stopped. Without workers (`nProcs` 1) only a mailbox
+   * applies it, at the next keepalive (every 20 records), so only time
+   * spent awaiting counts. A mailbox leaves such a message for retry and
+   * then moves it to the `Unsaved` folder, without ever deleting it. Not
+   * in parsedmarc. Default: 1 hour.
+   */
+  jobTimeout: number;
+  /**
+   * JavaScript heap limit of each parsing worker thread, in MiB; `0` keeps
+   * the runtime's limit (about 4 GiB per worker on 64-bit Node). A worker
+   * over it dies and only its job fails: a mailbox leaves the message for
+   * retry and then moves it to the `Unsaved` folder, without ever deleting
+   * it. Bun ignores it. Not in parsedmarc. Default: 2 GiB.
+   */
+  maxWorkerHeapMb: number;
+}
+/** Default {@link ParserOptions.maxEmailSize}: 50 MiB. */
+export declare const DEFAULT_MAX_EMAIL_SIZE: number;
+/** Default {@link ParserOptions.maxMimeParts}. */
+export declare const DEFAULT_MAX_MIME_PARTS = 1e4;
+/** Default {@link ParserOptions.maxHeaderLines}. */
+export declare const DEFAULT_MAX_HEADER_LINES = 1e5;
+/** Default {@link ParserOptions.maxExpandedEmailSize}: 512 MiB. */
+export declare const DEFAULT_MAX_EXPANDED_EMAIL_SIZE: number;
+/** Default {@link ParserOptions.maxNormalizedRecords}. */
+export declare const DEFAULT_MAX_NORMALIZED_RECORDS = 25e4;
+/** Default {@link ParserOptions.maxXmlDepth}. */
+export declare const DEFAULT_MAX_XML_DEPTH = 1e5;
+/** Default {@link ParserOptions.maxXmlNodes}. */
+export declare const DEFAULT_MAX_XML_NODES = 5e6;
+/** Default {@link ParserOptions.maxSmtpTlsReportSize}: 10 MiB. */
+export declare const DEFAULT_MAX_SMTP_TLS_REPORT_SIZE: number;
+/** Default {@link ParserOptions.jobTimeout}: one hour. */
+export declare const DEFAULT_JOB_TIMEOUT = 3600;
+/** Default {@link ParserOptions.maxWorkerHeapMb}. */
+export declare const DEFAULT_MAX_WORKER_HEAP_MB = 2048;
+/** Default {@link ParserOptions.maxLookupsPerReport}. */
+export declare const DEFAULT_MAX_LOOKUPS_PER_REPORT = 1e5;
+/** Default {@link ParserOptions.maxFailedLookupsPerReport}. */
+export declare const DEFAULT_MAX_FAILED_LOOKUPS_PER_REPORT = 256;
+/** Default {@link ParserOptions.maxLookupTimePerReport}, in seconds. */
+export declare const DEFAULT_MAX_LOOKUP_TIME_PER_REPORT = 600;
+/** The limits on an email's structure, applied while parsing it. */
+type EmailLimits = Pick<ParserOptions, "maxMimeParts" | "maxHeaderLines" | "maxExpandedEmailSize">;
+interface ParserCaches {
+  ipAddressCache: IPAddressCache;
+  /** Seen aggregate reports, keyed on reporter, Report-ID and policy domain (`aggregateReportKey()`). */
+  seenAggregateReportIds: SeenAggregateReportIds;
+  reverseDnsMap: ReverseDNSMap;
+}
+/** Immutable parser configuration: options plus shared caches. */
+type ParserConfig = Readonly<ParserOptions & ParserCaches>;
+export declare const DEFAULT_PARSER_OPTIONS: Readonly<ParserOptions>;
+/** Build a config. Caches not given are fresh and isolated. */
+export declare function createParserConfig(options?: Partial<ParserOptions & ParserCaches>): ParserConfig;
+/** Derive a variant of `config` that keeps sharing its caches. */
+export declare function replaceParserConfig(config: ParserConfig, changes: Partial<ParserOptions & ParserCaches>): ParserConfig;
+/** Options accepted by public parsing functions (individual options or `config`). */
+interface ParserConfigInput extends Partial<Omit<ParserOptions, "pslOverridesPath" | "pslOverridesUrl">> {
+  /** When given, the individual options are ignored. */
+  config?: ParserConfig | null;
+}
+/**
+ * Resolve the config for a public parsing call: `input.config` when given,
+ * otherwise a config built from the individual options and bound to the
+ * module-default caches. PSL override options are only settable through an
+ * explicit `config`. The module-default caches ignore the options, so calls
+ * with different `offline`, `nameservers` or `ipDbPath` values, or for
+ * different tenants, need a `createParserConfig()` each.
+ */
+export declare function resolveParserConfig(input?: ParserConfigInput): ParserConfig;
+/** The options of a config, without caches, for sending to a worker. */
+export declare function parserConfigToState(config: ParserConfig): ParserOptions;
+/**
+ * Rebuild a config from worker state. Missing options take their defaults
+ * and the caches bind to this thread's module-default caches.
+ */
+export declare function parserConfigFromState(state: Partial<ParserOptions>): ParserConfig;
+type CsvRow = Record<string, unknown>;
+interface CsvOptions {
+  /**
+   * Neutralize spreadsheet formulas (CSV injection): a text cell starting
+   * with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`,
+   * so Excel, LibreOffice or Google Sheets show it as text instead of
+   * evaluating it. Report data comes from untrusted senders. On by
+   * default, like parsedmarc 11.1.0 (`_csv_safe`); `false`
+   * writes cells unchanged. Numbers (a negative count) are never changed.
+   */
+  formulaEscape?: boolean;
+}
+/**
+ * A text cell with a leading `'` when a spreadsheet would read it as a
+ * formula (see {@link CsvOptions.formulaEscape}); other values unchanged.
+ */
+export declare function csvFormulaEscape(value: unknown): unknown;
+/** Incremental writer, like `csv.DictWriter` over a `StringIO`. */
+export declare class CsvDictWriter {
+  readonly fieldnames: readonly string[];
+  readonly formulaEscape: boolean;
+  private text;
+  constructor(fieldnames: readonly string[], options?: CsvOptions);
+  writeHeader(): void;
+  /**
+   * Write one row. Missing fields are empty; a field not in `fieldnames`
+   * throws, like `DictWriter`'s default `extrasaction="raise"`.
+   */
+  writeRow(row: CsvRow): void;
+  getValue(): string;
+}
+/** Header plus rows, as one CSV string. */
+export declare function rowsToCsv(fieldnames: readonly string[], rows: Iterable<CsvRow>, options?: CsvOptions): string;
+/**
+ * Strip NUL characters from a string cell (parsedmarc's `_csv_safe`).
+ * Non-string values are returned unchanged.
+ */
+export declare function csvSafe(value: unknown): unknown;
+/** Largest decompressed report accepted, in bytes. */
+export declare const MAX_DECOMPRESSED_REPORT_SIZE: number;
+/**
+ * Largest decompressed zip member accepted for the bzip2, LZMA and
+ * Zstandard methods (12, 14, 93), in bytes. Their pure-TypeScript decoders
+ * are much slower than inflate, and a 1 KB bzip2 member can expand to the
+ * 100 MiB cap, costing seconds of CPU per attachment. Report senders use
+ * deflate (RFC 7489 asks for zip or gzip), so these methods only need to
+ * handle small reports. Not in parsedmarc.
+ */
+export declare const MAX_DECOMPRESSED_SLOW_CODEC_SIZE: number;
+interface ExtractOptions {
+  /** Override the decompression cap (tests); defaults to 100 MiB. */
+  maxDecompressedSize?: number;
+  /**
+   * Override the cap for bzip2, LZMA and Zstandard zip members (tests);
+   * defaults to 10 MiB, and never exceeds `maxDecompressedSize`.
+   */
+  maxSlowCodecSize?: number;
+  /**
+   * Largest stream or file read, in bytes; `0` disables the check. Defaults
+   * to 100 MiB, the largest report once decompressed. Not in parsedmarc.
+   */
+  maxInputSize?: number;
+  /** Told how many bytes were decompressed (not called for plain content). */
+  onDecompressed?: (size: number) => void;
+}
+/**
+ * Decompress the first member of a gzip stream, refusing to produce more
+ * than `limit` bytes (parsedmarc's `_decompress_gzip_bounded`). Corrupt
+ * data raises zlib's errors (`Error -3 while decompressing data: ...`);
+ * trailing bytes after the first member are ignored.
+ */
+export declare function decompressGzipBounded(data: Uint8Array, limit?: number): Uint8Array;
+/**
+ * Extract report text from zip- or gzip-compressed content, or return
+ * plain XML/JSON content decoded as-is. A string is first decoded as strict
+ * base64; a string that is not valid base64 is returned unchanged.
+ */
+export declare function extractReport(content: string | Uint8Array | ArrayBuffer, options?: ExtractOptions): string;
+type ReportStream = AsyncIterable<Uint8Array | string> | ReadableStream<Uint8Array>;
+/**
+ * Read a whole stream and extract the report from it. A stream that yields
+ * text instead of bytes is rejected, like a Python file opened in text mode.
+ */
+export declare function extractReportFromStream(stream: ReportStream, options?: ExtractOptions): Promise<string>;
+/** Extract the report from a file. */
+export declare function extractReportFromFilePath(filePath: string, options?: ExtractOptions): Promise<string>;
+interface PyDateTimeFields {
+  year: number;
+  month: number;
+  day: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  microsecond?: number;
+  /** Minutes east of UTC; `null` (default) for a naive datetime. */
+  utcOffsetMinutes?: number | null;
+}
+export declare class PyDateTime {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+  readonly microsecond: number;
+  readonly utcOffsetMinutes: number | null;
+  constructor(fields: PyDateTimeFields);
+  /** Naive datetime in local time from an epoch instant (ms precision). */
+  static fromDateLocal(date: Date, microsecond?: number): PyDateTime;
+  /** Aware datetime with the given offset, from an epoch instant. */
+  static fromDateWithOffset(date: Date, utcOffsetMinutes: number, microsecond?: number): PyDateTime;
+  /**
+   * Python's `datetime.fromtimestamp(seconds)` (naive, local time), or
+   * `datetime.fromtimestamp(seconds, timezone.utc)` with `utc: true`.
+   */
+  static fromTimestamp(seconds: number, utc?: boolean): PyDateTime;
+  /** Python's `datetime.now()` (naive local) or `datetime.now(timezone.utc)`. */
+  static now(utc?: boolean): PyDateTime;
+  get isNaive(): boolean;
+  /** The instant this datetime denotes (naive values are read as local time). */
+  toDate(): Date;
+  /** POSIX timestamp in seconds (Python's `datetime.timestamp()`). */
+  timestamp(): number;
+  /** Python's `astimezone(timezone.utc)`. */
+  toUtc(): PyDateTime;
+  /** Python's `astimezone()` with no argument: aware, in local time. */
+  toLocal(): PyDateTime;
+  /** Python's `replace(tzinfo=...)`: same wall clock, new (or no) offset. */
+  withOffset(utcOffsetMinutes: number | null): PyDateTime;
+  /** Python's `replace(...)` for wall-clock fields. */
+  replace(changes: Partial<PyDateTimeFields>): PyDateTime;
+  /** Add a duration in seconds (Python's `+ timedelta(seconds=...)`). */
+  addSeconds(seconds: number): PyDateTime;
+  /** Midnight of the same day (Python's `datetime.combine(dt.date(), time())`). */
+  startOfDay(): PyDateTime;
+  /**
+   * Seconds from `other` to this datetime (Python's `(self - other)
+   * .total_seconds()`). Both must be naive or both aware, as in Python.
+   */
+  secondsSince(other: PyDateTime): number;
+  /** Negative, zero or positive, like comparing Python datetimes. */
+  compare(other: PyDateTime): number;
+  equals(other: PyDateTime): boolean;
+  private wallClockMicros;
+  fields(): PyDateTimeFields;
+  /** Day of the week, Monday = 0 (Python's `weekday()`). */
+  weekday(): number;
+  /**
+   * Python's `strftime` for the directives parsedmarc uses: `%Y %y %m %d %H
+   * %I %M %S %f %p %z %Z %a %A %b %B %j %%`.
+   */
+  strftime(format: string): string;
+  private directive;
+  /** Python's `isoformat(sep)`: `2024-01-01T00:00:00[.ffffff][+00:00]`. */
+  isoformat(separator?: string): string;
+  /** Python's `str(datetime)`: ISO format with a space separator. */
+  toString(): string;
+  /** JSON form, matching Python's `json.dumps(..., default=str)`. */
+  toJSON(): string;
+}
+/** Base class of every DNS error (dnspython's `dns.exception.DNSException`). */
+export declare class DNSException extends Error {
+  override name: string;
+}
+/** The DNS operation timed out (`dns.exception.Timeout`). */
+export declare class DNSTimeout extends DNSException {
+  override name: string;
+  /** Seconds waited, when known. */
+  readonly timeout: number | null;
+  constructor(timeout?: number | null);
+}
+/** One failed attempt against one nameserver during a resolution. */
+interface ResolutionError {
+  /** The nameserver, as dnspython prints it (`Do53:1.1.1.1@53`, a URL, ...). */
+  nameserver: string;
+  /** Whether the attempt used TCP (or a stream transport). */
+  tcp: boolean;
+  port: number;
+  /** The error raised, or the response code text (`SERVFAIL`). */
+  error: unknown;
+}
+/** The resolution lifetime expired (`dns.resolver.LifetimeTimeout`). */
+export declare class LifetimeTimeout extends DNSTimeout {
+  override name: string;
+  readonly errors: readonly ResolutionError[];
+  constructor(timeout: number, errors: readonly ResolutionError[]);
+}
+/** DNS message is malformed (`dns.exception.FormError`). */
+export declare class DNSFormError extends DNSException {
+  override name: string;
+  constructor(message?: string);
+}
+/** A DNS response does not respond to the question asked (`dns.query.BadResponse`). */
+export declare class BadResponse extends DNSFormError {
+  override name: string;
+  constructor(message?: string);
+}
+/** Text input is malformed (`dns.exception.SyntaxError`). */
+export declare class DNSSyntaxError extends DNSException {
+  override name: string;
+  constructor(message?: string);
+}
+/** An escaped code in a name is invalid (`dns.name.BadEscape`). */
+export declare class BadEscape extends DNSSyntaxError {
+  override name: string;
+  constructor();
+}
+/** IDNA encoding failed (`dns.name.IDNAException`). */
+export declare class IDNAException extends DNSException {
+  override name: string;
+  constructor(detail: string);
+}
+/** A DNS label is empty (`dns.name.EmptyLabel`). */
+export declare class EmptyLabel extends DNSSyntaxError {
+  override name: string;
+  constructor();
+}
+/** A DNS label is > 63 octets long (`dns.name.LabelTooLong`). */
+export declare class LabelTooLong extends DNSSyntaxError {
+  override name: string;
+  constructor();
+}
+/** A DNS name is > 255 octets long (`dns.name.NameTooLong`). */
+export declare class NameTooLong extends DNSFormError {
+  override name: string;
+  constructor();
+}
+/** The DNS query name does not exist (`dns.resolver.NXDOMAIN`). */
+export declare class NXDOMAIN extends DNSException {
+  override name: string;
+  /** The names that were tried, in text form with the final dot. */
+  readonly qnames: readonly string[];
+  constructor(qnames: readonly string[]);
+}
+/** The DNS query name is too long after DNAME substitution (`dns.resolver.YXDOMAIN`). */
+export declare class YXDOMAIN extends DNSException {
+  override name: string;
+  constructor();
+}
+/** The DNS response does not contain an answer to the question (`dns.resolver.NoAnswer`). */
+export declare class NoAnswer extends DNSException {
+  override name: string;
+  /** @param question The question as dnspython prints it (`example.com. IN TXT`). */
+  constructor(question: string);
+}
+/** All nameservers failed to answer the query (`dns.resolver.NoNameservers`). */
+export declare class NoNameservers extends DNSException {
+  override name: string;
+  readonly errors: readonly ResolutionError[];
+  /** @param question The question as dnspython prints it (`example.com. IN TXT`). */
+  constructor(question: string, errors: readonly ResolutionError[]);
+}
+/** DNS metaqueries are not allowed (`dns.resolver.NoMetaqueries`). */
+export declare class NoMetaqueries extends DNSException {
+  override name: string;
+  constructor();
+}
+/** DNS resource record type is unknown (`dns.rdatatype.UnknownRdatatype`). */
+export declare class UnknownRdatatype extends DNSException {
+  override name: string;
+  constructor(message?: string);
+}
+/**
+ * Module-level state the loaders write (parsedmarc's `_IP_DB_PATH`,
+ * `_LAST_LOGGED_IP_DB_PATH` and `_IPINFO_API_TOKEN` globals). Exposed so a
+ * CLI can snapshot and restore it around a configuration reload.
+ */
+interface IpInfoState {
+  /** The database selected by `loadIpDb()` (downloaded, cached or bundled). */
+  ipDbPath: string | null;
+  /** The last database path logged, so the selection is logged when it changes. */
+  lastLoggedIpDbPath: string | null;
+  /** IPinfo Lite API token; `null` disables the API. */
+  ipinfoApiToken: string | null;
+}
+export declare const ipInfoState: IpInfoState;
+/** Country and ASN fields of an IP address. */
+interface IPDatabaseRecord {
+  country: string | null;
+  asn: number | null;
+  asName: string | null;
+  asDomain: string | null;
+}
+interface LoadIpDbOptions {
+  /** Always use a local/bundled database file. */
+  alwaysUseLocalFile?: boolean;
+  /** Path to a local MMDB file. */
+  localFilePath?: string | null;
+  /** URL to the MMDB database file. */
+  url?: string | null;
+  /** Do not make online requests. */
+  offline?: boolean;
+}
+/**
+ * Downloads the IP-to-country MMDB database from a URL and caches it
+ * locally. An existing `localFilePath` is used as-is, with no download. On
+ * download failure (or when offline), a previously cached download is used
+ * if available, falling back to the bundled copy from `@tsdmarc/ipinfo-lite`.
+ * A download that isn't a MMDB database counts as a failure: parsedmarc
+ * saves it over the cached copy, and every lookup fails from then on.
+ */
+export declare function loadIpDb(options?: LoadIpDbOptions): Promise<void>;
+/**
+ * Configure the IPinfo Lite REST API as the primary source for IP lookups.
+ *
+ * With a token, `getIpAddressDbRecord()` queries the API first and falls
+ * back to the MMDB on network errors or non-2xx responses. An invalid token
+ * raises `InvalidIPinfoAPIKey`.
+ *
+ * With `probe` (the default), the token is verified by looking up
+ * `1.1.1.1`: a 401/403 raises `InvalidIPinfoAPIKey`; other errors are
+ * logged and the token is still accepted so per-request fallback can take
+ * over.
+ */
+export declare function configureIpinfoApi(token: string | null, options?: {
+  probe?: boolean;
+}): Promise<void>;
+/**
+ * Look up an IP and return country and ASN fields.
+ *
+ * If the IPinfo Lite API is configured (`configureIpinfoApi()`), it is
+ * queried first; any non-fatal failure falls through to the MMDB. An
+ * invalid API token raises `InvalidIPinfoAPIKey`. MaxMind/DBIP
+ * country-only databases carry only the country, so the ASN fields come
+ * back `null` for them.
+ */
+export declare function getIpAddressDbRecord(ipAddress: string, options?: {
+  dbPath?: string | null;
+  skipApi?: boolean;
+}): Promise<IPDatabaseRecord>;
+/**
+ * The ISO code of the country of an IPv4 or IPv6 address, or `null` when
+ * unknown. `dbPath` is a MMDB file from IPinfo, MaxMind or DBIP.
+ */
+export declare function getIpAddressCountry(ipAddress: string, options?: {
+  dbPath?: string | null;
+}): Promise<string | null>;
+interface LoadReverseDnsMapOptions {
+  /** Always use a local map file. */
+  alwaysUseLocalFile?: boolean;
+  /** Path to a local map file. */
+  localFilePath?: string | null;
+  /** URL to a reverse DNS map. */
+  url?: string | null;
+  /** Do not make online requests. */
+  offline?: boolean;
+  /** Path to a local PSL overrides file. */
+  pslOverridesPath?: string | null;
+  /** URL to a PSL overrides file. */
+  pslOverridesUrl?: string | null;
+}
+/**
+ * Loads the reverse DNS map from a URL or local file.
+ *
+ * Repopulates the given map in place. The URL is tried first; on
+ * failure (or when `offline` / `alwaysUseLocalFile` is set) the local path
+ * is used, defaulting to the bundled CSV. The PSL overrides are reloaded
+ * first with the same flags, so map entries that depend on a folded base
+ * domain resolve against the current overrides.
+ *
+ * parsedmarc clears the map before downloading; here the new entries are
+ * built aside and swapped in at once, so concurrent lookups never see a
+ * half-loaded map (and never cache results computed from it). Concurrent
+ * loads of the same map share one download.
+ */
+export declare function loadReverseDnsMap(reverseDnsMap: ReverseDNSMap, options?: LoadReverseDnsMapOptions): Promise<void>;
+interface GetServiceOptions extends LoadReverseDnsMapOptions {
+  /** A reverse DNS map; loaded into when empty. */
+  reverseDnsMap?: ReverseDNSMap | null;
+}
+/**
+ * The service of a base domain from reverse DNS. Unknown services have the
+ * base domain as name and a `null` type.
+ */
+export declare function getServiceFromReverseDnsBaseDomain(baseDomain: string, options?: GetServiceOptions): Promise<ReverseDNSService>;
+/**
+ * The network lookups one aggregate report may still make. parsedmarc has no
+ * such limit: records are resolved one at a time, a failed lookup takes
+ * seconds, and a sender choosing addresses that fail can hold a small
+ * report for days. Past a limit the report keeps all its records, without
+ * reverse DNS.
+ */
+declare class ReportLookupBudget {
+  private readonly maxLookups;
+  private readonly maxFailures;
+  private readonly maxTimeMs;
+  private lookups;
+  private failures;
+  private spentMs;
+  private warned;
+  /**
+   * What this report's lookups found for IPs the shared cache doesn't keep
+   * (no PTR record, ASN not in the map): a repeated address costs one
+   * lookup per report, not one per record.
+   */
+  private readonly uncached;
+  constructor(config: ParserConfig);
+  /** Whether one more IP may use the network; counts it if so. */
+  take(): boolean;
+  /** Count the time of a lookup against the report. */
+  charge(elapsedMs: number): void;
+  /** What an earlier record of this report found for `ipAddress`. */
+  recall(ipAddress: string): IPAddressInfo | undefined;
+  /** Keep what was found for an IP the shared cache doesn't keep. */
+  remember(info: IPAddressInfo): void;
+  /** Count a DNS error, unless it is a real answer that there is no PTR. */
+  recordError(error: DNSException): void;
+}
+interface GetIpAddressInfoOptions {
+  /**
+   * Take every option below from this config (its IP address cache,
+   * reverse DNS map, DNS settings, ...), the way parsedmarc's parsers call
+   * `get_ip_address_info()`. Options given alongside it are ignored.
+   */
+  config?: ParserConfig | null;
+  /** Limits on the network lookups of the report this IP comes from. */
+  lookupBudget?: ReportLookupBudget | null;
+  /** Path to a MMDB file from IPinfo, MaxMind, or DBIP. */
+  ipDbPath?: string | null;
+  /** Path to a reverse DNS map file. */
+  reverseDnsMapPath?: string | null;
+  /** Do not download files. */
+  alwaysUseLocalFiles?: boolean;
+  /** URL to the reverse DNS map file. */
+  reverseDnsMapUrl?: string | null;
+  /** Cache storage. */
+  cache?: IPAddressCache | null;
+  /** A reverse DNS map. */
+  reverseDnsMap?: ReverseDNSMap | null;
+  /** Do not make online queries for geolocation or DNS. */
+  offline?: boolean;
+  /** Nameservers to use (Cloudflare's public DNS resolvers by default). */
+  nameservers?: readonly string[] | null;
+  /** DNS timeout, in seconds. */
+  timeout?: number;
+  /** Times to retry on timeout or other transient DNS errors. */
+  retries?: number;
+  /** Path to a local PSL overrides file. */
+  pslOverridesPath?: string | null;
+  /** URL to a PSL overrides file. */
+  pslOverridesUrl?: string | null;
+}
+/**
+ * Reverse DNS, country, ASN, and service information for an IP address.
+ */
+export declare function getIpAddressInfo(ip: string, input?: GetIpAddressInfoOptions): Promise<IPAddressInfo>;
+/** The XML namespace RFC 9990 assigns to DMARC aggregate reports. */
+export declare const RFC_9990_NAMESPACE = "urn:ietf:params:xml:ns:dmarc-2.0";
+/**
+ * RFC 9990's PolicyOverrideType enumeration: `policy_test_mode` was added
+ * and `forwarded` / `sampled_out` were removed.
+ */
+export declare const RFC_9990_POLICY_OVERRIDE_TYPES: ReadonlySet<string>;
+export declare const RFC_7489_REMOVED_POLICY_OVERRIDE_TYPES: ReadonlySet<string>;
+/**
+ * Unwrap a possibly-langAttrString value (`{"#text": ..., "@lang": ...}`)
+ * to its text. `null` stays `null`; other shapes pass through unchanged.
+ */
+export declare function unwrapText(value: unknown): unknown;
+interface DayBucket {
+  begin: PyDateTime;
+  end: PyDateTime;
+  count: number | bigint;
+}
+/**
+ * Splits a report interval into calendar-day buckets
+ * (`_bucket_interval_by_day`), computing the day layout once for all of a
+ * report's records.
+ *
+ * Python walks every day of the interval; a reporter-supplied `date_range`
+ * can span thousands of years, so this works per group of days with the
+ * same overlap (first day, full days, last day). Every day in a group gets
+ * the same exact share, so floors, fractions and the largest-remainder
+ * order (Python's stable `sorted(..., reverse=True)`: among equal
+ * fractions, earlier days first) are computed per group, and only buckets
+ * with a non-zero count are built. The result equals Python's.
+ */
+declare class IntervalDays {
+  #private;
+  readonly begin: PyDateTime;
+  readonly end: PyDateTime;
+  constructor(begin: PyDateTime, end: PyDateTime);
+  /**
+   * Distribute `totalCount` over the days, like Python, raising like it.
+   * More than `maxBuckets` buckets raise `InvalidAggregateReport` before any
+   * is built (not in parsedmarc).
+   */
+  buckets(totalCount: number | bigint, maxBuckets?: number): DayBucket[];
+}
+/**
+ * Split [begin, end) into calendar-day buckets and distribute `totalCount`
+ * across them in proportion to each day's overlap, using largest-remainder
+ * rounding so the counts sum to `totalCount` (`_bucket_interval_by_day`).
+ */
+export declare function bucketIntervalByDay(begin: PyDateTime, end: PyDateTime, totalCount: number | bigint): DayBucket[];
+/** A parsed record before its interval fields are added. */
+type RecordWithoutInterval = Omit<AggregateRecord, "intervalBegin" | "intervalEnd" | "normalizedTimespan">;
+/**
+ * What a report's normalized timespan may still expand to, in records of
+ * ordinary size (`maxNormalizedRecords`; not in parsedmarc). Every day
+ * bucket is a row of the CSV and a document of the search outputs, and
+ * repeats its record's results and the report's data (reporter, errors,
+ * published policy), so a record with thousands of `<dkim>` entries, or a
+ * long `extra_contact_info`, weighs as many records as its rows take in the
+ * output: the number of records alone doesn't bound the report.
+ */
+export declare class NormalizedRecordBudget {
+  #private;
+  /**
+   * @param reportSize Estimated characters of the report data each row
+   *   repeats ({@link estimatedSize}).
+   */
+  constructor(maxRecords: number, reportSize?: number);
+  /** The records of ordinary size a row of `record` weighs, at least one. */
+  weigh(record: RecordWithoutInterval): number;
+  /** The buckets of a record of `weight` that still fit. */
+  room(weight: number): number;
+  spend(weight: number): void;
+}
+/**
+ * Append a parsed record unchanged, or split into daily buckets when the
+ * report's timespan needs normalizing (`_append_parsed_record`).
+ */
+export declare function appendParsedRecord(parsedRecord: RecordWithoutInterval, records: AggregateRecord[], beginDt: PyDateTime, endDt: PyDateTime, normalize: boolean, interval?: IntervalDays, maxRecords?: number | NormalizedRecordBudget): void;
+/**
+ * Convert one `<record>` into parsedmarc's consistent shape, enriching the
+ * source IP (`_parse_report_record`).
+ */
+export declare function parseReportRecord(record: unknown, config: ParserConfig, isRfc9990?: boolean, lookupBudget?: ReportLookupBudget | null): Promise<RecordWithoutInterval>;
+interface ParseAggregateReportOptions extends ParserConfigInput {
+  /** DNS timeout in seconds (parsedmarc's `timeout`); same as `dnsTimeout`. */
+  timeout?: number;
+  /** DNS retries (parsedmarc's `retries`); same as `dnsRetries`. */
+  retries?: number;
+  /** Called every 20 records of large reports (not part of `config`). */
+  keepAlive?: (() => unknown) | null;
+}
+/**
+ * Parse a DMARC aggregate report's XML. Malformed XML is recovered the way
+ * parsedmarc does (with the parse error kept in `reportMetadata.errors`).
+ * An error thrown by `keepAlive` is rethrown as is.
+ */
+export declare function parseAggregateReportXml(xml: string | Uint8Array, options?: ParseAggregateReportOptions): Promise<AggregateReport>;
+interface ParseAggregateReportFileOptions extends ParserConfigInput, ExtractOptions {
+  keepAlive?: (() => unknown) | null;
+}
+/**
+ * Parse an aggregate report from bytes (zip, gzip or XML) or base64 text
+ * (`parse_aggregate_report_file`). Like Python, a string goes to
+ * `extractReport()` as base64, or as the XML itself when it is not valid
+ * base64; it is never opened as a path (see
+ * {@link parseAggregateReportFromFilePath}).
+ */
+export declare function parseAggregateReportFile(input: string | Uint8Array, options?: ParseAggregateReportFileOptions): Promise<AggregateReport>;
+/**
+ * Parse an aggregate report file from disk (`extract_report_from_file_path`
+ * followed by `parse_aggregate_report_xml`). parsedmarc's
+ * `parse_aggregate_report_file()` documents a path argument but treats a
+ * string as report content; this is the path form.
+ */
+export declare function parseAggregateReportFromFilePath(filePath: string, options?: ParseAggregateReportFileOptions): Promise<AggregateReport>;
+/** Fields of `parsedAggregateReportsToCsv()`, in column order. */
+export declare const AGGREGATE_CSV_FIELDS: readonly string[];
+/**
+ * Flatten aggregate reports into CSV rows (snake_case keys), one per
+ * record (`parsed_aggregate_reports_to_csv_rows`).
+ */
+export declare function parsedAggregateReportsToCsvRows(reports: AggregateReport | AggregateReport[]): CsvRow[];
+/** Aggregate reports as flat CSV, with headers. */
+export declare function parsedAggregateReportsToCsv(reports: AggregateReport | AggregateReport[], options?: CsvOptions): string;
+/** Version of tsdmarc itself. */
+export declare const VERSION: string;
+/** parsedmarc version this port matches feature-for-feature. */
+export declare const PARSEDMARC_COMPAT_VERSION: string;
+export declare const USER_AGENT: string;
+/** DNS query timeout, in seconds. */
+export declare const DEFAULT_DNS_TIMEOUT: number;
+export declare const DEFAULT_DNS_MAX_RETRIES: number;
+/**
+ * Recommended mix of public resolvers for cross-provider DNS failover. Not
+ * applied automatically: callers opt in by passing
+ * `nameservers: RECOMMENDED_DNS_NAMESERVERS`. Mixing providers means a single
+ * operator's anycast outage falls through to a different provider.
+ */
+export declare const RECOMMENDED_DNS_NAMESERVERS: readonly string[];
+/** Raised when an error parsing a report occurs. */
+export declare class ParserError extends Error {
+  override name: string;
+}
+/** Raised when an invalid DMARC report is encountered. */
+export declare class InvalidDMARCReport extends ParserError {
+  override name: string;
+}
+/** Raised when an invalid SMTP TLS report is encountered. */
+export declare class InvalidSMTPTLSReport extends ParserError {
+  override name: string;
+}
+/** Raised when an invalid DMARC aggregate report is encountered. */
+export declare class InvalidAggregateReport extends InvalidDMARCReport {
+  override name: string;
+}
+/** Raised when an invalid DMARC failure report is encountered. */
+export declare class InvalidFailureReport extends InvalidDMARCReport {
+  override name: string;
+}
+/** Backward-compatible alias of {@link InvalidFailureReport}. */
+export declare const InvalidForensicReport: typeof InvalidFailureReport;
+/**
+ * Raised when an email is over the configured size or structure limits
+ * (`maxEmailSize`, `maxMimeParts`, `maxHeaderLines`,
+ * `maxExpandedEmailSize`); parsedmarc has no such limits. Mailbox processing
+ * treats the message as invalid.
+ */
+export declare class EmailTooLargeError extends ParserError {
+  override name: string;
+}
+/** The error for an email of `size` bytes over the `limit` (`maxEmailSize`). */
+export declare function emailTooLargeError(size: number, limit: number): EmailTooLargeError;
+/** Raised when an error parsing the email occurs. */
+export declare class EmailParserError extends Error {
+  override name: string;
+}
+/** Raised when an error occurs when downloading a file. */
+export declare class DownloadError extends Error {
+  override name: string;
+}
+/**
+ * Enrichment can't work for any record: nothing is wrong with the report
+ * being parsed. Unlike a bad record, it must not be skipped, or a report
+ * loses all its records and still looks parsed. parsedmarc has no such
+ * class.
+ */
+export declare class EnrichmentError extends Error {
+  override name: string;
+}
+/**
+ * The {@link EnrichmentError} behind `error`, or `null`: report parsers wrap
+ * whatever fails in a report-level error, keeping it in `cause`.
+ */
+export declare function findEnrichmentError(error: unknown): EnrichmentError | null;
+/** Raised when the IPinfo API rejects the configured token. */
+export declare class InvalidIPinfoAPIKey extends EnrichmentError {
+  override name: string;
+}
+/** Raised when no IP database can be opened. */
+export declare class IPDatabaseError extends EnrichmentError {
+  override name: string;
+  /** The system error code (`ENOENT`) of a missing file, if any. */
+  readonly code: string | undefined;
+  constructor(message: string, options?: ErrorOptions & {
+    code?: string;
+  });
+}
+export declare const NOTSET = 0;
+export declare const DEBUG = 10;
+export declare const INFO = 20;
+export declare const WARNING = 30;
+export declare const ERROR = 40;
+export declare const CRITICAL = 50;
+/** Name of the level, or `Level <n>` for custom levels (as in Python). */
+export declare function getLevelName(level: number): string;
+interface LogRecord {
+  name: string;
+  level: number;
+  levelName: string;
+  message: string;
+  /** Milliseconds since the epoch. */
+  created: number;
+  /** Error passed to `exception()` / `log(..., { error })`. */
+  error?: unknown;
+  /** Extra fields, like Python's `extra=`; filters may add to it. */
+  extra: Record<string, unknown>;
+}
+interface LogOptions {
+  error?: unknown;
+  extra?: Record<string, unknown>;
+}
+type LogFilter = (record: LogRecord) => boolean;
+type LogFormatter = (record: LogRecord) => string;
+/** Python's default `asctime`: local time, `2026-10-24 03:17:13,123`. */
+export declare function formatAsctime(created: number): string;
+/** `LEVEL:name:message`, the format of Python's `assertLogs` output. */
+export declare function basicFormat(record: LogRecord): string;
+/** Console format used by `configureLogging()`. */
+export declare function consoleFormat(record: LogRecord): string;
+/** Log file format used by `configureLogging()`. */
+export declare function fileFormat(record: LogRecord): string;
+export declare abstract class Handler {
+  level: number;
+  formatter: LogFormatter;
+  readonly filters: LogFilter[];
+  setLevel(level: number): void;
+  setFormatter(formatter: LogFormatter): void;
+  addFilter(filter: LogFilter): void;
+  removeFilter(filter: LogFilter): void;
+  format(record: LogRecord): string;
+  /** Apply level and filters, then emit. Errors in `emit` never propagate. */
+  handle(record: LogRecord): void;
+  /** Like Python's `Handler.handleError`: report to stderr, keep going. */
+  handleError(record: LogRecord, error: unknown): void;
+  abstract emit(record: LogRecord): void;
+  flush(): void;
+  close(): void;
+}
+/** Discards every record. */
+export declare class NullHandler extends Handler {
+  emit(_record: LogRecord): void;
+}
+interface WritableTextStream {
+  write: (text: string) => unknown;
+}
+/** Writes formatted records to a stream (stderr by default). */
+export declare class StreamHandler extends Handler {
+  readonly stream: WritableTextStream;
+  constructor(stream?: WritableTextStream);
+  emit(record: LogRecord): void;
+}
+/** Appends formatted records to a file, synchronously and in order. */
+export declare class FileHandler extends StreamHandler {
+  /** Absolute path of the log file, like Python's `baseFilename`. */
+  readonly baseFilename: string;
+  private fd;
+  constructor(filename: string, mode?: "a" | "w");
+  override close(): void;
+}
+export declare class Logger {
+  readonly name: string;
+  level: number;
+  readonly handlers: Handler[];
+  readonly filters: LogFilter[];
+  disabled: boolean;
+  constructor(name: string);
+  setLevel(level: number): void;
+  getEffectiveLevel(): number;
+  isEnabledFor(level: number): boolean;
+  addHandler(handler: Handler): void;
+  removeHandler(handler: Handler): void;
+  hasHandlers(): boolean;
+  addFilter(filter: LogFilter): void;
+  removeFilter(filter: LogFilter): void;
+  log(level: number, message: string, options?: LogOptions): void;
+  debug(message: string, options?: LogOptions): void;
+  info(message: string, options?: LogOptions): void;
+  warning(message: string, options?: LogOptions): void;
+  error(message: string, options?: LogOptions): void;
+  critical(message: string, options?: LogOptions): void;
+  /** Log at ERROR with the error attached (Python's `logger.exception`). */
+  exception(message: string, error: unknown, options?: LogOptions): void;
+}
+/** Return the shared logger with this name, creating it on first use. */
+export declare function getLogger(name: string): Logger;
+/** The library logger (parsedmarc's `parsedmarc.log.logger`). */
+export declare const logger: Logger;
+/**
+ * Configure the library logger's handlers: set the level, add a stderr
+ * handler if there is none, and add a file handler for `logFile` unless one
+ * for the same absolute path is already attached (so repeated calls, e.g. a
+ * SIGHUP reload, never write each record twice).
+ */
+export declare function configureLogging(level: number, logFile?: string | null): void;
+/** Collects records; used by {@link captureLogs}. */
+export declare class CaptureHandler extends Handler {
+  readonly records: LogRecord[];
+  emit(record: LogRecord): void;
+}
+interface LogCapture {
+  /** Captured records, in order. */
+  readonly records: LogRecord[];
+  /** Captured records as `LEVEL:name:message` strings (like `assertLogs`). */
+  readonly output: string[];
+  /** Detach the capture handler and restore the logger's level. */
+  restore: () => void;
+}
+/**
+ * Capture records of `level` and above from a logger, like Python's
+ * `assertLogs`. Call `restore()` when done (e.g. in `afterEach`).
+ */
+export declare function captureLogs(target?: Logger | string, level?: number): LogCapture;
+/**
+ * Content types of the MIME part that carries a failure report's sample
+ * message (or only its headers).
+ */
+export declare const EMAIL_SAMPLE_CONTENT_TYPES: readonly string[];
+/** Fields of `parsedFailureReportsToCsv()`, in column order. */
+export declare const FAILURE_CSV_FIELDS: readonly string[];
+/** Options of {@link parseFailureReport}. */
+type ParseFailureReportOptions = Omit<ParserConfigInput, "normalizeTimespanThresholdHours">;
+/**
+ * Parse a DMARC failure report (the `message/feedback-report` part) and its
+ * sample (the RFC 822 message or headers).
+ *
+ * `msgDate` (the report email's date) is the arrival date when the report
+ * has no `Arrival-Date` field. Feedback-report fields parsedmarc doesn't
+ * know are kept, with camelCase keys (`Reported-URI` → `reportedUri`).
+ */
+export declare function parseFailureReport(feedbackReport: string, sample: string, msgDate: PyDateTime | null, options?: ParseFailureReportOptions): Promise<FailureReport>;
+/** Backward-compatible alias of {@link parseFailureReport}. */
+export declare const parseForensicReport: typeof parseFailureReport;
+/**
+ * Flatten failure reports into CSV rows (snake_case keys): every report
+ * field except the sample, with the source flattened into `source_*`, the
+ * sample's subject, and the list fields joined with commas.
+ */
+export declare function parsedFailureReportsToCsvRows(reports: FailureReport | FailureReport[]): CsvRow[];
+/** Backward-compatible alias of {@link parsedFailureReportsToCsvRows}. */
+export declare const parsedForensicReportsToCsvRows: typeof parsedFailureReportsToCsvRows;
+/** Failure reports as flat CSV, with headers. */
+export declare function parsedFailureReportsToCsv(reports: FailureReport | FailureReport[], options?: CsvOptions): string;
+/** Backward-compatible alias of {@link parsedFailureReportsToCsv}. */
+export declare const parsedForensicReportsToCsv: typeof parsedFailureReportsToCsv;
+interface PyJsonDumpsOptions {
+  /** `(item_separator, key_separator)`; Python's default is `(', ', ': ')`. */
+  separators?: readonly [string, string];
+  /**
+   * Called for values JSON can't represent, like Python's `default=`; its
+   * result is serialized instead. Without it they throw `TypeError`.
+   */
+  default?: (value: unknown) => unknown;
+  /** Pretty-print with this many spaces per level, like `indent=`. */
+  indent?: number | null;
+  /** Escape non-ASCII as `\uXXXX`, like `ensure_ascii=`. Default: true. */
+  ensureAscii?: boolean;
+  /**
+   * Write `NaN`, `Infinity` and `-Infinity` as `null`, for a consumer that
+   * expects standard JSON. Python writes them bare (`allow_nan=True`).
+   */
+  nonFiniteAsNull?: boolean;
+}
+/**
+ * A number as Python's `json.dumps()` writes it back after `json.loads()`
+ * (an exact int, or a float's `repr`), so values a JS number can't keep
+ * (`12345678901234567890`, `1.0`) survive a load/dump round trip.
+ */
+export declare class PyJsonNumber {
+  readonly text: string;
+  constructor(text: string);
+}
+/** Python's `json.dumps(value, separators=, default=, indent=, ensure_ascii=)`. */
+export declare function pyJsonDumps(value: unknown, options?: PyJsonDumpsOptions): string;
+/**
+ * A copy of `value` that `JSON.stringify()` serializes like Python's
+ * `json.dumps()` writes ints: every `bigint` (and `PyJsonNumber`) becomes a
+ * `JSON.rawJSON()` exact integer, where `JSON.stringify()` would throw on a
+ * bigint. For payloads that SDKs serialize themselves (Elasticsearch,
+ * OpenSearch, Azure Log Analytics). Arrays and plain objects are copied;
+ * other values are kept as they are.
+ */
+export declare function rawJsonIntegers(value: unknown): unknown;
+/** Raised by mailbox methods a backend does not implement. */
+export declare class NotImplementedError extends Error {
+  override name: string;
+}
+/** A folder/label operation targets a name that is already taken. */
+export declare class FolderExistsError extends Error {
+  override name: string;
+}
+/** A folder/label referenced by an operation does not exist. */
+export declare class FolderNotFoundError extends Error {
+  override name: string;
+}
+/** Backend identifier. */
+type MailboxKind = "imap" | "gmail" | "msgraph" | "maildir";
+/** Provider-specific message identifier (IMAP UID, Graph/Gmail ID, Maildir key). */
+type MessageId = string | number;
+interface FetchMessagesOptions {
+  /** Only messages received since this date (backend-specific format, e.g. `"2d"` or an ISO date). */
+  since?: string | null;
+  /** Maximum number of messages to return (0 or unset: all). */
+  batchSize?: number;
+}
+interface FetchMessageOptions {
+  /** Mark the message as read after fetching it. */
+  markRead?: boolean;
+  /**
+   * Largest message to download, in bytes. Backends that can learn the size
+   * first throw `EmailTooLargeError` instead of downloading a larger one
+   * (not marking it read). Not in mailsuite.
+   */
+  maxSize?: number | null;
+}
+interface MoveFolderOptions {
+  /** The folder's complete new path. */
+  newPath?: string | null;
+  /** The folder to move the source under, keeping its leaf name ("" = root). */
+  newParent?: string | null;
+  /** Create the destination's parent path if missing. */
+  create?: boolean;
+}
+interface MergeFoldersOptions {
+  /** Create the destination if missing. */
+  create?: boolean;
+  /** Keep the emptied source folders. */
+  keepSourceFolders?: boolean;
+}
+interface WatchOptions {
+  /** Called with this connection whenever the watcher fires. */
+  checkCallback: (connection: MailboxConnection) => Promise<void> | void;
+  /** Polling interval (or IDLE timeout), in seconds. */
+  checkTimeout: number;
+  /** When it returns true, the watcher returns so the caller can reload config. */
+  configReloading?: (() => boolean) | null;
+  /** Aborts the watch loop. */
+  signal?: AbortSignal;
+}
+interface SendMessageOptions {
+  messageFrom: string;
+  messageTo?: string[] | null;
+  messageCc?: string[] | null;
+  messageBcc?: string[] | null;
+  subject?: string | null;
+  messageHeaders?: Record<string, string> | null;
+  /** `[filename, content]` pairs. */
+  attachments?: [string, Uint8Array][] | null;
+  plainMessage?: string | null;
+  htmlMessage?: string | null;
+  /** Save a copy to Sent Items (Microsoft Graph only). Default: true. */
+  saveToSentItems?: boolean;
+}
+export declare abstract class MailboxConnection {
+  abstract readonly kind: MailboxKind;
+  /**
+   * Tells this mailbox from others whose message IDs may be the same, for
+   * state kept between calls (several connection objects to one mailbox
+   * share it). Backends whose IDs are unique on their own leave it empty.
+   */
+  get mailboxIdentity(): string;
+  createFolder(_folderName: string): Promise<void>;
+  deleteFolder(_folderName: string): Promise<void>;
+  /**
+   * Rename a folder. Implementations call `ensureNoFolderConflict()` first,
+   * so renaming onto an existing name throws `FolderExistsError`.
+   */
+  renameFolder(_oldName: string, _newName: string): Promise<void>;
+  folderExists(_folderName: string): Promise<boolean>;
+  /** Throw `FolderExistsError` if `folderName` already exists. */
+  protected ensureNoFolderConflict(folderName: string): Promise<void>;
+  /**
+   * Move a folder (and its contents). Give exactly one of `newPath` (the
+   * complete new path) or `newParent` (keep the leaf name).
+   */
+  moveFolder(source: string, options: MoveFolderOptions): Promise<void>;
+  /** Move every message of each source folder into `destination`. */
+  mergeFolders(sources: string | string[], destination: string, options?: MergeFoldersOptions): Promise<void>;
+  /** Backend-specific relocation, called by `moveFolder()` after validation. */
+  protected doMoveFolder(_source: string, _targetParent: string, _targetPath: string): Promise<void>;
+  /** Move one message during `mergeFolders()`. Defaults to `moveMessage()`. */
+  protected moveMessageFrom(messageId: MessageId, _source: string, destination: string): Promise<void>;
+  /** Identifiers of the messages in a folder. */
+  fetchMessages(_reportsFolder: string, _options?: FetchMessagesOptions): Promise<MessageId[]>;
+  /** Raw RFC 822 contents of a message. */
+  fetchMessage(_messageId: MessageId, _options?: FetchMessageOptions): Promise<string>;
+  deleteMessage(_messageId: MessageId): Promise<void>;
+  moveMessage(_messageId: MessageId, _folderName: string): Promise<void>;
+  /** Send a no-op to keep the connection alive (if applicable). */
+  keepalive(): Promise<void>;
+  /** Watch for new messages, calling `checkCallback` on new mail or each interval. */
+  watch(_options: WatchOptions): Promise<void>;
+  /** Send through the backend's native API. Returns a message ID when available. */
+  sendMessage(_options: SendMessageOptions): Promise<string | null>;
+  /** Release network resources. No-op for backends without a connection. */
+  close(): Promise<void>;
+}
+/** What a save callback returns: `false` means "not saved". */
+type SaveCallbackResult = boolean | null | undefined | void;
+/**
+ * Called once per fetched batch with only that batch's reports, before any
+ * of its messages is moved or deleted. Returning `false` (or throwing)
+ * marks the batch unsaved; anything else commits it.
+ */
+type SaveCallback = (results: ParsingResults) => SaveCallbackResult | Promise<SaveCallbackResult>;
+/** Mailbox-handling options shared by both entry points (not part of `config`). */
+interface MailboxProcessingOptions extends ParserConfigInput {
+  /** The folder where reports can be found. Default: `"INBOX"`. */
+  reportsFolder?: string;
+  /** The folder to move processed mail to. Default: `"Archive"`. */
+  archiveFolder?: string;
+  /** Delete messages after processing them. Default: false. */
+  delete?: boolean;
+  /**
+   * Delete aggregate report messages instead of moving them to the
+   * `Aggregate` archive subfolder. `null`/unset inherits `delete`.
+   */
+  deleteAggregate?: boolean | null;
+  /**
+   * Delete failure report messages instead of moving them to the `Failure`
+   * archive subfolder. `null`/unset inherits `delete`.
+   */
+  deleteFailure?: boolean | null;
+  /**
+   * Delete SMTP TLS report messages instead of moving them to the
+   * `SMTP-TLS` archive subfolder. `null`/unset inherits `delete`.
+   */
+  deleteSmtpTls?: boolean | null;
+  /**
+   * Delete unparseable messages instead of moving them to the `Invalid`
+   * archive subfolder. `null`/unset inherits `delete`.
+   */
+  deleteInvalid?: boolean | null;
+  /** Do not move or delete messages after processing them. Default: false. */
+  test?: boolean;
+  /** Messages to read and process before saving (0: no limit). Default: 10. */
+  batchSize?: number;
+  /**
+   * Only messages since this relative time (`5m`, `3h`, `2d`, `1w`). Any
+   * other string falls back to one day, with a warning.
+   */
+  since?: string | null;
+  /**
+   * Worker threads used to parse messages. Fetching, archiving and dedup
+   * stay sequential; with `nProcs > 1`, invalid messages are disposed of
+   * after the parsing phase. Default: 1.
+   */
+  nProcs?: number;
+  /**
+   * Retries a message gets after its batch was first reported unsaved,
+   * before it moves to the `Unsaved` archive subfolder (never deleted).
+   * `0` moves it on the first failed save; negative values throw
+   * `ValueError`. Default: 2.
+   */
+  maxUnsavedRetries?: number;
+}
+/** Options of {@link getDmarcReportsFromMailbox}. */
+interface GetDmarcReportsFromMailboxOptions extends MailboxProcessingOptions {
+  /** Results from the previous run, to accumulate into. */
+  results?: ParsingResults | null;
+  /** Create the destination folders (not used in watch). Default: true. */
+  createFolders?: boolean;
+  /**
+   * Called once per batch before its messages are archived or deleted.
+   * Returning `false` leaves them in `reportsFolder` for retry (or moves
+   * them to `Unsaved` once retries run out) and keeps their aggregate
+   * report keys out of the dedup cache. Throwing counts as unsaved too, and
+   * the error is rethrown after that bookkeeping. Still invoked in `test`
+   * mode, where the mailbox and retry counters are never touched.
+   */
+  saveCallback?: SaveCallback | null;
+}
+/** Options of {@link watchInbox}. */
+interface WatchInboxOptions extends MailboxProcessingOptions {
+  /** Seconds to wait for an IMAP IDLE response or between checks. Default: 30. */
+  checkTimeout?: number;
+  /** Returns true when a config reload or shutdown was requested. */
+  configReloading?: (() => boolean) | null;
+  /** Aborts the watch loop. */
+  signal?: AbortSignal;
+}
+/**
+ * Fetches and parses DMARC and SMTP TLS reports from a mailbox, then
+ * archives (or deletes) each message by report type: `<archive>/Aggregate`,
+ * `Failure`, `SMTP-TLS`, `Invalid`, and `Unsaved` for batches the
+ * `saveCallback` kept failing to save.
+ *
+ * Parsing options (or `config`) work as in every parsing function; the
+ * mailbox options always apply. With `batchSize: 0` the reports folder is
+ * re-checked after the run and new messages are processed recursively.
+ *
+ * Throws an `EnrichmentError` when enrichment fails for every report
+ * (a revoked IPinfo token, no readable IP database): the batch stays in
+ * `reportsFolder`, unsaved, for the next run. Unlike parsedmarc, which
+ * files those reports as invalid or empty, and deletes them with `delete`.
+ *
+ * Throws `ValueError` when a delete option is combined with `test`, when
+ * `maxUnsavedRetries` is negative, or without a connection.
+ */
+export declare function getDmarcReportsFromMailbox(connection: MailboxConnection, options?: GetDmarcReportsFromMailboxOptions): Promise<ParsingResults>;
+/**
+ * Watches the mailbox for new messages and processes them with
+ * {@link getDmarcReportsFromMailbox} on every check, with `callback` as its
+ * `saveCallback`: it runs once per batch, before the batch's messages are
+ * archived or deleted, and returning `false` (or throwing) leaves them for
+ * the next check. What happens to a thrown error is backend-specific: the
+ * IMAP and Maildir watch loops log it and keep checking; Gmail and
+ * Microsoft Graph end the watch.
+ *
+ * Throws `ValueError` for a negative `maxUnsavedRetries` before watching.
+ */
+export declare function watchInbox(mailboxConnection: MailboxConnection, callback: SaveCallback, options?: WatchInboxOptions): Promise<void>;
+interface SaveOutputOptions {
+  /** The path to the directory to save in (default `output`; `~` expands). */
+  outputDirectory?: string;
+  /** Filename for the aggregate JSON file (default `aggregate.json`). */
+  aggregateJsonFilename?: string;
+  /** Filename for the failure JSON file (default `failure.json`). */
+  failureJsonFilename?: string;
+  /** Filename for the SMTP TLS JSON file (default `smtp_tls.json`). */
+  smtpTlsJsonFilename?: string;
+  /** Filename for the aggregate CSV file (default `aggregate.csv`). */
+  aggregateCsvFilename?: string;
+  /** Filename for the failure CSV file (default `failure.csv`). */
+  failureCsvFilename?: string;
+  /** Filename for the SMTP TLS CSV file (default `smtp_tls.csv`). */
+  smtpTlsCsvFilename?: string;
+  /**
+   * Prefix CSV text cells that a spreadsheet would run as a formula with
+   * `'` (see `CsvOptions.formulaEscape`). Default true, like parsedmarc.
+   */
+  csvFormulaEscape?: boolean;
+}
+interface GetReportZipOptions {
+  /** See {@link SaveOutputOptions.csvFormulaEscape}. Default true. */
+  csvFormulaEscape?: boolean;
+}
+/**
+ * Append `reports` to a JSON array on disk, creating the file if needed.
+ *
+ * Reads the existing array (if the file exists and parses cleanly), merges
+ * the new reports onto the end, and replaces the file with a single valid
+ * JSON array (indented by 2, keys in snake_case like parsedmarc's output).
+ * A file above {@link MAX_REWRITTEN_JSON_BYTES} that already has that layout
+ * keeps its bytes and only gets the new entries, which gives the same result.
+ * A file that can't be used (corrupt, unreadable, a root that is not an
+ * array) is moved to `<filename>.corrupt-<timestamp>` with a warning, never
+ * discarded. An empty `reports` leaves the file alone (and creates nothing).
+ * Calls for one file run in turn; other processes are not coordinated with.
+ *
+ * Throws `ValueError` when a single report is too large to serialize.
+ */
+export declare function appendJson(filename: string, reports: readonly AggregateReport[] | readonly FailureReport[] | readonly SMTPTLSReport[]): Promise<void>;
+/**
+ * Append CSV text to a file. When the file already has content, the header
+ * line of `csv` is dropped; a header-only `csv` then writes nothing.
+ */
+export declare function appendCsv(filename: string, csv: string): Promise<void>;
+/**
+ * Save report data in the given directory.
+ *
+ * Writes the JSON and CSV files of each report type, then the message
+ * sample of each failure report to a `samples` subdirectory, named after the
+ * sample's own `subject` header run through {@link getFilenameSafeString},
+ * falling back to `sample` when sanitizing leaves nothing. A subject comes
+ * from an untrusted sender, so it is sanitized here, at write time; a
+ * caller-supplied `filenameSafeSubject` is not trusted and not used. Names
+ * that collide, in this call or with a file already there, get a ` (1)`,
+ * ` (2)`, … suffix.
+ *
+ * Throws `ValueError` if `outputDirectory` exists and is not a directory.
+ */
+export declare function saveOutput(results: ParsingResults, options?: SaveOutputOptions): Promise<void>;
+/**
+ * Creates a zip file of parsed report output: {@link saveOutput} into a
+ * temporary directory, then every file in it.
+ *
+ * The layout is parsedmarc's, except that parsedmarc also stores each file
+ * of `samples/` a second time as `../<name>` (its `add_subdir()` swaps the
+ * `relpath` arguments). Those entries point outside the extraction
+ * directory, a path-traversal risk for whoever unzips the attachment, so
+ * they are left out; every file is still in the zip once.
+ */
+export declare function getReportZip(results: ParsingResults, options?: GetReportZipOptions): Promise<Uint8Array>;
+/**
+ * Runs send tasks one after another. Sockets are unref'd, like Python's,
+ * which never hold the interpreter open; while sends are queued a timer
+ * keeps the event loop alive so they are not cut short.
+ */
+declare class SendQueue {
+  #private;
+  /** Queue `task`; its error goes to `onError` (never rejects the queue). */
+  push(task: () => Promise<void>, onError: (error: unknown) => void): void;
+  /** Resolves once every queued send has finished. */
+  drain(): Promise<void>;
+}
+/**
+ * Messages a stream handler could not deliver. `emit()` can't report them
+ * and `SendQueue` runs on, so the client's save method asks here after
+ * draining and fails, which keeps the batch from counting as saved.
+ */
+declare class SendFailures {
+  #private;
+  record(error: unknown): void;
+  /** The failures since the last call, or `null` when there were none. */
+  take(): {
+    count: number;
+    error: unknown;
+  } | null;
+}
+interface GelfHandlerOptions {
+  /** GELF spec version (default `1.1`). */
+  version?: string;
+  /** Send the record's extra fields as `_<name>` (default false). */
+  includeExtraFields?: boolean;
+  /** zlib-compress each message (default: true for UDP, false otherwise). */
+  compress?: boolean;
+}
+/** pygelf's `BaseHandler`: turns records into GELF. */
+declare abstract class BaseGelfHandler extends Handler {
+  readonly host: string;
+  readonly port: number;
+  readonly version: string;
+  readonly includeExtraFields: boolean;
+  readonly compress: boolean;
+  /** The `host` field: this machine's hostname. */
+  readonly domain: string;
+  protected readonly queue: SendQueue;
+  protected readonly failures: SendFailures;
+  constructor(host: string, port: number, options: GelfHandlerOptions, compressDefault: boolean);
+  convertRecordToGelf(record: LogRecord): Uint8Array;
+  /** The bytes sent for one record. */
+  makePickle(record: LogRecord): Uint8Array;
+  protected abstract send(data: Uint8Array): Promise<void>;
+  emit(record: LogRecord): void;
+  /** Resolves once every record emitted so far has been sent (or dropped). */
+  drain(): Promise<void>;
+  /** The messages dropped since the last call (always none over UDP). */
+  takeFailures(): {
+    count: number;
+    error: unknown;
+  } | null;
+  override close(): void;
+  abstract closeAsync(): Promise<void>;
+}
+/**
+ * pygelf's `GelfTcpHandler` over Python's `SocketHandler`: connects on the
+ * first record, sends each message NUL-terminated, and on a connection or
+ * send error closes the socket and retries later with exponential back-off
+ * (1 s doubling up to 30 s). Unlike Python, a message that fails on a stale
+ * connection is sent again once over a new one, and one that is still lost
+ * is recorded in `failures` (`SocketHandler` drops it without a trace).
+ */
+export declare class GelfTcpHandler extends BaseGelfHandler {
+  #private;
+  sock: Socket$1 | null;
+  /** Epoch ms before which no reconnect is attempted. */
+  retryTime: number | null;
+  retryPeriod: number;
+  constructor(host: string, port: number, options?: GelfHandlerOptions);
+  /** NUL-terminated: "if you send the message over tcp, it should always be null terminated". */
+  override makePickle(record: LogRecord): Uint8Array;
+  /** Open the connection (`SocketHandler.makeSocket`). */
+  protected makeSocket(timeout?: number): Promise<Socket$1>;
+  /** `SocketHandler.createSocket()`: connect unless backing off. */
+  createSocket(): Promise<void>;
+  protected send(data: Uint8Array): Promise<void>;
+  closeAsync(): Promise<void>;
+}
+interface GelfUdpHandlerOptions extends GelfHandlerOptions {
+  /** Maximum datagram size before chunking (default 1300). */
+  chunkSize?: number;
+}
+/**
+ * pygelf's `GelfUdpHandler`: zlib-compressed datagrams (IPv4, like Python's
+ * `DatagramHandler`), split into GELF chunks above `chunkSize` bytes.
+ */
+export declare class GelfUdpHandler extends BaseGelfHandler {
+  readonly chunkSize: number;
+  sock: Socket | null;
+  constructor(host: string, port: number, options?: GelfUdpHandlerOptions);
+  protected send(data: Uint8Array): Promise<void>;
+  closeAsync(): Promise<void>;
+}
+interface GelfTlsOptions {
+  /**
+   * Verify the server certificate and hostname (default true). pygelf
+   * defaults to false; see the deviations in the architecture notes.
+   */
+  validate?: boolean;
+  /** CA bundle file, added to the system CAs. */
+  caCerts?: string | null;
+  /** Client certificate file (may also hold the key). */
+  certfile?: string | null;
+  /** Client private key file. */
+  keyfile?: string | null;
+}
+/** pygelf's `GelfTlsHandler`: {@link GelfTcpHandler} over TLS (IPv4). */
+export declare class GelfTlsHandler extends GelfTcpHandler {
+  readonly tlsOptions: ConnectionOptions;
+  constructor(host: string, port: number, options?: GelfHandlerOptions & GelfTlsOptions);
+  protected override makeSocket(timeout?: number): Promise<Socket$1>;
+}
+/** parsedmarc's thread-local `log_context_data`: the row being logged. */
+export declare const logContextData: {
+  parsedmarc?: unknown;
+};
+/** Copies `logContextData.parsedmarc` onto each record as `parsedmarc`. */
+export declare class ContextFilter {
+  readonly filter: (record: LogRecord) => boolean;
+}
+/** Raised when messages could not be delivered over TCP or TLS. */
+export declare class GelfError extends Error {
+  override name: string;
+}
+type GelfMode = "udp" | "tcp" | "tls";
+interface GelfClientOptions {
+  /** TLS settings for `tls` mode. */
+  tls?: GelfTlsOptions;
+}
+type GelfHandler = GelfUdpHandler | GelfTcpHandler | GelfTlsHandler;
+/** A client for the Graylog Extended Log Format. */
+export declare class GelfClient {
+  #private;
+  readonly host: string;
+  readonly port: number;
+  readonly logger: Logger;
+  readonly gelfMode: Readonly<Record<GelfMode, (host: string, port: number) => GelfHandler>>;
+  /** The GELF handler attached to {@link logger}. */
+  handler: Handler;
+  /**
+   * @param host - The GELF host
+   * @param port - The GELF port
+   * @param mode - The GELF transport mode: `udp`, `tcp` or `tls`
+   */
+  constructor(host: string, port: number, mode: string, options?: GelfClientOptions);
+  saveAggregateReportToGelf(aggregateReports: AggregateReport | AggregateReport[]): Promise<void>;
+  saveFailureReportToGelf(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  /** Backward-compatible alias of {@link saveFailureReportToGelf}. */
+  saveForensicReportToGelf(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  saveSmtpTlsReportToGelf(smtpTlsReports: SMTPTLSReport | SMTPTLSReport[]): Promise<void>;
+  /** Remove and close the GELF handler, releasing its connection. */
+  close(): Promise<void>;
+}
+/** Raised when a Splunk API error occurs. */
+export declare class SplunkError extends Error {
+  override name: string;
+}
+interface HECClientOptions {
+  /** The source name (default `"tsdmarc"`). */
+  source?: string;
+  /** Verify TLS certificates (default `true`). */
+  verify?: boolean;
+  /** Seconds to wait for the server before giving up (default 60). */
+  timeout?: number;
+}
+type JsonObject = Record<string, unknown>;
+/** A client for a Splunk HTTP Events Collector (HEC). */
+export declare class HECClient {
+  #private;
+  readonly url: string;
+  readonly accessToken: string;
+  readonly index: string;
+  readonly host: string;
+  readonly source: string;
+  readonly timeout: number;
+  readonly verify: boolean;
+  /** Headers sent with every request. */
+  readonly headers: Readonly<Record<string, string>>;
+  /**
+   * @param url - The URL of the HEC; only its scheme and host are used
+   * @param accessToken - The HEC access token
+   * @param index - The name of the index
+   */
+  constructor(url: string, accessToken: string, index: string, options?: HECClientOptions);
+  /** The `host`, `source` and `index` fields every event carries. */
+  get commonData(): Readonly<JsonObject>;
+  /** Saves aggregate DMARC reports to Splunk, one event per record. */
+  saveAggregateReportsToSplunk(aggregateReports: AggregateReport | AggregateReport[]): Promise<void>;
+  /** Saves failure DMARC reports to Splunk, one event per report. */
+  saveFailureReportsToSplunk(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  /** Backward-compatible alias of {@link saveFailureReportsToSplunk}. */
+  saveForensicReportsToSplunk(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  /** Saves SMTP TLS reports to Splunk, one event per report. */
+  saveSmtpTlsReportsToSplunk(reports: SMTPTLSReport | SMTPTLSReport[]): Promise<void>;
+  /** Close the client: abort in-flight requests and refuse new ones. */
+  close(): void;
+}
+export declare const LOKI_PUSH_PATH = "/loki/api/v1/push";
+export declare const LOKI_TIMESTAMP_MODES: readonly LokiTimestampMode[];
+export declare const LOKI_DEFAULT_LABEL_FIELDS: readonly string[];
+type LokiTimestampMode = "ingest" | "report_begin";
+type LokiReportType = "aggregate" | "failure" | "smtp_tls";
+/** Raised when pushing to Loki fails. */
+export declare class LokiError extends Error {
+  override name: string;
+}
+interface LokiClientOptions {
+  /**
+   * Static stream labels, merged over the defaults `job=parsedmarc` and
+   * `host=<host name>`.
+   */
+  labels?: Readonly<Record<string, string>> | null;
+  /**
+   * Record fields used as stream labels (default `report_type`, `domain`);
+   * keep them to fields with few distinct values.
+   */
+  labelFields?: readonly string[] | null;
+  /**
+   * `ingest` (time of the push, the default) or `report_begin` (begin of the
+   * reported period; Loki rejects entries older than its
+   * `reject_old_samples_max_age`).
+   */
+  timestamp?: LokiTimestampMode;
+  /** Basic auth user. */
+  username?: string | null;
+  /** Basic auth password (used only with `username`). */
+  password?: string | null;
+  /** Bearer token, instead of basic auth. */
+  token?: string | null;
+  /** Sent as `X-Scope-OrgID`. */
+  tenantId?: string | null;
+  /** Verify TLS certificates (default `true`). */
+  verify?: boolean;
+  /** Request timeout in seconds (default 60). */
+  timeout?: number;
+  /** Maximum log lines per push request (default 1000). */
+  batchSize?: number;
+}
+/** A client for the Grafana Loki push API. */
+export declare class LokiClient {
+  #private;
+  /** The push URL (with its userinfo, if any). */
+  readonly url: string;
+  readonly labels: Readonly<Record<string, string>>;
+  readonly labelFields: readonly string[];
+  readonly timestamp: LokiTimestampMode;
+  readonly timeout: number;
+  readonly batchSize: number;
+  readonly verify: boolean;
+  /** Headers sent with every request. */
+  readonly headers: Readonly<Record<string, string>>;
+  /**
+   * Every report record becomes one JSON log line.
+   *
+   * @param url - Loki base URL (`/loki/api/v1/push` is appended when the URL
+   *   has no path) or the full push URL
+   */
+  constructor(url: string, options?: LokiClientOptions);
+  saveAggregateReportToLoki(aggregateReports: AggregateReport | AggregateReport[]): Promise<void>;
+  saveFailureReportToLoki(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  /** Backward-compatible alias of {@link saveFailureReportToLoki}. */
+  saveForensicReportToLoki(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  saveSmtpTlsReportToLoki(smtpTlsReports: SMTPTLSReport | SMTPTLSReport[]): Promise<void>;
+  /** Close the client: abort in-flight requests and refuse new ones. */
+  close(): void;
+}
+/** `LOG_USER`, SysLogHandler's default facility. */
+export declare const LOG_USER = 1;
+type SyslogSocketType = "dgram" | "stream";
+interface SysLogHandlerOptions {
+  /** `socket.SOCK_DGRAM` (UDP, the default) or `SOCK_STREAM` (TCP). */
+  socktype?: SyslogSocketType;
+  /** Seconds for connect and send; `null` (the default) waits forever. */
+  timeout?: number | null;
+  /** Turns each new TCP connection into the one to use (TLS). */
+  wrapSocket?: (socket: Socket$1) => Promise<Socket$1>;
+}
+/**
+ * Port of `logging.handlers.SysLogHandler` for a `(host, port)` address:
+ * sends `<PRI>message\0` per record, as one datagram (UDP) or on one
+ * connection (TCP, no octet counting, like Python). Create it with
+ * {@link SysLogHandler.create}, which resolves the host and, for TCP,
+ * connects, like Python's constructor. Unlike Python, which keeps using a
+ * dead TCP socket forever, a failed send reconnects (with `SocketHandler`'s
+ * back-off) and tries once more; what is still lost is in {@link takeFailures}.
+ */
+export declare class SysLogHandler extends Handler {
+  #private;
+  readonly address: readonly [string, number];
+  readonly facility: number;
+  readonly socktype: SyslogSocketType;
+  /** Seconds for each send on a stream socket; `null` waits forever. */
+  timeout: number | null;
+  /** The datagram socket, or the (possibly TLS-wrapped) stream socket. */
+  socket: Socket | Socket$1 | null;
+  protected constructor(address: readonly [string, number], options: SysLogHandlerOptions);
+  /** Create the handler and its socket (throws if that fails). */
+  static create(address: readonly [string, number], options?: SysLogHandlerOptions): Promise<SysLogHandler>;
+  /**
+   * Resolve the address and create the socket; for TCP, connect to the
+   * first address that accepts, like Python's `createSocket()`.
+   */
+  createSocket(): Promise<void>;
+  /** `SysLogHandler.encodePriority()` with `mapPriority()`. */
+  encodePriority(levelName: string): number;
+  emit(record: LogRecord): void;
+  /** Resolves once every record emitted so far has been sent (or failed). */
+  drain(): Promise<void>;
+  /** The messages lost over TCP/TLS since the last call (UDP has no record). */
+  takeFailures(): {
+    count: number;
+    error: unknown;
+  } | null;
+  /** Close the socket (after the queued sends). Use {@link closeAsync} to wait. */
+  override close(): void;
+  /** Send what is queued, then close the socket. */
+  closeAsync(): Promise<void>;
+}
+interface SyslogClientOptions {
+  /** `udp` (default), `tcp` or `tls`; case-insensitive. */
+  protocol?: string;
+  /** CA certificate file for TLS server verification, added to the system CAs. */
+  cafilePath?: string | null;
+  /** Client certificate file for TLS authentication. */
+  certfilePath?: string | null;
+  /** Client private key file for TLS authentication. */
+  keyfilePath?: string | null;
+  /** Connection timeout in seconds for TCP/TLS (default 5). */
+  timeout?: number;
+  /** Connection attempts for TCP/TLS (default 3). */
+  retryAttempts?: number;
+  /** Seconds between connection attempts (default 5). */
+  retryDelay?: number;
+}
+/** Raised when messages could not be delivered over TCP or TLS. */
+export declare class SyslogError extends Error {
+  override name: string;
+}
+/** A client for Syslog. */
+export declare class SyslogClient {
+  #private;
+  readonly serverName: string;
+  readonly serverPort: number;
+  readonly protocol: string;
+  readonly timeout: number;
+  readonly retryAttempts: number;
+  readonly retryDelay: number;
+  readonly logger: Logger;
+  /** The syslog handler attached to {@link logger}. */
+  logHandler: Handler;
+  protected constructor(serverName: string, serverPort: number, options: SyslogClientOptions);
+  /**
+   * Create a SyslogClient: resolves the server and, for TCP/TLS, connects
+   * (retrying `retryAttempts` times, `retryDelay` seconds apart), so a bad
+   * address fails here as Python's constructor does.
+   *
+   * @param serverName - The Syslog server
+   * @param serverPort - The Syslog port
+   */
+  static create(serverName: string, serverPort: number, options?: SyslogClientOptions): Promise<SyslogClient>;
+  /** Creates a SysLogHandler with the specified protocol and TLS settings. */
+  protected createSyslogHandler(options: SyslogClientOptions): Promise<SysLogHandler>;
+  /** TCP connection wrapped in TLS ≥ 1.2, verifying the server. */
+  protected createTlsHandler(options: SyslogClientOptions): Promise<SysLogHandler>;
+  saveAggregateReportToSyslog(aggregateReports: AggregateReport | AggregateReport[]): Promise<void>;
+  saveFailureReportToSyslog(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  /** Backward-compatible alias of {@link saveFailureReportToSyslog}. */
+  saveForensicReportToSyslog(failureReports: FailureReport | FailureReport[]): Promise<void>;
+  saveSmtpTlsReportToSyslog(smtpTlsReports: SMTPTLSReport | SMTPTLSReport[]): Promise<void>;
+  /** Remove and close the syslog handler, releasing its socket. */
+  close(): Promise<void>;
+}
+type WebhookPayload = string | Uint8Array | Record<string, string>;
+interface WebhookClientOptions {
+  /** Seconds to wait for each webhook call (default 60); `null` waits forever. */
+  timeout?: number | null;
+  /**
+   * Throw network errors, timeouts and non-2xx responses instead of only
+   * logging them (default `false`, as parsedmarc). Turn it on when the
+   * caller has to know a report was not delivered, e.g. before deleting
+   * its email; the CLI does.
+   */
+  throwOnError?: boolean;
+}
+/** A client for webhooks. */
+export declare class WebhookClient {
+  #private;
+  readonly aggregateUrl: string;
+  readonly failureUrl: string;
+  readonly smtpTlsUrl: string;
+  readonly timeout: number | null;
+  readonly throwOnError: boolean;
+  /** Headers sent with every request. */
+  readonly headers: Readonly<Record<string, string>>;
+  /**
+   * @param aggregateUrl - The aggregate report webhook URL
+   * @param failureUrl - The failure report webhook URL
+   * @param smtpTlsUrl - The SMTP TLS report webhook URL
+   */
+  constructor(aggregateUrl: string, failureUrl: string, smtpTlsUrl: string, options?: WebhookClientOptions);
+  saveFailureReportToWebhook(report: string): Promise<void>;
+  /** Backward-compatible alias of {@link saveFailureReportToWebhook}. */
+  saveForensicReportToWebhook(report: string): Promise<void>;
+  saveSmtpTlsReportToWebhook(report: string): Promise<void>;
+  saveAggregateReportToWebhook(report: string): Promise<void>;
+  /**
+   * POST `payload` to `webhookUrl`. A string or bytes payload is sent as
+   * is; an object is form-encoded. Network errors are logged and swallowed
+   * and HTTP error statuses ignored, so a failing webhook never aborts the
+   * surrounding batch; with `throwOnError`, both are thrown instead (and
+   * not logged here).
+   */
+  sendToWebhook(webhookUrl: string, payload: WebhookPayload): Promise<void>;
+  /** Close the client: abort in-flight requests and refuse new ones. */
+  close(): void;
+}
+/** The Maildir directory does not exist and `maildirCreate` was not set. */
+export declare class NoSuchMailboxError extends Error {
+  override name: string;
+}
+/** A folder can't be removed because it still holds messages or subfolders. */
+export declare class NotEmptyError extends Error {
+  override name: string;
+}
+/** A move would overwrite a message with the same key (`mailbox.ExternalClashError`). */
+export declare class ExternalClashError extends Error {
+  override name: string;
+}
+/**
+ * Running as root, the process could not fully drop to the Maildir's owner
+ * (uid, gid and supplementary groups). mailsuite only warns and stays root.
+ */
+export declare class PrivilegeDropError extends Error {
+  override name: string;
+}
+/** No message has the given key (Python's `KeyError`). */
+export declare class MaildirKeyError extends Error {
+  override name: string;
+}
+interface MaildirConnectionOptions {
+  /** Create the Maildir (`cur`, `new`, `tmp`) if it doesn't exist. Default: false. */
+  maildirCreate?: boolean;
+}
+/**
+ * A `MailboxConnection` backed by an on-disk Maildir.
+ *
+ * Useful for local processing of messages dropped into a Maildir by an MTA
+ * (e.g. postfix delivering DMARC reports). Maildir has no concept of
+ * sending: `sendMessage()` throws `NotImplementedError`.
+ *
+ * The constructor does its filesystem checks synchronously, like
+ * mailsuite's: uid checks (warn, don't crash, but throw `PrivilegeDropError`
+ * if root can't drop to the Maildir's owner), the optional `cur`/`new`/`tmp`
+ * creation, and opening the Maildir.
+ */
+export declare class MaildirConnection extends MailboxConnection {
+  readonly kind: "maildir";
+  private readonly maildirPath;
+  private readonly maildirCreate;
+  private readonly client;
+  private activeFolder;
+  private readonly subfolderClient;
+  constructor(maildirPath: string, options?: MaildirConnectionOptions);
+  private getFolder;
+  private folderPath;
+  override createFolder(folderName: string): Promise<void>;
+  override renameFolder(oldName: string, newName: string): Promise<void>;
+  override folderExists(folderName: string): Promise<boolean>;
+  override deleteFolder(folderName: string): Promise<void>;
+  protected override doMoveFolder(source: string, _targetParent: string, targetPath: string): Promise<void>;
+  override fetchMessages(reportsFolder: string, _options?: FetchMessagesOptions): Promise<MessageId[]>;
+  /**
+   * The message's stored bytes decoded as UTF-8 (undecodable bytes
+   * replaced), like mailsuite 2.3.3 and its IMAP backend's raw fetch, or
+   * `""` for an unknown key. The file is not parsed or re-serialized, so a
+   * message Python's `email` package can parse but not generate (a `\x1c`
+   * in a nested header, deep multipart nesting) is returned as is.
+   *
+   * With `markRead` the file is renamed into `cur/` with the `S` flag (see
+   * `Maildir.markRead`). With `maxSize`, a larger file throws
+   * `EmailTooLargeError` without being read (not in mailsuite).
+   */
+  override fetchMessage(messageId: MessageId, options?: FetchMessageOptions): Promise<string>;
+  override deleteMessage(messageId: MessageId): Promise<void>;
+  /**
+   * Move the message's file into the same subdirectory (`new`/`cur`) of
+   * `folderName`, keeping its file name, flags and bytes, like mailsuite
+   * 2.3.3 (it no longer re-serializes the message). Maildir++ folders live
+   * under the same root, so this is a same-filesystem rename; a folder on
+   * another mount fails with `EXDEV`. Throws {@link ExternalClashError}
+   * rather than overwriting when the destination already holds a message
+   * with the same key (including a move into the active folder itself).
+   */
+  override moveMessage(messageId: MessageId, folderName: string): Promise<void>;
+  override keepalive(): Promise<void>;
+  override watch(options: WatchOptions): Promise<void>;
+  override sendMessage(_options: SendMessageOptions): Promise<string | null>;
+}
+/**
+ * Convert one camelCase key to snake_case (`ipAddress` → `ip_address`).
+ * Keys that aren't plain camelCase (`x-mailer`, `@lang`, `Header_From`) are
+ * data from the report and are returned unchanged.
+ */
+export declare function camelToSnake(key: string): string;
+/**
+ * Convert one snake_case key to camelCase (`ip_address` → `ipAddress`).
+ * Keys that aren't plain snake_case are returned unchanged, so the two
+ * functions are inverses for every key either produces.
+ */
+export declare function snakeToCamel(key: string): string;
+/**
+ * Deep-copy `value`, converting every object key from camelCase to
+ * snake_case, except inside values whose key is in `opaqueKeys`.
+ */
+export declare function toSnakeCaseKeys(value: unknown, opaqueKeys?: ReadonlySet<string>): unknown;
+/**
+ * Deep-copy `value`, converting every object key from snake_case to
+ * camelCase, except inside values whose key is in `opaqueKeys`. The inverse of
+ * {@link toSnakeCaseKeys}.
+ */
+export declare function toCamelCaseKeys(value: unknown, opaqueKeys?: ReadonlySet<string>): unknown;
+/**
+ * Pool initializer (parsedmarc's `_init_worker`): restore the parent's
+ * lookup context in a worker, which starts with fresh modules. The IP
+ * database path, IPinfo API token and PSL overrides (and, unlike
+ * parsedmarc, a loaded reverse DNS map) come from `shared`, so enrichment
+ * matches what the main thread configured; then the parent's logging is
+ * rebuilt, so records logged while parsing in a worker are not dropped.
+ */
+export declare function initWorker(logLevel: number, logFiles: readonly string[], shared: WorkerSharedState, reverseDnsMap: Map<string, ReverseDNSService>): void;
+/** Options passed to a job function when its task carries a config. */
+interface ParallelJobOptions {
+  config: ParserConfig;
+}
+/** What a worker runs for each job: `fn(job)` or `fn(job, { config })`. */
+interface ParallelTask {
+  /**
+   * URL or absolute path of an ES module exporting the function. Omit to
+   * use a built-in job: `parseReportEmailJob` or `parseReportFileJob`.
+   */
+  module?: string | URL | null;
+  /** Name of the exported function. */
+  name: string;
+  /** Parser config; rebuilt in the worker and passed as `{ config }`. */
+  config?: ParserConfig | null;
+}
+/** Task running `parseReportEmailJob` (report-email.ts) with `config`. */
+export declare function parseReportEmailTask(config: ParserConfig): ParallelTask;
+/** Task running `parseReportFileJob` (report-file.ts) with `config`. */
+export declare function parseReportFileTask(config: ParserConfig): ParallelTask;
+/**
+ * Module-level enrichment state the main thread may have set up before
+ * parsing in parallel (the IP database `loadIpDb()` chose, the IPinfo API
+ * token, PSL overrides loaded from a URL or file, a loaded reverse DNS
+ * map). A worker starts with fresh modules, so it gets a copy: otherwise it
+ * would use the bundled IP database, no IPinfo API, the bundled overrides
+ * and download the map again. parsedmarc's forkserver workers start fresh
+ * too and have the same gap.
+ */
+interface WorkerSharedState {
+  ipDbPath: string | null;
+  ipinfoApiToken: string | null;
+  pslOverrides: string[];
+  /** Entries of the task config's reverse DNS map, when it is loaded. */
+  reverseDnsMap: [string, ReverseDNSService][] | null;
+}
+/**
+ * Python's `concurrent.futures.process.BrokenProcessPool`: the pool can't
+ * run jobs at all (a worker failed while starting).
+ */
+export declare class BrokenProcessPool extends Error {
+  override name: string;
+}
+/**
+ * A worker thread died while running a job (over its heap limit,
+ * `process.exit()` or an uncaught error outside the job's promise). Only
+ * that job fails; the worker is replaced. parsedmarc's process pool breaks
+ * for good instead (`BrokenProcessPool`). It says nothing about the job's
+ * content: the heap also holds what the worker kept from earlier jobs.
+ */
+export declare class WorkerCrashedError extends Error {
+  override name: string;
+}
+/** A job ran longer than `jobTimeout`; its worker was stopped and replaced. */
+export declare class JobTimeoutError extends Error {
+  override name: string;
+}
+/** Options of {@link parallelMap}. */
+interface ParallelMapOptions<J = unknown, R = unknown> {
+  /** Jobs submitted ahead of the oldest unfinished one, per worker. */
+  windowFactor?: number;
+  /**
+   * Called every `heartbeatInterval` seconds spent waiting for a result. If
+   * it throws, the iteration ends with that error: the jobs did not fail,
+   * so `onJobError` doesn't see it.
+   */
+  heartbeat?: (() => unknown) | null;
+  /** Seconds between heartbeats (default 30). */
+  heartbeatInterval?: number;
+  /**
+   * Checked after each result; when it returns true, queued jobs are
+   * cancelled, running ones are awaited and yielded, and iteration ends.
+   */
+  shouldStop?: (() => boolean | Promise<boolean>) | null;
+  /**
+   * Turns a failed job into a result instead of ending the iteration: an
+   * error the job threw, a {@link WorkerCrashedError} or a
+   * {@link JobTimeoutError}. Not called for {@link BrokenProcessPool}
+   * (workers that can't start), which still ends the iteration.
+   */
+  onJobError?: ((error: unknown, job: J) => R) | null;
+  /**
+   * Seconds a job may run before its worker is stopped and the job fails
+   * with {@link JobTimeoutError}, counted once the worker has started.
+   * `null` or `0`: no limit. Default: `jobTimeout` of the task's config,
+   * else no limit.
+   */
+  jobTimeout?: number | null;
+  /**
+   * Heap limit of each worker, in MiB. A worker over it dies, which fails
+   * its job with a {@link WorkerCrashedError}. `null` or `0`: the runtime's
+   * limit. Default: `maxWorkerHeapMb` of the task's config, else no limit.
+   */
+  maxWorkerHeapMb?: number | null;
+}
+/**
+ * Map a task over `jobs` with a bounded pool of `nProcs` worker threads
+ * (parsedmarc's `parallel_map`).
+ *
+ * `jobs` is consumed lazily: at most `windowFactor * nProcs` jobs are
+ * submitted ahead of the oldest unfinished one. Results come back in
+ * submission order. No worker is started when `jobs` is empty. A job that
+ * throws, or whose worker dies ({@link WorkerCrashedError}) or runs past
+ * `jobTimeout` ({@link JobTimeoutError}), makes the iteration throw at its
+ * position, unless `onJobError` turns it into a result. A dead worker is
+ * replaced; only a worker that fails while starting breaks the pool
+ * ({@link BrokenProcessPool}). parsedmarc's process pool breaks on any
+ * dead worker.
+ *
+ * Throws {@link ValueError} right away when `nProcs` is less than 1.
+ */
+export declare function parallelMap<J, R>(task: ParallelTask, jobs: Iterable<J> | AsyncIterable<J>, nProcs: number, options?: ParallelMapOptions<J, R>): AsyncGenerator<R>;
+/**
+ * parsedmarc's `text_report_regex`: `Name: value` fields of a legacy
+ * plain-text failure notice. Anchored at line starts (`(?<![^\n])` is
+ * Python's `^` under `re.MULTILINE`, which, unlike JS's `m` flag, does not
+ * treat `\r` as a line break); the classes are disjoint so it runs in linear
+ * time (GHSA-7grx-mj6g-qxmc).
+ */
+export declare const TEXT_REPORT_REGEX: RegExp;
+/**
+ * Throw {@link EmailTooLargeError} when an email is over the config's
+ * `maxEmailSize` bytes or has more than `maxMimeParts` MIME boundary
+ * lines. Both checks are linear and run before any parsing; the parser then
+ * counts the parts that need no boundary line, see `messageFromString()`.
+ */
+export declare function checkEmailLimits(input: string | Uint8Array, config: Pick<ParserConfig, "maxEmailSize" | "maxMimeParts">): void;
+/** Options of {@link parseReportEmail}. */
+interface ParseReportEmailOptions extends ParserConfigInput {
+  /** Keep-alive callback for large aggregate reports (not part of `config`). */
+  keepAlive?: (() => unknown) | null;
+}
+/**
+ * Parses a DMARC or SMTP TLS report from an email (RFC 822 bytes or text).
+ *
+ * Throws {@link ParserError} when the email can't be read,
+ * {@link InvalidDMARCReport} when it holds no valid report, and
+ * {@link InvalidFailureReport} when its failure report is invalid. Throws
+ * {@link EmailTooLargeError} when the email is over the config's
+ * `maxEmailSize`, `maxMimeParts`, `maxHeaderLines` or `maxExpandedEmailSize`
+ * (not in parsedmarc). Whatever the input, only `ParserError` subclasses are
+ * thrown, apart from what `keepAlive` throws: that is rethrown as is, since
+ * it says nothing about the email (parsedmarc reports a `ParserError`).
+ */
+export declare function parseReportEmail(input: string | Uint8Array, options?: ParseReportEmailOptions): Promise<ParsedReport>;
+/**
+ * Worker job that parses one report email (parsedmarc's
+ * `parallel._parse_report_email_job`). A {@link ParserError} is returned as
+ * a value, never thrown, so one invalid message needs no special handling.
+ * `parseReportEmail` throws only `ParserError` subclasses, whatever the
+ * input, so no other error is expected from here.
+ */
+export declare function parseReportEmailJob(messageContent: string | Uint8Array, options: {
+  config: ParserConfig;
+}): Promise<ParsedReport | ParserError>;
+/**
+ * The dedup key of an aggregate report (parsedmarc's
+ * `_aggregate_report_dedup_key()`): RFC 9990 section 3.5.1 defines a
+ * Report-ID as unique only "among reports to the same domain", so the key
+ * is the reporter, the Report-ID and the policy domain, as a JSON array
+ * (no delimiter a field could contain). ASCII letters of the domain are
+ * compared without case (RFC 4343 section 3); the report is unchanged.
+ * Every writer of the seen report ID cache (mbox, mailbox, the CLI's
+ * direct files) must use it. The key outlives parsing in that cache and
+ * every part comes from the sender, so a long one is replaced by its hash
+ * (parsedmarc keeps it whole).
+ */
+export declare function aggregateReportKey(report: AggregateReport): string;
+/** Input of {@link parseReportFile}: a path, bytes, or a binary stream. */
+type ReportFileInput = string | URL | Uint8Array | ArrayBuffer | ReportStream;
+/** Options of {@link parseReportFile}. */
+interface ParseReportFileOptions extends ParserConfigInput {
+  /** Keep-alive callback for large aggregate reports (not part of `config`). */
+  keepAlive?: (() => unknown) | null;
+}
+/**
+ * Parses a DMARC aggregate report, DMARC failure report or SMTP TLS report
+ * from a file path, bytes or a binary stream (compressed or not, report
+ * email or bare report).
+ *
+ * A path is opened and closed here; a caller-supplied stream is read but
+ * left for the caller to close. When no format matches, the
+ * {@link ParserError} explains why, based on what the content looks like.
+ */
+export declare function parseReportFile(input: ReportFileInput, options?: ParseReportFileOptions): Promise<ParsedReport>;
+/**
+ * Worker job that parses one report file (parsedmarc's
+ * `parallel._parse_report_file_job`). Any error is returned with the path
+ * instead of being thrown, so the caller can log it and move on.
+ */
+export declare function parseReportFileJob(filePath: string, options: {
+  config: ParserConfig;
+}): Promise<[string, ParsedReport | Error]>;
+/** Options of {@link getDmarcReportsFromMbox}. */
+interface GetDmarcReportsFromMboxOptions extends ParserConfigInput {
+  /**
+   * Worker threads used to parse messages in parallel (not part of
+   * `config`). Reading, dedup and result assembly stay in the caller.
+   */
+  nProcs?: number;
+}
+/**
+ * Parses an mbox file containing emails with attached DMARC and SMTP TLS
+ * reports. Each message's stored bytes are parsed. A message that can't be
+ * parsed or is over `maxEmailSize` is logged as a warning and skipped.
+ * Duplicate aggregate reports are dropped using the config's seen-report
+ * cache.
+ */
+export declare function getDmarcReportsFromMbox(input: string, options?: GetDmarcReportsFromMboxOptions): Promise<ParsingResults>;
+/** Fields of `parsedSmtpTlsReportsToCsv()`, in column order. */
+export declare const SMTP_TLS_CSV_FIELDS: readonly string[];
+/** Parse one `failure-details` entry (parsedmarc's `_parse_smtp_tls_failure_details`). */
+export declare function parseSmtpTlsFailureDetails(failureDetails: unknown): SMTPTLSFailureDetails;
+/** Parse one policy entry (parsedmarc's `_parse_smtp_tls_report_policy`). */
+export declare function parseSmtpTlsReportPolicy(policy: unknown): SMTPTLSPolicy;
+/** Parse and validate an SMTP TLS report (RFC 8460 JSON). */
+export declare function parseSmtpTlsReportJson(report: string | Uint8Array, options?: Partial<Pick<ParserOptions, "maxSmtpTlsReportSize">>): SMTPTLSReport;
+/**
+ * Flatten SMTP TLS reports into CSV rows (snake_case keys): one row per
+ * policy, plus one per failure-details entry.
+ */
+export declare function parsedSmtpTlsReportsToCsvRows(reports: SMTPTLSReport | SMTPTLSReport[]): CsvRow[];
+/** SMTP TLS reports as flat CSV, with headers. */
+export declare function parsedSmtpTlsReportsToCsv(reports: SMTPTLSReport | SMTPTLSReport[], options?: CsvOptions): string;
+interface CreateEmailOptions {
+  messageFrom: string;
+  messageTo?: string[] | null;
+  messageCc?: string[] | null;
+  subject?: string | null;
+  messageHeaders?: Record<string, string> | null;
+  /** `[filename, content]` pairs. */
+  attachments?: [string, Uint8Array][] | null;
+  plainMessage?: string | null;
+  htmlMessage?: string | null;
+}
+/** `email.utils.formatdate(localtime=True)`: RFC 2822 date in local time. */
+export declare function formatDate(date?: Date): string;
+/**
+ * Create an RFC 822 email message and return it as a string.
+ *
+ * Port of `mailsuite.utils.create_email`: a `multipart/mixed` message with
+ * the plain and/or HTML body followed by one `application/octet-stream`
+ * part per attachment.
+ */
+export declare function createEmail(options: CreateEmailOptions): string;
+/** Python's `repr(float)`: shortest round-trip digits, `1.0`, `1e-05`, `inf`. */
+export declare function pyFloatRepr(value: number): string;
+/**
+ * Python's `repr()` for JSON-like values (strings use single quotes).
+ * Written in one pass with an explicit stack: linear in the output, and data
+ * nested deeper than the call stack allows still prints.
+ */
+export declare function pyRepr(value: unknown): string;
+/** Python's `str()` for JSON-like values. */
+export declare function pyStr(value: unknown): string;
+/**
+ * Masks the credentials in a URL or host string so it is safe to log
+ * (parsedmarc's `redact_url_credentials()`): the password, after the first
+ * `:` of the userinfo, becomes `***` (`https://user:***@host:9200`), and a
+ * userinfo without `:` (a bare token) is replaced whole
+ * (`https://***@host`). When the last `@` is past the end of the authority
+ * (a `/`, `?` or `#` in the password, or an `@` in the path or query),
+ * everything from the start of the authority through that `@` is masked
+ * (`https://admin:p4ss/w0rd@host:3100` becomes `https://***@host:3100`;
+ * `https://host/path@file` becomes `https://***@file`).
+ *
+ * One URL per string: split a comma-separated list first, or pass an
+ * array, which is masked element by element into a new array (non-string
+ * items are kept). Never throws.
+ */
+export declare function redactUrlCredentials(value: string): string;
+export declare function redactUrlCredentials<T>(value: readonly T[]): T[];
+/**
+ * Masks the credentials of the configured nameserver URLs in free text
+ * such as an error message (parsedmarc's `_mask_nameserver_secrets()`):
+ * each entry is replaced by its masked form, and each of its
+ * {@link urlSecrets} by `***` wherever it still appears. A short secret
+ * masks every occurrence of that text. Never throws.
+ */
+export declare function maskNameserverSecrets(text: string, nameservers: readonly string[] | null | undefined): string;
+/**
+ * Escapes the non-printable characters of a sender-controlled string so it
+ * is safe to put in a log line or an error message.
+ *
+ * Every character for which Python's `str.isprintable()` is false (CR, LF,
+ * tab, ESC, U+2028, NUL, and so on) is replaced by its `unicode_escape`
+ * form, e.g. `\r\n`. A sender can plant such characters in a header through
+ * an RFC 2047 encoded-word (`=?utf-8?q?a=0D=0Ab?=` decodes to a raw CR LF),
+ * and an unescaped CR/LF would let it forge extra log lines. The ASCII
+ * space, letters in any script, and most emoji pass through unchanged;
+ * non-ASCII spaces (NBSP, U+3000) and format characters such as the
+ * zero-width joiner or the bidi marks are escaped.
+ */
+export declare function sanitizeForLog(value: string): string;
+/** Cache of `queryDns()` answers, keyed `<domain>_<TYPE>`. */
+type DnsCache = ExpiringDict<string, string[]>;
+/** Cloudflare's public resolvers, used when no nameservers are configured. */
+export declare const DEFAULT_NAMESERVERS: readonly string[];
+/**
+ * A malformed nameserver entry: Python's `ValueError`, raised by
+ * parsedmarc's nameserver parsing and dnspython's `Resolver.nameservers`.
+ * `name` is `ValueError` so messages that print the error type (the CLI's
+ * DNS pre-flight check) match parsedmarc's; it is a `RangeError` for
+ * callers that catch the built-in type.
+ */
+export declare class InvalidNameserverError extends RangeError {
+  override name: string;
+}
+/**
+ * A socket-level failure (Python's `OSError`): connection refused, network
+ * unreachable, TLS handshake failure. dnspython takes the nameserver out of
+ * the mix, and parsedmarc retries the whole query on it.
+ */
+export declare class DNSSocketError extends Error {
+  override name: string;
+  /** The Node error code (`ECONNREFUSED`, ...), when known. */
+  readonly code: string | null;
+  constructor(message: string, code?: string | null);
+}
+interface DnsQueryOptions {
+  /** Cache storage. */
+  cache?: DnsCache | null;
+  /**
+   * Nameservers to use (Cloudflare's public resolvers by default). Each
+   * entry is an IP address (DNS over UDP/TCP port 53), an `https://` URL
+   * (DNS over HTTPS) or `tls://ip[:port][#hostname]` (DNS over TLS, port
+   * 853 by default, `#hostname` naming the server's TLS certificate
+   * identity). Pass `RECOMMENDED_DNS_NAMESERVERS` for a cross-provider mix.
+   */
+  nameservers?: readonly string[] | null;
+  /**
+   * Overall DNS lifetime budget in seconds per configured nameserver.
+   * Per-query attempts are capped at `min(1, timeout)` so a lost UDP packet
+   * is retried within the lifetime, and a slow nameserver falls through to
+   * the next quickly.
+   */
+  timeout?: number;
+  /**
+   * Times to retry the whole query after a timeout or other transient error
+   * (`LifetimeTimeout`, `NoNameservers`, `DNSSocketError`).
+   */
+  retries?: number;
+}
+/**
+ * Queries DNS and returns the answers as text. Throws
+ * `InvalidNameserverError` (a `RangeError`) when a
+ * nameserver is malformed, with the nameservers' URL credentials masked.
+ */
+export declare function queryDns(domain: string, recordType: string, options?: DnsQueryOptions): Promise<string[]>;
+interface GetReverseDnsOptions extends DnsQueryOptions {
+  /** Called with the DNS error when there is one, before returning `null`. */
+  onError?: (error: DNSException) => void;
+}
+/**
+ * Resolves an IP address to a hostname using a reverse DNS query. Returns
+ * `null` on any DNS error.
+ */
+export declare function getReverseDns(ipAddress: string, options?: GetReverseDnsOptions): Promise<string | null>;
+/**
+ * Reverse-map domain name of an IP address, with the final dot
+ * (`str(dns.reversename.from_address(text))`). Raises `DNSSyntaxError` for
+ * text that is not an IP address.
+ */
+export declare function reverseNameFromAddress(text: string): string;
+/**
+ * The module-level PSL overrides list (parsedmarc's `psl_overrides`).
+ * `loadPslOverrides()` refills this same array in place, and
+ * `getBaseDomain()` reads it on every call.
+ */
+export declare const pslOverrides: string[];
+interface LoadPslOverridesOptions {
+  /** Always use a local overrides file. */
+  alwaysUseLocalFile?: boolean;
+  /** Path to a local overrides file (default: the bundled `psl_overrides.txt`). */
+  localFilePath?: string | null;
+  /** URL to a PSL overrides file. */
+  url?: string | null;
+  /** Do not make online requests. */
+  offline?: boolean;
+}
+/**
+ * Loads the PSL overrides list from a URL or local file.
+ *
+ * Repopulates the module-level `pslOverrides` array in place, then returns
+ * it. The URL is tried first; on failure (or when `offline` /
+ * `alwaysUseLocalFile` is set) the local path is used, defaulting to the
+ * bundled `psl_overrides.txt`.
+ *
+ * parsedmarc clears the list before downloading; here the new list is built
+ * aside and swapped in at once, so lookups running during the download keep
+ * seeing the previous overrides instead of an empty list.
+ */
+export declare function loadPslOverrides(options?: LoadPslOverridesOptions): Promise<string[]>;
+/**
+ * Gets the base domain name for the given domain.
+ *
+ * Results are based on the Public Suffix List and the overrides in
+ * `psl_overrides.txt`. Returns `null` if a base domain cannot be determined.
+ */
+export declare function getBaseDomain(domain: string): string | null;
+/** Python's `ValueError`. */
+declare class PyValueError extends Error {
+  override name: string;
+}
+/**
+ * Decodes a base64 string, with padding being optional.
+ *
+ * Throws `UnicodeEncodeError` for non-ASCII input and `binascii.Error`
+ * (`BinasciiError`) for undecodable data, like Python.
+ */
+export declare function decodeBase64(data: string): Uint8Array;
+/**
+ * Builds an address dict from a `(display_name, address)` pair, as
+ * mail-parser returns them.
+ */
+export declare function parseEmailAddress(originalAddress: readonly [string, string] | readonly string[]): EmailAddress;
+/**
+ * Converts a string to a string that is safe to use as a filename.
+ *
+ * The result is a single path component: no `/`, `\`, `:`, NUL, other
+ * control characters or bidi marks, never ending in `.` or a space, never
+ * `.` or `..`, and at most 100 characters and 100 UTF-8 bytes (cut on a
+ * character boundary; lone surrogates are dropped), like parsedmarc. It can
+ * be empty, so callers that need a name must supply a fallback. `null` is
+ * treated as the literal string `"None"`.
+ *
+ * parsedmarc removes only `\ / : " * ? |`, CR, LF and NUL; the other control
+ * characters and the bidi marks are a tsdmarc addition.
+ */
+export declare function getFilenameSafeString(value: string | null): string;
+/**
+ * Checks if the file at the given path is an mbox mailbox file (it holds at
+ * least one message). Errors are logged at debug level and give `false`.
+ */
+export declare function isMbox(path: string): Promise<boolean>;
+/** Checks if the given content is an Outlook msg OLE/MSG file. */
+export declare function isOutlookMsg(content: unknown): boolean;
+/** How long `msgconvert` may run before it is killed (milliseconds). */
+export declare const MSGCONVERT_TIMEOUT_MS = 6e4;
+/** Python's `subprocess.CalledProcessError`. */
+export declare class CalledProcessError extends Error {
+  override name: string;
+}
+/**
+ * Uses the `msgconvert` Perl utility to convert an Outlook MSG file to
+ * standard RFC 822 format.
+ *
+ * Throws {@link ValueError} when the bytes are not an Outlook MSG file and
+ * {@link EmailParserError} when `msgconvert` is not installed (or, unlike
+ * parsedmarc, runs longer than {@link MSGCONVERT_TIMEOUT_MS}). Throws
+ * `EmailTooLargeError` when `maxSize` is not 0 and the converted message is
+ * larger, before reading it: a small MSG can expand a lot.
+ */
+export declare function convertOutlookMsg(msgBytes: Uint8Array, maxSize?: number): Promise<Uint8Array>;
+/** Options of {@link parseEmail}. */
+interface ParseEmailOptions {
+  /** Remove attachment payloads. */
+  stripAttachmentPayloads?: boolean;
+  /** Limits on the message's structure (not in parsedmarc). */
+  limits?: EmailLimits;
+}
+/**
+ * A simplified email parser.
+ *
+ * `data` is the RFC 822 message text, or its bytes (Outlook MSG bytes are
+ * converted with `msgconvert` first; other bytes are decoded as UTF-8 with
+ * replacement). `toSnakeCaseKeys()` of the result is parsedmarc's
+ * `parse_email()` output.
+ */
+export declare function parseEmail(data: Uint8Array | string, options?: ParseEmailOptions): Promise<ParsedEmail>;
+/**
+ * The synchronous part of {@link parseEmail}, for already-decoded text (no
+ * Outlook MSG conversion).
+ */
+export declare function parseEmailText(text: string, options?: ParseEmailOptions): ParsedEmail;
+/** Raised when a date string cannot be parsed (dateutil's `ParserError`). */
+export declare class DateParseError extends Error {
+  override name: string;
+}
+interface ParseDateOptions {
+  /**
+   * Naive datetime supplying the fields the string leaves out (dateutil's
+   * `default`). Defaults to today at midnight, local time.
+   */
+  default?: PyDateTime;
+  /**
+   * Year that two-digit years are resolved around (dateutil uses the local
+   * year when it is imported). Defaults to the current local year.
+   */
+  currentYear?: number;
+}
+/**
+ * Parse a date/time string like `dateutil.parser.parse(timestr)`. Missing
+ * fields come from `options.default` (today at midnight); a numeric offset
+ * or UTC zone name makes the result aware, an unknown zone name is ignored.
+ */
+export declare function parseDate(input: string, options?: ParseDateOptions): PyDateTime;
+/** Python's `datetime.fromtimestamp(int(timestamp))`: naive, local time. */
+export declare function timestampToDatetime(timestamp: number | string): PyDateTime;
+/** A UNIX timestamp as local `YYYY-MM-DD HH:MM:SS`. */
+export declare function timestampToHuman(timestamp: number | string): string;
+/**
+ * Remove RFC 5322 comments from a header value. Comments nest and may hold
+ * quoted-pairs such as `\)`, so this counts depth instead of using a regex;
+ * an unclosed comment runs to the end of the value.
+ */
+export declare function stripComments(value: string): string;
+interface HumanTimestampOptions {
+  /** Convert the result to UTC. */
+  toUtc?: boolean;
+  /** Treat a timestamp without a UTC offset as UTC instead of local time. */
+  assumeUtc?: boolean;
+}
+/** Parse a human-readable timestamp (Python's `human_timestamp_to_datetime`). */
+export declare function humanTimestampToDatetime(humanTimestamp: string, options?: HumanTimestampOptions): PyDateTime;
+/** Parse a human-readable timestamp into a UNIX timestamp (whole seconds). */
+export declare function humanTimestampToUnixTimestamp(humanTimestamp: string, options?: Pick<HumanTimestampOptions, "assumeUtc">): number;
+/**
+ * Python's `xml.parsers.expat.ExpatError`: the message is Expat's error
+ * string followed by `: line N, column M` (line 1-based, column 0-based and
+ * counted in characters), exactly as pyexpat formats it.
+ */
+export declare class ExpatError extends Error {
+  override name: string;
+  /** Expat's numeric error code (`enum XML_Error`). */
+  readonly code: number;
+  /** 1-based line of the error. */
+  readonly lineno: number;
+  /** 0-based column of the error, in characters. */
+  readonly offset: number;
+  constructor(code: number, lineno: number, offset: number);
+}
+export { type AggregateAlignment, type AggregateAuthResultDKIM, type AggregateAuthResultSPF, type AggregateAuthResults, type AggregateIdentifiers, type AggregateParsedReport, type AggregatePolicyEvaluated, type AggregatePolicyOverrideReason, type AggregatePolicyPublished, type AggregateRecord, type AggregateReport, type AggregateReportMetadata, type CreateEmailOptions, type CsvOptions, type CsvRow, type DayBucket, type DnsCache, type DnsQueryOptions, type EmailAddress, type EmailAttachment, type EmailReceivedHop, type ExpiringDictOptions, type ExtractOptions, type FailureParsedReport, type FailureReport, type FetchMessageOptions, type FetchMessagesOptions, type ForensicParsedReport, type ForensicReport, type GelfClientOptions, type GelfHandlerOptions, type GelfMode, type GelfTlsOptions, type GelfUdpHandlerOptions, type GetDmarcReportsFromMailboxOptions, type GetDmarcReportsFromMboxOptions, type GetIpAddressInfoOptions, type GetServiceOptions, type HECClientOptions, type HumanTimestampOptions, type IPAddressCache, type IPAddressInfo, type IPDatabaseRecord, type IPSourceInfo, type IpInfoState, type LoadIpDbOptions, type LoadPslOverridesOptions, type LoadReverseDnsMapOptions, type LogCapture, type LogFilter, type LogFormatter, type LogOptions, type LogRecord, type LokiClientOptions, type LokiReportType, type LokiTimestampMode, type MailboxKind, type MaildirConnectionOptions, type MergeFoldersOptions, type MessageId, type MoveFolderOptions, type ParallelJobOptions, type ParallelMapOptions, type ParallelTask, type ParseAggregateReportFileOptions, type ParseAggregateReportOptions, type ParseEmailOptions, type ParseFailureReportOptions, type ParseReportEmailOptions, type ParseReportFileOptions, type ParsedEmail, type ParsedReport, type ParserCaches, type ParserConfig, type ParserConfigInput, type ParserOptions, type ParsingResults, type PyDateTimeFields, type PyJsonDumpsOptions, type ReportFileInput, type ReportStream, type ReportType, type ResolutionError, type ReverseDNSMap, type ReverseDNSService, type SMTPTLSFailureDetails, type SMTPTLSParsedReport, type SMTPTLSPolicy, type SMTPTLSReport, type SaveCallback, type SaveCallbackResult, type SaveOutputOptions, type SeenAggregateReportIds, type SendMessageOptions, type SysLogHandlerOptions, type SyslogClientOptions, type SyslogSocketType, PyValueError as ValueError, type WatchInboxOptions, type WatchOptions, type WebhookClientOptions, type WebhookPayload, type WritableTextStream };
+//# sourceMappingURL=index.d.ts.map