anafpy: Instructions file for Claude Code

CLAUDE.md

Guidance for working in this repository. DESIGN.md is the decision record — rationale, dates, and reversals live there; this file states only the current rules. docs/anaf-reference/ is the compiled local reference of ANAF's APIs. docs/ is also the MkDocs source of the public docs site (Read the Docs, https://anafpy.readthedocs.io).

What this is

anafpy — typed async Python clients for Romania's ANAF tax-authority services, plus a local stdio MCP server (anafpy.mcp, extra anafpy[mcp]) exposing the same operations as Claude tools and skills. It is a thin, stateless transport client — no persistence, no accounting logic; client methods map 1:1 onto MCP tools. Python 3.12+ (dev pin 3.13), httpx2, Pydantic v2.

The service strands:

• e-Factura (electronic invoicing). Outbound has two shapes (DESIGN.md §1): XML pass-through is strongly recommended when the caller runs invoicing software — bring its complete UBL XML; anafpy never re-composes an upstream document, and ANAF's SPV is not invoice storage (it purges filed messages after ~60 days, so the durable record lives upstream). Structured authoring (efactura.authoring) is the first-class path without one: a bidirectional InvoiceDocument covers invoice + credit note (kind picks the render target), totals/VAT computed with explicit overrides preserved, a hand-translated EN 16931 + CIUS-RO rule set (validate(), findings with official BR-* ids; ANAF stays authoritative), byte-stable render/read round-trips, EFacturaClient.upload_invoice. The same model backs the inbox — but not the same contract: the construction checks are authoring's, and nothing the caller did not author is judged by them (_DERIVED_CONTEXT — a document read off the wire, or a value compute_* derives), so the reader never rejects a document ANAF accepted and a read one always renders back. DownloadedMessage.view never raises (None when not representable — a missing mandatory element or off-list code; cause on view_error + a warning; raw bytes + full UBL model are the fallback tiers).
• e-Transport (goods transport) — fully translated: bidirectional flat models author a filing and view a parsed one, covering all four operations (declaration/correction, deletion, confirmation, vehicle change); XML input remains supported. UIT presentation (extra anafpy[cards], DESIGN.md §13) renders a filed declaration into two PDFs — a phone-shaped driver card and an A4 detail document — locally, informative, never issued by ANAF. Validity is ANAF's data_exp_uit when the caller has one and the statutory OUG 41/2022 window otherwise (ANAF discloses the date only to the transport organizer, so that is the common case) — the two are never rendered alike.
• Public no-auth services (anafpy.public) — registry lookups, financial statements, and the stateless e-Factura validare/transformare.
• Exchange rates (anafpy.bnr, DESIGN.md §17) — the one non-ANAF publisher: BNR's reference-rate XML on curs.bnr.ro, for the lei figures ANAF filings need from foreign-currency documents. A rate source, not a ruling: it returns what BNR published on a day; which day a filing must use is the caller's (and the workflow skill's) call.
• SPV (anafpy.spv) — read-only mailbox over a certificate cookie session.
• Declarations (anafpy.declaratii, DESIGN.md §12) — local authoring + validation via ANAF's DUKIntegrator (managed-installed from ANAF's update feed), official-PDF rendering, qualified signing (the raw op delegated to the OS token — no key material or PIN in-process), portal filing (production-only; opt-out ANAFPY_DECLARATII_UPLOAD=off), and no-auth StareD112 status/recipisa tracking.