skills/plugins/document-navigator/docs/communication/emails/dmarc/README.md

@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
    }
  }
}