runningtab 0.1.0.dev3__py3-none-any.whl

runningtab/period/crosscheck.py

@@ -0,0 +1,257 @@
+"""Check our package's figures against ERPNext's own Trial Balance and AR/AP Summary reports.
+
+Plan 1's `trial_balance`/`open_items` recompute a quarter's figures from the raw
+GL Entries -- our own arithmetic, however carefully checked, never balancing
+against ERPNext's own reports is a silent way for the close to hand out wrong
+books. This module reads the three reports a person would otherwise open by
+hand (Trial Balance, Accounts Receivable Summary, Accounts Payable Summary)
+through `frappe.desk.query_report.run`, and compares them line by line against
+`TrialBalance`/`OpenItem`: any disagreement is named, never averaged away or
+silently accepted.
+
+The comparison is account-by-account and party-by-party, not total-by-total: a
+compensating pair of errors that leaves the grand total unchanged would pass a
+total-only check and still be wrong books.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from collections import defaultdict
+from collections.abc import Callable, Sequence
+from decimal import Decimal
+from typing import Any, Literal, Protocol
+
+from runningtab.period.balances import TrialBalance
+from runningtab.period.csvfmt import money
+from runningtab.period.ledger import AccountIndex
+from runningtab.period.open_items import Kind, OpenItem
+from runningtab.period.package import Package
+from runningtab.period.quarter import FiscalYear, Quarter
+
+TRIAL_BALANCE_REPORT = "Trial Balance"
+# The Trial Balance report's own grand-total row names itself this, quoted by
+# ERPNext itself -- see the committed tests/fixtures/period/trial-balance-report.json.
+_TRIAL_BALANCE_TOTAL_ACCOUNT = "'Total'"
+_PARTY_SUMMARY_REPORT: dict[Kind, str] = {
+    "Receivable": "Accounts Receivable Summary",
+    "Payable": "Accounts Payable Summary",
+}
+_ZERO = Decimal(0)
+
+
+class _Caller(Protocol):
+    def call(self, dotted_path: str, params: dict[str, Any] | None = None) -> Any: ...
+
+
+def read_trial_balance_report(
+    client: _Caller, company: str, fiscal_year: FiscalYear, quarter: Quarter
+) -> list[dict[str, Any]]:
+    """ERPNext's own Trial Balance report for `quarter`, one row per account (postable or group) with activity, plus the report's own grand-total row.
+
+    Net presentation (`show_net_values: 1`) so each row's debit/credit columns
+    match `AccountBalance`'s sign convention directly, and every closing
+    figure Period Closing Vouchers would otherwise fold in is left out
+    (`with_period_closing_entry_for_*: 0`) since plan 1 does not handle those
+    either (`runningtab.period.balances._refuse_out_of_scope`).
+
+    Only a row that is not even a dict, or a dict with no `account` at all, is
+    dropped here. The report's own grand-total row -- `{"account": "'Total'",
+    "account_name": "'Total'", ...}`, quoted by ERPNext itself; see the
+    committed `tests/fixtures/period/trial-balance-report.json`, whose last
+    row is exactly this -- is a dict with an `account` like any other row, so
+    it passes through unfiltered. `trial_balance_mismatches` is what
+    recognizes and skips it, by the one thing that actually sets it apart: it
+    carries no `is_group_account` key, which every real account row does.
+    """
+    result = client.call(
+        "frappe.desk.query_report.run",
+        {
+            "report_name": TRIAL_BALANCE_REPORT,
+            "filters": {
+                "company": company,
+                "fiscal_year": fiscal_year.name,
+                "from_date": quarter.start.isoformat(),
+                "to_date": quarter.end.isoformat(),
+                "show_net_values": 1,
+                "show_unclosed_fy_pl_balances": 0,
+                "with_period_closing_entry_for_opening": 0,
+                "with_period_closing_entry_for_current_period": 0,
+                "include_default_book_entries": 1,
+            },
+        },
+    )
+    return [row for row in result["result"] if isinstance(row, dict) and row.get("account")]
+
+
+def read_party_summary(
+    client: _Caller, company: str, as_of: dt.date, kind: Literal["Receivable", "Payable"]
+) -> list[dict[str, Any]]:
+    """ERPNext's own Accounts Receivable/Payable Summary report as of `as_of`, one row per party with an outstanding balance.
+
+    Like the Trial Balance report, the grand-total row is a bare list, not a
+    dict, and is dropped along with anything else missing a `party`.
+    """
+    result = client.call(
+        "frappe.desk.query_report.run",
+        {
+            "report_name": _PARTY_SUMMARY_REPORT[kind],
+            "filters": {
+                "company": company,
+                "report_date": as_of.isoformat(),
+                "ageing_based_on": "Due Date",
+                "range": "30, 60, 90, 120",
+            },
+        },
+    )
+    return [row for row in result["result"] if isinstance(row, dict) and row.get("party")]
+
+
+def _decimal(row: dict[str, Any], field: str) -> Decimal:
+    return Decimal(str(row.get(field) or 0))
+
+
+def _trial_balance_figures(row: dict[str, Any]) -> tuple[Decimal, Decimal, Decimal, Decimal]:
+    return (
+        _decimal(row, "opening_debit") - _decimal(row, "opening_credit"),
+        _decimal(row, "debit"),
+        _decimal(row, "credit"),
+        _decimal(row, "closing_debit") - _decimal(row, "closing_credit"),
+    )
+
+
+def trial_balance_mismatches(ours: TrialBalance, theirs: list[dict[str, Any]], index: AccountIndex) -> list[str]:
+    """Every postable account whose opening, period debit, period credit, or closing figure disagrees with `theirs`.
+
+    `theirs` rows are matched to `ours.lines` by account document name through
+    `index`, the same key `GLRow.account` uses, rather than by parsing the
+    report's human-readable account string. Four kinds of row in `theirs` are
+    not a postable account to compare against `ours.lines`, and each is
+    handled differently:
+
+    - The report's own grand-total row carries no `is_group_account` key at
+      all (see `read_trial_balance_report`'s docstring) *and* names itself
+      `account == "'Total'"` -- skipped outright, never reported. Both
+      conditions are checked, not just the missing key: the key's absence
+      alone is a structural accident of this one row on this ERPNext
+      version, not a guarantee, and treating it alone as "this is the total
+      row" would silently drop a real account row that happened to lack the
+      key for some other reason.
+    - Any other row missing `is_group_account` -- a shape this module does
+      not recognize, not the report's own total row -- is reported by name
+      rather than silently dropped: `"<account>: unrecognised row shape in
+      ERPNext's trial balance (no is_group_account)"`.
+    - A group account's row (`is_group_account` truthy) is a subtotal
+      `ours.lines` does not carry one of -- skipped outright, never reported.
+    - A row whose `account` is simply not in `index` is chart drift: ERPNext
+      has an account this run's `chart.coa` does not describe. An all-zero
+      row is skipped (there is nothing in it to disagree with, and the
+      export's own live-chart check already refuses chart drift elsewhere);
+      a row with any nonzero figure is reported by name, since it is real
+      money `ours` has nowhere to put and would otherwise vanish silently.
+
+    A postable account that `theirs` has no row for at all (no activity all
+    quarter, in ERPNext's own report) is treated as all-zero, not as a
+    missing-row mismatch: `ours.lines` always carries every postable account,
+    active or not, and a truly inactive one is expected to be absent from
+    ERPNext's report. `ours.prior_year_unclosed` has no line in ERPNext's own
+    report to compare against and is not checked here.
+    """
+    by_number: dict[str, dict[str, Any]] = {}
+    mismatches: list[str] = []
+    for row in theirs:
+        if "is_group_account" not in row:
+            if row.get("account") == _TRIAL_BALANCE_TOTAL_ACCOUNT:
+                continue
+            mismatches.append(
+                f"{row.get('account')}: unrecognised row shape in ERPNext's trial balance (no is_group_account)"
+            )
+            continue
+        if row["is_group_account"]:
+            continue
+        account_name = row.get("account")
+        account = index.get(account_name) if account_name else None
+        if account is None:
+            opening, debit, credit, closing = _trial_balance_figures(row)
+            if any((opening, debit, credit, closing)):
+                mismatches.append(
+                    f"{account_name}: in ERPNext's trial balance but not in chart.coa "
+                    f"(opening {money(opening)}, period debit {money(debit)}, period credit {money(credit)}, "
+                    f"closing {money(closing)})"
+                )
+            continue
+        by_number[account.number] = row
+
+    for line in ours.lines:
+        row = by_number.get(line.account.number)
+        label = f"{line.account.number} {line.account.name}"
+        their_opening, their_debit, their_credit, their_closing = (
+            _trial_balance_figures(row) if row else (_ZERO, _ZERO, _ZERO, _ZERO)
+        )
+        for our_value, their_value, figure in (
+            (line.opening, their_opening, "opening"),
+            (line.period_debit, their_debit, "period debit"),
+            (line.period_credit, their_credit, "period credit"),
+            (line.closing, their_closing, "closing"),
+        ):
+            if our_value != their_value:
+                mismatches.append(f"{label} {figure}: ours {money(our_value)}, ERPNext {money(their_value)}")
+    return mismatches
+
+
+def open_item_mismatches(ours: Sequence[OpenItem], theirs: list[dict[str, Any]], kind: Kind) -> list[str]:
+    """Every party whose total open amount disagrees with ERPNext's own AR/AP Summary `outstanding`.
+
+    Summed per party on our side (`OpenItem` is one row per document, the
+    report is one row per party) so the two are compared at the same grain.
+    ERPNext's `outstanding` is positive for money owed to us (Receivable) or
+    by us (Payable) -- the same sign `runningtab.period.open_items.open_items`
+    already gives `OpenItem.amount` -- so no sign flip is needed for either
+    kind.
+    """
+    ours_by_party: dict[str, Decimal] = defaultdict(Decimal)
+    for item in ours:
+        ours_by_party[item.party] += item.amount
+    theirs_by_party: dict[str, Decimal] = defaultdict(Decimal)
+    for row in theirs:
+        theirs_by_party[str(row["party"])] += _decimal(row, "outstanding")
+
+    mismatches: list[str] = []
+    for party in sorted({*ours_by_party, *theirs_by_party}):
+        our_amount = ours_by_party.get(party, _ZERO)
+        their_amount = theirs_by_party.get(party, _ZERO)
+        if our_amount != their_amount:
+            mismatches.append(f"{party}: ours {money(our_amount)}, ERPNext {money(their_amount)}")
+    return mismatches
+
+
+def bind_crosscheck(
+    client: _Caller, company: str, index: AccountIndex
+) -> Callable[[Package, TrialBalance, tuple[OpenItem, ...], tuple[OpenItem, ...], Quarter, FiscalYear], list[str]]:
+    """Bind a live `client`, `company`, and chart `index` into `close.py`'s `CloseSteps.crosscheck` shape.
+
+    `package` is accepted (the close ceremony always passes it) but unused: it
+    carries only the rendered files, and every figure this module checks
+    already comes through `trial_balance`/`open_items` as `TrialBalance` and
+    `OpenItem`.
+    """
+
+    def crosscheck(
+        package: Package,
+        trial_balance: TrialBalance,
+        receivables: tuple[OpenItem, ...],
+        payables: tuple[OpenItem, ...],
+        quarter: Quarter,
+        fiscal_year: FiscalYear,
+    ) -> list[str]:
+        del package
+        theirs_tb = read_trial_balance_report(client, company, fiscal_year, quarter)
+        theirs_ar = read_party_summary(client, company, quarter.end, "Receivable")
+        theirs_ap = read_party_summary(client, company, quarter.end, "Payable")
+        return [
+            *trial_balance_mismatches(trial_balance, theirs_tb, index),
+            *open_item_mismatches(receivables, theirs_ar, "Receivable"),
+            *open_item_mismatches(payables, theirs_ap, "Payable"),
+        ]
+
+    return crosscheck

runningtab/period/csvfmt.py

@@ -0,0 +1,86 @@
+"""How every file in the package writes money and rows."""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+from collections.abc import Iterable, Sequence
+from decimal import Decimal
+
+from runningtab.period import PeriodError
+
+_CENT = Decimal("0.01")
+
+# A cell starting with one of these opens as a formula, not text, the moment
+# a spreadsheet opens the file -- and a bank counterparty's remarks are text
+# from outside our control, not something we authored. A tab or carriage
+# return can carry a formula character into a cell a naive check on the
+# first character would miss (some readers treat leading whitespace as part
+# of the formula prefix), so both lead the same way `=`, `+`, and `@` do.
+_LEADING_FORMULA_CHARS = ("=", "+", "@", "\t", "\r")
+
+# `-` alone is not a formula character in any spreadsheet, but Excel's own
+# CSV import treats a `-` cell as one anyway unless what follows is a bare
+# number -- so a plain negative amount like `-12.00` (money()'s own output)
+# must stay untouched while anything else starting with `-` gets escaped.
+_PLAIN_NEGATIVE_NUMBER = re.compile(r"^-\d+(\.\d+)?$")
+
+
+def money(value: Decimal) -> str:
+    """Two places, no separator. Refuses a value that is not a whole number of cents.
+
+    The ledger stores cents; a third decimal place means an upstream parse
+    went wrong, and rounding it away would hide that.
+    """
+    quantized = value.quantize(_CENT)
+    if quantized != value:
+        raise PeriodError(f"amount {value} is not a whole number of cents")
+    if quantized.is_zero():
+        quantized = abs(quantized)
+    return f"{quantized:f}"
+
+
+def is_formula_like(cell: str) -> bool:
+    """Whether a spreadsheet would read `cell` as a formula instead of text.
+
+    Exported (not just used by `spreadsheet_safe_cell` below) so
+    `runningtab.period.qbo` can apply the identical rule to the QBO kit's Name
+    and Account Name columns -- which QuickBooks matches by exact text and
+    so cannot be escaped the way a human-facing cell can, only refused. One
+    predicate, so the two rules cannot drift apart.
+    """
+    if cell.startswith(_LEADING_FORMULA_CHARS):
+        return True
+    return cell.startswith("-") and not _PLAIN_NEGATIVE_NUMBER.match(cell)
+
+
+def spreadsheet_safe_cell(cell: str) -> str:
+    """`cell`, prefixed with `'` if a spreadsheet would otherwise read it as a formula.
+
+    The apostrophe is Excel's and Sheets' own text-marker convention: it is
+    never itself shown, so a person reading the cell sees exactly the text
+    that was there, just no longer live. Exported for `runningtab.period.qbo`'s
+    Journal/Description column: free text, not a key QuickBooks matches on,
+    so it is escaped the same way the human-facing CSVs are rather than
+    refused.
+    """
+    return f"'{cell}" if is_formula_like(cell) else cell
+
+
+def render_csv(header: Sequence[str], rows: Iterable[Sequence[str]], *, spreadsheet_safe: bool = True) -> bytes:
+    """UTF-8 CSV with a header row and `\\n` line endings, identical for identical input.
+
+    `spreadsheet_safe` (the default) escapes any cell that would open as a
+    formula in a spreadsheet -- remarks carry bank counterparty text, which
+    is input from outside this system, not something we authored. Pass
+    `False` for the `qbo/` import files: QBO must receive exactly what was
+    computed, with nothing added.
+    """
+    buffer = io.StringIO()
+    writer = csv.writer(buffer, lineterminator="\n", quoting=csv.QUOTE_MINIMAL)
+    writer.writerow(header)
+    if spreadsheet_safe:
+        rows = ([spreadsheet_safe_cell(cell) for cell in row] for row in rows)
+    writer.writerows(rows)
+    return buffer.getvalue().encode("utf-8")

runningtab/period/documents.py

@@ -0,0 +1,260 @@
+"""The receipts and invoices behind the quarter's vouchers and bank lines."""
+
+from __future__ import annotations
+
+import dataclasses
+import re
+from collections import defaultdict
+from collections.abc import Iterable, Sequence
+from typing import Any, Protocol
+
+import httpx2
+from icedcoffee_sync.frappe.client import FileDownloadError
+
+from runningtab.health import AccountLedger
+from runningtab.period import PeriodError
+from runningtab.period.ledger import GLRow
+from runningtab.period.quarter import Quarter
+
+MAX_DOCUMENT_BYTES = 20 * 1024 * 1024
+_UNSAFE = re.compile(r"[/\\\x00-\x1f]")
+_CHUNK = 100
+
+
+class _Site(Protocol):
+    def iter_all(self, doctype: str, **kwargs: Any) -> Any: ...
+    def download_file(self, file_url: str, *, max_bytes: int) -> bytes: ...
+
+
+def safe_component(text: str) -> str:
+    cleaned = _UNSAFE.sub("_", text)
+    if cleaned in ("", ".", ".."):
+        raise PeriodError(f"{text!r} cannot name a file or directory")
+    return cleaned
+
+
+def quarter_vouchers(rows: Sequence[GLRow], quarter: Quarter) -> list[tuple[str, str]]:
+    return sorted({(r.voucher_type, r.voucher_no) for r in rows if quarter.start <= r.posting_date <= quarter.end})
+
+
+def refuse_unreadable_doctypes(vouchers: Sequence[tuple[str, str]], readable: Iterable[str]) -> None:
+    """Refuse, before listing Files, a voucher type the reader's credential cannot read documents of.
+
+    Frappe filters private Files attached to a document the credential
+    cannot read out of the query results rather than refusing the query, so
+    a voucher type the reader was never granted read on comes back with no
+    Files at all -- indistinguishable from a voucher with no attachments.
+    That is exactly the missed-attachment failure this catches before it
+    ships a package silently short a document nobody is told about.
+    "Bank Transaction" is required even though it never appears in
+    `vouchers`: `read_documents` always queries Files on it too.
+    """
+    readable_set = frozenset(readable)
+    by_doctype: dict[str, list[str]] = defaultdict(list)
+    for doctype, name in vouchers:
+        by_doctype[doctype].append(name)
+    by_doctype.setdefault("Bank Transaction", [])
+    missing = sorted(doctype for doctype in by_doctype if doctype not in readable_set)
+    if not missing:
+        return
+    parts = [
+        f"{doctype} ({', '.join(sorted(by_doctype[doctype]))})" if by_doctype[doctype] else doctype
+        for doctype in missing
+    ]
+    raise PeriodError(
+        "the reader cannot read Files on: "
+        + "; ".join(parts)
+        + "; Frappe silently omits attachments on a doctype it cannot read rather than refusing the query"
+    )
+
+
+def refuse_unreadable_vouchers(client: _Site, vouchers: Sequence[tuple[str, str]]) -> None:
+    """Refuse, before listing Files, a voucher the reader's credential cannot see the document of.
+
+    A doctype-level grant does not guarantee every document: Frappe also
+    honours per-document restrictions (a User Permission, say), and -- the
+    same silent omission `refuse_unreadable_doctypes` catches one level up --
+    filters a private File attached to a document the credential cannot read
+    out of the query results rather than refusing the query. `vouchers`'
+    names come from the general ledger, read under a different grant (`GL
+    Entry`), so nothing before this has proven the reader can see the
+    voucher documents themselves. Listing them back through the reader, in
+    chunks of at most `_CHUNK` names, is what proves it; not listed back
+    means not readable.
+
+    Bank Transactions need no matching check here: `read_bank_transactions`
+    already lists them through the reader's own credential, so whatever it
+    returns is by definition what the reader can see -- there is no
+    separately-sourced candidate list to compare it against, the way GL
+    Entry supplies one for vouchers. `refuse_missing_bank_transactions`
+    below is that check, sourced from the Mercury ledgers instead.
+    """
+    by_doctype: dict[str, list[str]] = defaultdict(list)
+    for doctype, name in vouchers:
+        by_doctype[doctype].append(name)
+    missing: list[str] = []
+    for doctype, names in sorted(by_doctype.items()):
+        seen: set[str] = set()
+        for start in range(0, len(names), _CHUNK):
+            rows = client.iter_all(
+                doctype,
+                fields=["name"],
+                filters=[["name", "in", names[start : start + _CHUNK]]],
+                order_by="name asc",
+            )
+            seen.update(str(r["name"]) for r in rows)
+        absent = sorted(set(names) - seen)
+        if absent:
+            missing.append(f"{doctype} ({', '.join(absent)})")
+    if missing:
+        raise PeriodError(
+            "the reader cannot read voucher document(s): "
+            + "; ".join(missing)
+            + "; Frappe silently omits attachments on a document it cannot read rather than refusing the query"
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class BankTransaction:
+    """One Bank Transaction, as much of it as `read_bank_transactions` needs."""
+
+    name: str
+    # The Mercury transaction this row was posted from -- `runningtab.mercury.posting`'s
+    # TRANSACTION_ID_FIELD -- or None for a row Mercury never posted (a hand
+    # import through Bank Statement Import, say).
+    mercury_transaction_id: str | None
+
+
+def read_bank_transactions(client: _Site, company: str, quarter: Quarter) -> list[BankTransaction]:
+    """Every Bank Transaction dated in `quarter`, draft or submitted -- cancelled excluded.
+
+    `docstatus != 2` rather than `= 1`: a draft row can carry an attachment
+    (a receipt matched to it before it was reconciled and submitted), and
+    excluding drafts here means `read_documents` never queries Files on that
+    row at all -- the attachment is silently missing from the package rather
+    than refused or reported. `order_by="name asc"`: `iter_all` pages by
+    offset over a listing with no unique sort key otherwise, and a page
+    boundary can then skip or repeat a row -- silently dropping an
+    attachment the same way an unhandled short read would.
+
+    `mercury_transaction_id` rides along on the same listing --
+    `refuse_missing_bank_transactions` needs it and a second read of the
+    same doctype would only duplicate this one.
+    """
+    rows = client.iter_all(
+        "Bank Transaction",
+        fields=["name", "mercury_transaction_id"],
+        filters=[
+            ["company", "=", company],
+            ["docstatus", "!=", 2],
+            ["date", ">=", quarter.start.isoformat()],
+            ["date", "<=", quarter.end.isoformat()],
+        ],
+        order_by="name asc",
+    )
+    transactions = [
+        BankTransaction(str(r["name"]), str(r["mercury_transaction_id"]) if r.get("mercury_transaction_id") else None)
+        for r in rows
+    ]
+    return sorted(transactions, key=lambda b: b.name)
+
+
+def refuse_missing_bank_transactions(
+    ledgers: Sequence[AccountLedger], bank_transactions: Sequence[BankTransaction], quarter: Quarter
+) -> None:
+    """Refuse, naming each, a settled Mercury transaction in `quarter` with no matching Bank Transaction.
+
+    `read_bank_transactions`'s listing is the only source `read_documents`
+    has for which Bank Transactions to look for Files on; nothing before
+    this proves that listing is complete. Two different failures produce
+    the identical symptom -- a settled transaction with no Bank Transaction
+    the reader can see, and its attachments (if any) silently absent from
+    the package:
+
+    - A per-document restriction hides a specific Bank Transaction from the
+      reader, the same class of silence `refuse_unreadable_vouchers` exists
+      to catch for vouchers -- but there `vouchers` is an independently
+      sourced candidate list (the general ledger); here, without the
+      Mercury ledgers as that independent source, a hidden row is simply
+      never queried at all.
+    - The Mercury ingest has not posted the quarter's transactions yet, so
+      the Bank Transaction does not exist to be hidden or found.
+
+    This refuses either way, without telling them apart: the fix for both
+    is the same (post or re-check the ingest, or re-provision the reader),
+    and a person reading a silently short package could never distinguish
+    them from the outside regardless.
+    """
+    present = {bt.mercury_transaction_id for bt in bank_transactions if bt.mercury_transaction_id}
+    missing = sorted(
+        (t.id, ledger.label, t.accounting_date)
+        for ledger in ledgers
+        for t in ledger.transactions
+        if t.is_postable and quarter.start <= t.accounting_date <= quarter.end and t.id not in present
+    )
+    if missing:
+        named = "; ".join(f"{tid} ({label}, {date.isoformat()})" for tid, label, date in missing)
+        raise PeriodError(
+            "settled Mercury transaction(s) in the quarter have no matching Bank Transaction the reader can "
+            f"see: {named}; the Mercury ingest may not have posted them yet, or the reader cannot read them"
+        )
+
+
+def read_documents(
+    client: _Site, vouchers: Sequence[tuple[str, str]], bank_transactions: Sequence[str]
+) -> dict[str, bytes]:
+    """Every File attached to `vouchers` or `bank_transactions`, keyed by the path it lands at in the package.
+
+    `order_by="name asc"` on the File listing: `iter_all` pages by offset
+    over a listing with no unique sort key otherwise, and a page boundary
+    can then skip or repeat a row -- silently dropping an attachment.
+    """
+    by_doctype: dict[str, list[str]] = defaultdict(list)
+    for doctype, name in vouchers:
+        by_doctype[doctype].append(name)
+    by_doctype["Bank Transaction"].extend(bank_transactions)
+    documents: dict[str, bytes] = {}
+    sources: dict[str, str] = {}
+    problems: list[str] = []
+    for doctype, names in sorted(by_doctype.items()):
+        for start in range(0, len(names), _CHUNK):
+            files = client.iter_all(
+                "File",
+                fields=["name", "file_name", "file_url", "attached_to_doctype", "attached_to_name", "is_folder"],
+                filters=[
+                    ["attached_to_doctype", "=", doctype],
+                    ["attached_to_name", "in", names[start : start + _CHUNK]],
+                ],
+                order_by="name asc",
+            )
+            for f in files:
+                if int(f.get("is_folder") or 0):
+                    continue
+                path = "/".join([
+                    "documents",
+                    safe_component(doctype),
+                    safe_component(str(f["attached_to_name"])),
+                    safe_component(f"{f['name']}-{f['file_name']}"),
+                ])
+                source = f"File {f['name']} ({f['file_name']}) on {doctype} {f['attached_to_name']}"
+                if path in sources:
+                    # Two distinct Files landing on the same package path is a
+                    # collision this function must never resolve by silently
+                    # overwriting one with the other -- that would drop a
+                    # document from the package without a trace.
+                    raise PeriodError(
+                        f"two Files would land on the same package path {path!r}: {sources[path]} and {source}"
+                    )
+                sources[path] = source
+                try:
+                    documents[path] = client.download_file(str(f["file_url"]), max_bytes=MAX_DOCUMENT_BYTES)
+                # A timeout or a connection error surfaces from httpx2 as
+                # httpx2.HTTPError, not FileDownloadError (that one covers a
+                # bad status or an over-cap read) -- collected the same way,
+                # naming the file and voucher, or it would escape this loop
+                # and crash the whole export instead of refusing it cleanly.
+                except (FileDownloadError, ValueError, httpx2.HTTPError) as exc:
+                    problems.append(f"{doctype} {f['attached_to_name']}: could not fetch {f['file_name']}: {exc}")
+    if problems:
+        raise PeriodError("could not fetch all documents:\n  " + "\n  ".join(sorted(problems)))
+    return dict(sorted(documents.items()))