aprf-reader 0.1.0__tar.gz

aprf_reader-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neil Anuskiewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aprf_reader-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: aprf-reader
+Version: 0.1.0
+Summary: Summarise APRF (Aggregate Performance Reporting) inbox placement reports.
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# aprf-reader
+
+Reads APRF (Aggregate Performance Reporting) reports and tells you where the
+mail you signed landed: how much reached the inbox, how much was treated as
+unwanted, and how recipients reacted, day by day and per DKIM selector.
+
+**Status: 0.1, beta.** Reads reports in the format of draft-ietf-mailmaint-aprf-00.
+
+## What APRF is
+
+APRF is a proposed standard for a daily report from a mailbox provider about the
+mail you signed with DKIM. It is an IETF working group draft,
+[draft-ietf-mailmaint-aprf](https://datatracker.ietf.org/doc/draft-ietf-mailmaint-aprf/),
+adopted by the Mail Maintenance (MAILMAINT) working group in October 2026. Reports
+arrive by email as small JSON files, one per day per signing domain and selector.
+Comcast sends them today in a beta for comcast.net mail.
+
+A plain-language introduction: [What APRF inbox placement reports tell you, and
+what they don't](https://dns-audit.com/articles/aprf).
+
+## Use it
+
+Python 3.11 or later, no other dependencies. Install with
+[pipx](https://pipx.pypa.io/), which keeps command line tools in their own
+environment, or with pip (`pip3` on some systems) inside a virtual environment.
+
+```bash
+pipx install aprf-reader
+aprf-reader reports/                      # Markdown summary to the terminal
+aprf-reader reports/ --html summary.html  # and a page you can open or share
+```
+
+Point it at report files (`.json`, `.json.gz`), saved report emails (`.eml`),
+or folders of them. Folders are searched recursively. Files it skips are listed
+on stderr and at the end of the summary, each with a reason.
+
+Each stream (provider, signing domain, selector) gets a table with one row per
+day and segment, a trend line per count, and a row for each day with no report.
+A change in the report's `version` field is called out, since the draft uses it
+to mark a change in what a category counts.
+
+## What it does
+
+- Read report files (`.json`, `.json.gz` and `.eml`) or a folder of them, and skip
+  duplicates and files it cannot read, with a reason for each.
+- Summarise placement per signing domain and selector: inbox, unwanted and
+  recipient reactions, by day and as a trend.
+- Treat the counts as what the draft says they are: rounded into buckets, so
+  they are a signal, not exact rates.
+- Write a Markdown summary and a single self-contained HTML page you can open
+  or share. Nothing is uploaded anywhere.
+- Follow the draft as it changes. The report format lives in one module
+  (`src/aprf_reader/report.py`), so a new draft revision is a small update.
+- When the same day arrives twice, keep the first copy and say so. The draft
+  has not yet decided whether a resend replaces the original.
+
+## Related
+
+- [dns-audit.com](https://dns-audit.com) checks a domain for an APRF record and
+  where its reports would go.
+
+## License
+
+MIT

aprf_reader-0.1.0/README.md

@@ -0,0 +1,64 @@
+# aprf-reader
+
+Reads APRF (Aggregate Performance Reporting) reports and tells you where the
+mail you signed landed: how much reached the inbox, how much was treated as
+unwanted, and how recipients reacted, day by day and per DKIM selector.
+
+**Status: 0.1, beta.** Reads reports in the format of draft-ietf-mailmaint-aprf-00.
+
+## What APRF is
+
+APRF is a proposed standard for a daily report from a mailbox provider about the
+mail you signed with DKIM. It is an IETF working group draft,
+[draft-ietf-mailmaint-aprf](https://datatracker.ietf.org/doc/draft-ietf-mailmaint-aprf/),
+adopted by the Mail Maintenance (MAILMAINT) working group in October 2026. Reports
+arrive by email as small JSON files, one per day per signing domain and selector.
+Comcast sends them today in a beta for comcast.net mail.
+
+A plain-language introduction: [What APRF inbox placement reports tell you, and
+what they don't](https://dns-audit.com/articles/aprf).
+
+## Use it
+
+Python 3.11 or later, no other dependencies. Install with
+[pipx](https://pipx.pypa.io/), which keeps command line tools in their own
+environment, or with pip (`pip3` on some systems) inside a virtual environment.
+
+```bash
+pipx install aprf-reader
+aprf-reader reports/                      # Markdown summary to the terminal
+aprf-reader reports/ --html summary.html  # and a page you can open or share
+```
+
+Point it at report files (`.json`, `.json.gz`), saved report emails (`.eml`),
+or folders of them. Folders are searched recursively. Files it skips are listed
+on stderr and at the end of the summary, each with a reason.
+
+Each stream (provider, signing domain, selector) gets a table with one row per
+day and segment, a trend line per count, and a row for each day with no report.
+A change in the report's `version` field is called out, since the draft uses it
+to mark a change in what a category counts.
+
+## What it does
+
+- Read report files (`.json`, `.json.gz` and `.eml`) or a folder of them, and skip
+  duplicates and files it cannot read, with a reason for each.
+- Summarise placement per signing domain and selector: inbox, unwanted and
+  recipient reactions, by day and as a trend.
+- Treat the counts as what the draft says they are: rounded into buckets, so
+  they are a signal, not exact rates.
+- Write a Markdown summary and a single self-contained HTML page you can open
+  or share. Nothing is uploaded anywhere.
+- Follow the draft as it changes. The report format lives in one module
+  (`src/aprf_reader/report.py`), so a new draft revision is a small update.
+- When the same day arrives twice, keep the first copy and say so. The draft
+  has not yet decided whether a resend replaces the original.
+
+## Related
+
+- [dns-audit.com](https://dns-audit.com) checks a domain for an APRF record and
+  where its reports would go.
+
+## License
+
+MIT

aprf_reader-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aprf-reader"
+version = "0.1.0"
+description = "Summarise APRF (Aggregate Performance Reporting) inbox placement reports."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+aprf-reader = "aprf_reader.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

aprf_reader-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aprf_reader-0.1.0/src/aprf_reader/__init__.py

@@ -0,0 +1,3 @@
+"""Read APRF aggregate performance reports."""
+
+__version__ = "0.1.0"

aprf_reader-0.1.0/src/aprf_reader/cli.py

@@ -0,0 +1,43 @@
+"""Command line entry point: aprf-reader <paths...>"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .load import load
+from .render import to_html, to_markdown
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="aprf-reader", description="Summarise APRF placement reports.")
+    p.add_argument("paths", nargs="+", type=Path, help="report files (.json, .json.gz, .eml) or folders")
+    p.add_argument("--md", type=Path, help="write the Markdown summary here instead of printing it")
+    p.add_argument("--html", type=Path, help="also write a self-contained HTML page here")
+    p.add_argument("--version", action="version", version=f"aprf-reader {__version__}")
+    args = p.parse_args(argv)
+
+    for path in args.paths:
+        if not path.exists():
+            p.error(f"no such file or folder: {path}")
+    loaded = load(args.paths)
+    for where, reason in loaded.skipped:
+        print(f"skipped {where}: {reason}", file=sys.stderr)
+    if not loaded.reports:
+        print("no APRF reports found", file=sys.stderr)
+        return 1
+
+    md = to_markdown(loaded)
+    if args.md:
+        args.md.write_text(md, encoding="utf-8")
+    else:
+        sys.stdout.write(md)
+    if args.html:
+        args.html.write_text(to_html(loaded), encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aprf_reader-0.1.0/src/aprf_reader/load.py

@@ -0,0 +1,98 @@
+"""Find report files, open them, and drop duplicates."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import io
+import zlib
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from email import policy
+from email.parser import BytesParser
+from pathlib import Path
+
+from .report import Report, ReportError, parse
+
+SUFFIXES = (".json", ".json.gz", ".eml")
+# A daily report is a few KB; this stops a stray huge file or gzip bomb
+MAX_BYTES = 10 * 1024 * 1024
+
+
+@dataclass
+class Loaded:
+    reports: list[Report] = field(default_factory=list)
+    skipped: list[tuple[str, str]] = field(default_factory=list)  # (where, reason)
+
+
+def _files(paths: Iterable[Path]) -> Iterator[Path]:
+    for p in paths:
+        if p.is_dir():
+            yield from sorted(f for f in p.rglob("*") if f.is_file() and f.name.lower().endswith(SUFFIXES))
+        else:
+            yield p
+
+
+def _gunzip(data: bytes) -> bytes:
+    with gzip.GzipFile(fileobj=io.BytesIO(data)) as g:
+        out = g.read(MAX_BYTES + 1)
+    if len(out) > MAX_BYTES:
+        raise ReportError("larger than 10 MB unpacked")
+    return out
+
+
+def _payloads(path: Path) -> Iterator[tuple[str, bytes]]:
+    """Yield (label, report JSON bytes) for each report in a file."""
+    data = path.read_bytes()
+    if len(data) > MAX_BYTES:
+        raise ReportError("larger than 10 MB")
+    name = path.name.lower()
+    if name.endswith(".eml"):
+        msg = BytesParser(policy=policy.default).parsebytes(data)
+        found = False
+        for part in msg.walk():
+            fname = (part.get_filename() or "").lower()
+            ctype = part.get_content_type()
+            if fname.endswith(".json.gz") or ctype == "application/gzip":
+                found = True
+                yield f"{path} ({fname or ctype})", _gunzip(part.get_payload(decode=True) or b"")
+            elif fname.endswith(".json") or ctype == "application/json":
+                found = True
+                yield f"{path} ({fname or ctype})", part.get_payload(decode=True) or b""
+        if not found:
+            raise ReportError("no .json or .json.gz attachment")
+    elif data[:2] == b"\x1f\x8b":
+        yield str(path), _gunzip(data)
+    else:
+        yield str(path), data
+
+
+def load(paths: Iterable[Path]) -> Loaded:
+    out = Loaded()
+    seen_bytes: set[str] = set()
+    seen_keys: dict[tuple, str] = {}
+    for path in _files(paths):
+        try:
+            payloads = list(_payloads(path))
+        except (OSError, EOFError, zlib.error, ReportError) as e:
+            out.skipped.append((str(path), str(e)))
+            continue
+        for where, data in payloads:
+            digest = hashlib.sha256(data).hexdigest()
+            if digest in seen_bytes:
+                out.skipped.append((where, "duplicate of a file already read"))
+                continue
+            seen_bytes.add(digest)
+            try:
+                reports = parse(data)
+            except ReportError as e:
+                out.skipped.append((where, str(e)))
+                continue
+            for r in reports:
+                # The draft does not yet say whether a resend replaces the first; keep the first
+                if r.key in seen_keys:
+                    out.skipped.append((where, f"same day already reported in {seen_keys[r.key]}; kept that one"))
+                    continue
+                seen_keys[r.key] = where
+                out.reports.append(r)
+    return out

aprf_reader-0.1.0/src/aprf_reader/render.py

@@ -0,0 +1,126 @@
+"""Write a stream summary as Markdown or as a self-contained HTML page."""
+
+from __future__ import annotations
+
+import html
+
+from . import __version__
+from .load import Loaded
+from .report import DRAFT
+from .summary import Row, Stream, streams
+
+CAVEAT = (
+    "Counts are bucket upper bounds chosen by each provider: a ceiling, not an exact figure. "
+    "Placement counts mail received that day; engagement counts actions taken that day on mail "
+    "from any day. Dividing one count by another gives a ratio nobody measured."
+)
+
+
+def _n(v: int | None) -> str:
+    return "" if v is None else f"{v:,}"
+
+
+def _md(text: str) -> str:
+    return text.replace("\\", "\\\\").replace("|", "\\|").replace("\n", " ")
+
+
+def _plural(n: int, word: str) -> str:
+    return f"{n} {word}{'' if n == 1 else 's'}"
+
+
+def _counts(loaded: Loaded, ss: list[Stream]) -> str:
+    return f"{_plural(len(loaded.reports), 'report')} in {_plural(len(ss), 'stream')}."
+
+
+def _span(s: Stream) -> str:
+    gap = f", {_plural(s.missing, 'day')} with no report" if s.missing else ""
+    return f"{s.first} to {s.last}: {_plural(len(s.by_day), 'report')}{gap}"
+
+
+def _day(row: Row) -> str:
+    return str(row.day) if row.until == row.day else f"{row.day} to {row.until}"
+
+
+def to_markdown(loaded: Loaded) -> str:
+    ss = streams(loaded.reports)
+    lines = ["# APRF placement summary", "", f"{_counts(loaded, ss)} {CAVEAT}", ""]
+    for s in ss:
+        lines += [f"## {_md(s.source)}: {_md(s.domain)}, selector {_md(s.selector)}", "", _span(s), ""]
+        cols = [k for _, k in s.columns]
+        lines.append("| Day | Segment | " + " | ".join(_md(c) for c in cols) + " |")
+        lines.append("|---|---|" + "---:|" * len(cols))
+        for row in s.rows:
+            if row.segment is None:
+                lines.append(f"| {_day(row)} | no report |" + " |" * len(cols))
+            else:
+                lines.append(f"| {row.day} | {_md(row.segment)} | " + " | ".join(_n(v) for v in row.values) + " |")
+        lines.append("")
+        if s.notes:
+            lines += [f"- {_md(n)}" for n in s.notes] + [""]
+    if loaded.skipped:
+        lines += ["## Skipped", ""] + [f"- {_md(w)}: {_md(r)}" for w, r in loaded.skipped] + [""]
+    lines.append(f"Read by aprf-reader {__version__} against {DRAFT}.")
+    return "\n".join(lines) + "\n"
+
+
+def _spark(points: list[tuple[int, int]]) -> str:
+    """Line over (day offset, value) points, broken where days are missing."""
+    if len(points) < 2:
+        return ""
+    w, h = 96, 20
+    top = max(v for _, v in points) or 1
+    step = w / points[-1][0]
+    path, prev = [], None
+    for x, v in points:
+        cmd = "L" if prev is not None and x - prev == 1 else "M"
+        path.append(f"{cmd}{x * step:.1f},{h - 1 - (v / top) * (h - 2):.1f}")
+        prev = x
+    return (f'<svg class="spark" viewBox="-1 0 {w + 2} {h}" width="{w}" height="{h}" aria-hidden="true">'
+            f'<path d="{" ".join(path)}" fill="none" stroke="currentColor" stroke-width="1.5" '
+            'stroke-linecap="round"/></svg>')
+
+
+CSS = """
+:root{--bg:#fff;--fg:#1a1a1a;--muted:#5f6368;--line:#dadce0;--gap:#f6f6f6;--accent:#1a5fb4}
+@media (prefers-color-scheme:dark){:root{--bg:#161616;--fg:#e8e8e8;--muted:#a0a0a0;--line:#3a3a3a;--gap:#202020;--accent:#78aeed}}
+body{background:var(--bg);color:var(--fg);font:15px/1.5 system-ui,sans-serif;margin:0 auto;max-width:960px;padding:24px 16px}
+h1{font-size:1.5rem}h2{font-size:1.15rem;margin-top:2rem}
+.muted{color:var(--muted)}
+.wrap{overflow-x:auto}table{border-collapse:collapse;width:100%;font-variant-numeric:tabular-nums}
+th,td{border-bottom:1px solid var(--line);padding:4px 8px;text-align:right;white-space:nowrap}
+th:nth-child(-n+2),td:nth-child(-n+2){text-align:left}
+tr.gap td{background:var(--gap);color:var(--muted)}tr.trend td{border-bottom:2px solid var(--line)}
+.spark{color:var(--accent);vertical-align:middle}
+"""
+
+
+def to_html(loaded: Loaded) -> str:
+    e = html.escape
+    ss = streams(loaded.reports)
+    parts = [
+        "<!doctype html><html lang=en><head><meta charset=utf-8>",
+        '<meta name=viewport content="width=device-width,initial-scale=1">',
+        f"<title>APRF placement summary</title><style>{CSS}</style></head><body>",
+        "<h1>APRF placement summary</h1>",
+        f"<p>{_counts(loaded, ss)}</p><p class=muted>{e(CAVEAT)}</p>",
+    ]
+    for s in ss:
+        cols = [k for _, k in s.columns]
+        parts.append(f"<h2>{e(s.source)}: {e(s.domain)}, selector {e(s.selector)}</h2>")
+        parts.append(f"<p class=muted>{e(_span(s))}</p><div class=wrap><table><thead><tr><th>Day<th>Segment")
+        parts.append("".join(f"<th>{e(c)}" for c in cols) + "</thead><tbody>")
+        parts.append("<tr class=trend><td>Trend<td class=muted>sum per day")
+        parts.append("".join(f"<td>{_spark(s.trend(i))}" for i in range(len(cols))))
+        for row in s.rows:
+            if row.segment is None:
+                parts.append(f"<tr class=gap><td>{_day(row)}<td>no report" + "<td>" * len(cols))
+            else:
+                parts.append(f"<tr><td>{row.day}<td>{e(row.segment)}" + "".join(f"<td>{_n(v)}" for v in row.values))
+        parts.append("</tbody></table></div>")
+        if s.notes:
+            parts.append("<ul>" + "".join(f"<li>{e(n)}" for n in s.notes) + "</ul>")
+    if loaded.skipped:
+        parts.append("<h2>Skipped</h2><ul>" + "".join(f"<li>{e(w)}: {e(r)}" for w, r in loaded.skipped) + "</ul>")
+    parts.append(f"<p class=muted>Read by aprf-reader {e(__version__)} against {DRAFT}. Nothing left this computer.</p>")
+    parts.append("</body></html>")
+    return "\n".join(parts) + "\n"

aprf_reader-0.1.0/src/aprf_reader/report.py

@@ -0,0 +1,141 @@
+"""The APRF report format, per draft-ietf-mailmaint-aprf-00.
+
+Everything that knows field names lives here, so a new draft revision is an
+edit to this file.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime
+
+DRAFT = "draft-ietf-mailmaint-aprf-00"
+
+# Names the draft defines, in display order; providers may add others
+PLACEMENT_NAMES = ("inbox", "unwanted")
+ENGAGEMENT_NAMES = ("positive", "neutral", "negative")
+# sdi_used values that mean no SDI was applied (section 5.2.1)
+NO_SDI = ("", "N/A", "N/F")
+
+
+class ReportError(ValueError):
+    """The data is not an APRF report this module can read."""
+
+
+@dataclass(frozen=True)
+class Segment:
+    # () when the report is flat (no SDI); otherwise up to four values, broad to narrow
+    path: tuple[str, ...]
+    # Provider-defined names (inbox, unwanted, ...) to bucket upper bounds
+    classification: dict[str, int] = field(default_factory=dict)
+    engagement: dict[str, int] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Report:
+    source: str
+    dkim_domain: str
+    dkim_selector: str
+    report_start: int
+    report_end: int
+    version: str
+    sdi_used: str
+    contact_info: str
+    extra_info: str
+    segments: tuple[Segment, ...]
+
+    @property
+    def day(self) -> date:
+        # Section 8: the report's date is its ending date, in UTC
+        return _day(self.report_end)
+
+    @property
+    def key(self) -> tuple[str, str, str, date]:
+        return (self.source, self.dkim_domain.lower(), self.dkim_selector, self.day)
+
+
+def _day(epoch: int) -> date:
+    return datetime.fromtimestamp(epoch, UTC).date()
+
+
+def _counts(value: object, where: str) -> dict[str, int]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ReportError(f"{where} is not an object")
+    out = {}
+    for name, n in value.items():
+        if isinstance(n, bool) or not isinstance(n, int) or n < 0:
+            raise ReportError(f"{where}.{name} is not a count: {n!r}")
+        out[str(name)] = n
+    return out
+
+
+def _segment(item: object, i: int) -> Segment:
+    if not isinstance(item, dict):
+        raise ReportError(f"body[{i}] is not an object")
+    seg = item.get("segment")
+    # Section 5.2.2 shows a string, the samples a list
+    if seg is None:
+        path: tuple[str, ...] = ()
+    elif isinstance(seg, str):
+        path = (seg,)
+    elif isinstance(seg, list) and all(isinstance(s, str) for s in seg):
+        path = tuple(seg)
+    else:
+        raise ReportError(f"body[{i}].segment is not a string or list of strings")
+    return Segment(
+        path,
+        _counts(item.get("classification"), f"body[{i}].classification"),
+        _counts(item.get("engagement"), f"body[{i}].engagement"),
+    )
+
+
+def _text(value: object) -> str:
+    return "" if value is None else str(value)
+
+
+def _report(obj: object) -> Report:
+    if not isinstance(obj, dict) or not isinstance(obj.get("header"), dict):
+        raise ReportError("no header object")
+    h = obj["header"]
+    for name in ("dkim_domain", "dkim_selector"):
+        if not isinstance(h.get(name), str) or not h[name]:
+            raise ReportError(f"header.{name} is missing")
+    for name in ("report_start", "report_end"):
+        if isinstance(h.get(name), bool) or not isinstance(h.get(name), int):
+            raise ReportError(f"header.{name} is not an epoch time")
+    try:
+        _day(h["report_end"])
+    except (OverflowError, OSError, ValueError):
+        raise ReportError(f"header.report_end is out of range: {h['report_end']}") from None
+    body = obj.get("body", [])
+    if not isinstance(body, list):
+        raise ReportError("body is not a list")
+    return Report(
+        source=_text(h.get("source")) or "unknown",
+        dkim_domain=h["dkim_domain"],
+        dkim_selector=h["dkim_selector"],
+        report_start=h["report_start"],
+        report_end=h["report_end"],
+        version=_text(h.get("version")),
+        sdi_used=_text(h.get("sdi_used")),
+        contact_info=_text(h.get("contact_info")),
+        extra_info=_text(h.get("extra_info")),
+        segments=tuple(_segment(s, i) for i, s in enumerate(body)),
+    )
+
+
+def parse(data: bytes) -> list[Report]:
+    """Parse one report document. The draft's samples wrap reports in a list."""
+    try:
+        doc = json.loads(data)
+    except (UnicodeDecodeError, json.JSONDecodeError) as e:
+        raise ReportError(f"not JSON: {e}") from None
+    except RecursionError:
+        raise ReportError("JSON nested too deeply") from None
+    items = doc if isinstance(doc, list) else [doc]
+    if not items:
+        raise ReportError("empty list")
+    return [_report(o) for o in items]

aprf_reader-0.1.0/src/aprf_reader/summary.py

@@ -0,0 +1,93 @@
+"""Group reports into streams: one provider, signing domain and selector over time."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import date, timedelta
+from functools import cached_property
+
+from .report import ENGAGEMENT_NAMES, NO_SDI, PLACEMENT_NAMES, Report
+
+
+@dataclass(frozen=True)
+class Row:
+    day: date
+    # For a gap, the last missing day of the run; equal to day otherwise
+    until: date
+    # None for a run of days with no report
+    segment: str | None
+    values: tuple[int | None, ...] = ()
+
+
+@dataclass
+class Stream:
+    source: str
+    domain: str
+    selector: str
+    by_day: dict[date, Report]
+
+    @cached_property
+    def first(self) -> date:
+        return min(self.by_day)
+
+    @cached_property
+    def last(self) -> date:
+        return max(self.by_day)
+
+    @cached_property
+    def missing(self) -> int:
+        return (self.last - self.first).days + 1 - len(self.by_day)
+
+    def _names(self, attr: str, order: tuple[str, ...]) -> list[str]:
+        seen = {k for r in self.by_day.values() for s in r.segments for k in getattr(s, attr)}
+        return [k for k in order if k in seen] + sorted(seen - set(order))
+
+    @cached_property
+    def columns(self) -> list[tuple[str, str]]:
+        """(attribute, name) pairs: placement counts, then engagement counts."""
+        return ([("classification", k) for k in self._names("classification", PLACEMENT_NAMES)]
+                + [("engagement", k) for k in self._names("engagement", ENGAGEMENT_NAMES)])
+
+    @cached_property
+    def rows(self) -> list[Row]:
+        """One row per segment per report day; one row per run of days with no report."""
+        out: list[Row] = []
+        prev: date | None = None
+        for d in sorted(self.by_day):
+            if prev is not None and (d - prev).days > 1:
+                out.append(Row(prev + timedelta(1), d - timedelta(1), None))
+            for s in self.by_day[d].segments:
+                vals = tuple(getattr(s, a).get(k) for a, k in self.columns)
+                out.append(Row(d, d, " / ".join(s.path) or "all mail", vals))
+            prev = d
+        return out
+
+    def trend(self, col: int) -> list[tuple[int, int]]:
+        """(day offset from first, sum across segments) for each report day."""
+        a, k = self.columns[col]
+        return [((d - self.first).days, sum(getattr(s, a).get(k, 0) for s in r.segments))
+                for d, r in sorted(self.by_day.items())]
+
+    @cached_property
+    def notes(self) -> list[str]:
+        out = []
+        prev: str | None = None
+        for d, r in sorted(self.by_day.items()):
+            if prev is not None and r.version != prev:
+                out.append(f"Report version changed from {prev} to {r.version} on {d}: "
+                           "the provider may have changed what a category counts.")
+            prev = r.version
+        # "TBD" is the draft samples' placeholder
+        out += [f"Provider note: {t}" for t in sorted({r.extra_info for r in self.by_day.values()} - {"", "TBD"})]
+        sdi = sorted({r.sdi_used for r in self.by_day.values()} - set(NO_SDI))
+        if sdi:
+            out.append("SDI used: " + ", ".join(sdi))
+        return out
+
+
+def streams(reports: list[Report]) -> list[Stream]:
+    groups: dict[tuple[str, str, str], dict[date, Report]] = defaultdict(dict)
+    for r in reports:
+        groups[(r.source, r.dkim_domain.lower(), r.dkim_selector)][r.day] = r
+    return [Stream(src, dom, sel, days) for (src, dom, sel), days in sorted(groups.items())]

aprf_reader-0.1.0/src/aprf_reader.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: aprf-reader
+Version: 0.1.0
+Summary: Summarise APRF (Aggregate Performance Reporting) inbox placement reports.
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# aprf-reader
+
+Reads APRF (Aggregate Performance Reporting) reports and tells you where the
+mail you signed landed: how much reached the inbox, how much was treated as
+unwanted, and how recipients reacted, day by day and per DKIM selector.
+
+**Status: 0.1, beta.** Reads reports in the format of draft-ietf-mailmaint-aprf-00.
+
+## What APRF is
+
+APRF is a proposed standard for a daily report from a mailbox provider about the
+mail you signed with DKIM. It is an IETF working group draft,
+[draft-ietf-mailmaint-aprf](https://datatracker.ietf.org/doc/draft-ietf-mailmaint-aprf/),
+adopted by the Mail Maintenance (MAILMAINT) working group in October 2026. Reports
+arrive by email as small JSON files, one per day per signing domain and selector.
+Comcast sends them today in a beta for comcast.net mail.
+
+A plain-language introduction: [What APRF inbox placement reports tell you, and
+what they don't](https://dns-audit.com/articles/aprf).
+
+## Use it
+
+Python 3.11 or later, no other dependencies. Install with
+[pipx](https://pipx.pypa.io/), which keeps command line tools in their own
+environment, or with pip (`pip3` on some systems) inside a virtual environment.
+
+```bash
+pipx install aprf-reader
+aprf-reader reports/                      # Markdown summary to the terminal
+aprf-reader reports/ --html summary.html  # and a page you can open or share
+```
+
+Point it at report files (`.json`, `.json.gz`), saved report emails (`.eml`),
+or folders of them. Folders are searched recursively. Files it skips are listed
+on stderr and at the end of the summary, each with a reason.
+
+Each stream (provider, signing domain, selector) gets a table with one row per
+day and segment, a trend line per count, and a row for each day with no report.
+A change in the report's `version` field is called out, since the draft uses it
+to mark a change in what a category counts.
+
+## What it does
+
+- Read report files (`.json`, `.json.gz` and `.eml`) or a folder of them, and skip
+  duplicates and files it cannot read, with a reason for each.
+- Summarise placement per signing domain and selector: inbox, unwanted and
+  recipient reactions, by day and as a trend.
+- Treat the counts as what the draft says they are: rounded into buckets, so
+  they are a signal, not exact rates.
+- Write a Markdown summary and a single self-contained HTML page you can open
+  or share. Nothing is uploaded anywhere.
+- Follow the draft as it changes. The report format lives in one module
+  (`src/aprf_reader/report.py`), so a new draft revision is a small update.
+- When the same day arrives twice, keep the first copy and say so. The draft
+  has not yet decided whether a resend replaces the original.
+
+## Related
+
+- [dns-audit.com](https://dns-audit.com) checks a domain for an APRF record and
+  where its reports would go.
+
+## License
+
+MIT

aprf_reader-0.1.0/src/aprf_reader.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/aprf_reader/__init__.py
+src/aprf_reader/cli.py
+src/aprf_reader/load.py
+src/aprf_reader/render.py
+src/aprf_reader/report.py
+src/aprf_reader/summary.py
+src/aprf_reader.egg-info/PKG-INFO
+src/aprf_reader.egg-info/SOURCES.txt
+src/aprf_reader.egg-info/dependency_links.txt
+src/aprf_reader.egg-info/entry_points.txt
+src/aprf_reader.egg-info/requires.txt
+src/aprf_reader.egg-info/top_level.txt
+tests/test_reader.py

aprf_reader-0.1.0/src/aprf_reader.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aprf_reader-0.1.0/src/aprf_reader.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aprf-reader = aprf_reader.cli:main

aprf_reader-0.1.0/src/aprf_reader.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=7

aprf_reader-0.1.0/src/aprf_reader.egg-info/top_level.txt

@@ -0,0 +1 @@
+aprf_reader

aprf_reader-0.1.0/tests/test_reader.py

@@ -0,0 +1,139 @@
+import gzip
+import json
+from datetime import date
+from email.message import EmailMessage
+from pathlib import Path
+
+import pytest
+
+from aprf_reader.cli import main
+from aprf_reader.load import load
+from aprf_reader.render import to_html, to_markdown
+from aprf_reader.summary import streams
+from aprf_reader.report import ReportError, parse
+
+FIX = Path(__file__).parent / "fixtures"
+DAY = 86400
+
+
+def report(day: int, inbox: int = 100, source: str = "Comcast", **header) -> dict:
+    start = 1790812800 + day * DAY  # 2026-10-01 00:00 UTC
+    h = {"version": "1", "source": source, "dkim_domain": "example.com", "dkim_selector": "s1",
+         "report_start": start, "report_end": start + DAY - 1, "sdi_used": "N/F", **header}
+    return {"header": h, "body": [{"classification": {"inbox": inbox, "unwanted": 10},
+                                   "engagement": {"positive": 5, "negative": 1}}]}
+
+
+def write(path: Path, obj) -> Path:
+    path.write_text(json.dumps(obj))
+    return path
+
+
+def test_draft_samples_parse():
+    (r1,) = parse((FIX / "draft_sample_1.json").read_bytes())
+    assert r1.dkim_selector == "selector1" and r1.version == "42"
+    assert [s.path for s in r1.segments] == [("Seg1", "Seg2", "Seg3"), ("Seg1", "Seg2", "Other"), ("Seg1", "Other")]
+    assert r1.segments[0].classification == {"inbox": 10000, "unwanted": 500}
+    assert r1.day == date(2024, 2, 29)
+    (r2,) = parse((FIX / "draft_sample_2.json").read_bytes())
+    assert r2.segments[0].path == () and r2.sdi_used == "N/F"
+
+
+def test_bare_object_and_string_segment():
+    obj = report(0)
+    obj["body"][0]["segment"] = "CustomerA"
+    (r,) = parse(json.dumps(obj).encode())
+    assert r.segments[0].path == ("CustomerA",)
+
+
+@pytest.mark.parametrize("mutate, reason", [
+    (lambda o: o.pop("header"), "no header"),
+    (lambda o: o["header"].pop("dkim_domain"), "dkim_domain"),
+    (lambda o: o["header"].update(report_end="yesterday"), "report_end"),
+    (lambda o: o["body"][0]["classification"].update(inbox=-1), "not a count"),
+    (lambda o: o["body"][0]["engagement"].update(positive=True), "not a count"),
+])
+def test_bad_reports_rejected(mutate, reason):
+    obj = report(0)
+    mutate(obj)
+    with pytest.raises(ReportError, match=reason):
+        parse(json.dumps(obj).encode())
+
+
+def test_load_gz_eml_folder_and_skips(tmp_path):
+    write(tmp_path / "a.json", report(0))
+    (tmp_path / "b.json.gz").write_bytes(gzip.compress(json.dumps(report(1)).encode()))
+    msg = EmailMessage()
+    msg["Subject"] = "APRF: 20261003_example.com_s1_Comcast"
+    msg.set_content("report attached")
+    msg.add_attachment(gzip.compress(json.dumps(report(2)).encode()), maintype="application",
+                       subtype="gzip", filename="20261003_example.com_s1_Comcast.json.gz")
+    (tmp_path / "c.eml").write_bytes(msg.as_bytes())
+    write(tmp_path / "copy.json", report(0))  # same bytes as a.json
+    write(tmp_path / "resend.json", report(0, inbox=999))  # same day, different counts
+    (tmp_path / "broken.json").write_text("{not json")
+    (tmp_path / "notes.txt").write_text("ignored: not a report suffix")
+
+    loaded = load([tmp_path])
+    assert sorted(r.day.day for r in loaded.reports) == [1, 2, 3]
+    reasons = dict((Path(w.split(" ")[0]).name, r) for w, r in loaded.skipped)
+    assert set(reasons) == {"copy.json", "resend.json", "broken.json"}
+    assert "duplicate" in reasons["copy.json"] and "same day" in reasons["resend.json"]
+
+
+def test_hostile_files_skipped_not_crashed(tmp_path):
+    (tmp_path / "deep.json").write_text("[" * 100_000 + "]" * 100_000)
+    write(tmp_path / "far.json", report(0, report_end=10**20))
+    good = gzip.compress(json.dumps(report(0)).encode())
+    (tmp_path / "bad-deflate.json.gz").write_bytes(good[:10] + b"\x07" * (len(good) - 10))
+    (tmp_path / "truncated.json.gz").write_bytes(good[:-12])
+    loaded = load([tmp_path])
+    assert not loaded.reports and len(loaded.skipped) == 4
+    reasons = " ".join(r for _, r in loaded.skipped)
+    assert "nested too deeply" in reasons and "out of range" in reasons
+
+
+def test_gzip_bomb_skipped(tmp_path):
+    (tmp_path / "big.json.gz").write_bytes(gzip.compress(b" " * (11 * 1024 * 1024)))
+    loaded = load([tmp_path])
+    assert not loaded.reports and "10 MB" in loaded.skipped[0][1]
+
+
+def test_stream_gaps_versions_and_columns(tmp_path):
+    write(tmp_path / "1.json", report(0))
+    write(tmp_path / "2.json", report(3, version="2", extra_info="positive now includes replies"))
+    write(tmp_path / "3.json", report(1, source="Other MBP"))
+    ss = streams(load([tmp_path]).reports)
+    assert [s.source for s in ss] == ["Comcast", "Other MBP"]
+    s = ss[0]
+    assert s.missing == 2
+    assert [k for _, k in s.columns] == ["inbox", "unwanted", "positive", "negative"]
+    gaps = [(r.day, r.until) for r in s.rows if r.segment is None]
+    assert gaps == [(date(2026, 10, 2), date(2026, 10, 3))]  # one row per run, not per day
+    assert [x for x, _ in s.trend(0)] == [0, 3]
+    notes = " ".join(s.notes)
+    assert "SDI" not in notes  # N/F means none
+    assert "changed from 1 to 2 on 2026-10-04" in notes and "replies" in notes
+
+
+def test_outputs_escape_report_text(tmp_path):
+    hostile = "<script>alert(1)</script>|x"
+    obj = report(0, source=hostile)
+    obj["body"][0]["segment"] = [hostile]
+    write(tmp_path / "r.json", obj)
+    loaded = load([tmp_path])
+    page = to_html(loaded)
+    assert "<script>" not in page and "&lt;script&gt;" in page
+    md = to_markdown(loaded)
+    assert "</script>\\|x" in md and "</script>|x" not in md
+
+
+def test_cli(tmp_path, capsys):
+    out = tmp_path / "out.html"
+    assert main([str(FIX), "--html", str(out)]) == 0
+    stdout = capsys.readouterr().out
+    assert "Receiver MBP, Inc.: example.com, selector selector1" in stdout
+    assert "| 2024-02-29 | Seg1 / Seg2 / Seg3 | 10,000 | 500 | 300 | 50 | 200 |" in stdout
+    assert out.read_text().startswith("<!doctype html>")
+    (tmp_path / "empty").mkdir()
+    assert main([str(tmp_path / "empty")]) == 1