@suaveplan/dmarc - DMARC report parser — parses aggregate (RUA) and forensic (RUF) DMARC XML reports into typed structures

Summary

DMARC report parser for @suaveplan — parses aggregate (RUA) and forensic (RUF) DMARC XML reports into validated, strongly-typed structures. Accepts raw XML strings or gzip-compressed binary blobs.

Documentation tree

gzip — Provides gzip decompression and input-decoding utilities for @suaveplan/dmarc. DMARC aggregate and forensic reports a…
xml — Wraps fast-xml-parser with a fixed, strict configuration tuned for DMARC report XML. The module isolates all parser c…
errors — (no submodules)
- dmarc-error — (no submodules)
otel — (no submodules)
- dmarc-otel — (no submodules)
aggregate — Implements parseDmarcAggregate, the primary entry point for converting raw DMARC aggregate (RUA) report data into val…
forensic — Implements parseDmarcForensic, the entry point for parsing DMARC forensic (RUF) reports. Forensic reports notify doma…

- [dmarc-error](./src/errors/dmarc-error.md) — _(no submodules)_- [otel](./src/otel/dmarc-otel.md) — _(no submodules)_- [dmarc-otel](./src/otel/dmarc-otel.md) — _(no submodules)_- [aggregate](./src/parsers/aggregate.md) — Implements `parseDmarcAggregate`, the primary entry point for converting raw DMARC aggregate (RUA) report data into val…

forensic — Implements parseDmarcForensic, the entry point for parsing DMARC forensic (RUF) reports. Forensic reports notify doma…
dmarc-error — (no submodules)- otel — (no submodules)- dmarc-otel — (no submodules)- aggregate — Implements parseDmarcAggregate, the primary entry point for converting raw DMARC aggregate (RUA) report data into val…
forensic — Implements parseDmarcForensic, the entry point for parsing DMARC forensic (RUF) reports. Forensic reports notify doma…
dmarc-error — (no submodules)- otel — (no submodules)- dmarc-otel — (no submodules)- aggregate — Implements parseDmarcAggregate, the primary entry point for converting raw DMARC aggregate (RUA) report data into val…
forensic — Implements parseDmarcForensic, the entry point for parsing DMARC forensic (RUF) reports. Forensic reports notify doma…
dmarc-error — (no submodules)- otel — (no submodules) - dmarc-otel — (no submodules)- aggregate — Implements parseDmarcAggregate, the primary entry point for converting raw DMARC aggregate (RUA) report data into val…
forensic — Implements parseDmarcForensic, the entry point for parsing DMARC forensic (RUF) reports. Forensic reports notify doma…

Packages

Module	Description
`src/parsers/aggregate.ts`	Parse DMARC aggregate (RUA) reports
`src/parsers/forensic.ts`	Parse DMARC forensic (RUF) reports
`src/decoders/gzip.ts`	Gzip detection and decompression
`src/decoders/xml.ts`	XML parsing via fast-xml-parser
`src/errors/dmarc-error.ts`	Typed error class and code registry
`src/otel/dmarc-otel.ts`	OpenTelemetry metrics

Quick Start

import { parseDmarcAggregate, parseDmarcForensic } from "@suaveplan/dmarc";

// Parse an aggregate report from an XML string
const aggregate = parseDmarcAggregate(xmlString);
console.log(aggregate.reportMetadata.orgName);
console.log(aggregate.record[0].row.sourceIp);

// Parse from gzip-compressed bytes (auto-detected)
const { gzipSync, strToU8 } = await import("fflate");
const compressed = gzipSync(strToU8(xmlString));
const report = parseDmarcAggregate(compressed);

// Parse a forensic report
const forensic = parseDmarcForensic(forensicXml);
console.log(forensic.feedback.policyPublished.domain);

Error Handling

import { DmarcError, DMARC_CODES } from "@suaveplan/dmarc";

try {
  parseDmarcAggregate(input);
} catch (err) {
  if (err instanceof DmarcError) {
    switch (err.code) {
      case DMARC_CODES.PARSE_ERROR:          // XML could not be parsed
      case DMARC_CODES.INVALID_REPORT:       // Schema validation failed
      case DMARC_CODES.UNSUPPORTED_ENCODING: // Gzip decompression failed
    }
  }
}

5.4 KiB Raw Blame History