Open-source personal finance manager. Self-hosted, privacy-first.
"""Jurisdiction packs: which documents a country asks for, in what order.
The split that makes this work, and the one thing to preserve if this file is
ever refactored:
- **A kind defines the document.** How to normalise it, how to validate it,
how to mask it, what to call it. One definition, in code, used everywhere.
A CNPJ is fourteen digits with a check digit whether the workspace is set
to Brazil, to Germany, or to nothing at all, so a stored value stays
comparable and a document typed in one workspace means the same in the
next.
- **A jurisdiction chooses from them.** A pack is a country code and an
ordered list of kinds, nothing more. It cannot weaken a validator, cannot
rename a document, and cannot make the same kind behave differently than
it does elsewhere.
That split is deliberate and was arrived at the hard way: an earlier version
let packs carry their own `normalise`, and a German VAT number stored from a
Brazilian workspace came out spaced differently than the same number stored
from a German one.
Two further properties:
- **A pack suggests; it never restricts.** It sets what a workspace is
*offered*. Every kind stays storable in every workspace, because the
counterparty's country is not the workspace's: a Brazilian consultancy
billing a Berlin client needs `vat`, and the BR pack must not forbid it.
- **No pack is a working configuration.** An unset or unknown
`tax_jurisdiction` resolves to FALLBACK: free text under `other`, no
mask, no validation. Packs are enhancement, never a prerequisite, so a
country nobody has contributed yet is usable today.
Adding a country is one TOML file. Adding a *document* is a new `TaxIdKind`
plus one entry in KIND_SPECS, and a named validator if its format is
checkable. Both are pull requests, which is the point: a document that no
code understands is a document no export can use.
"""
import re
import tomllib
from dataclasses import dataclass
from enum import Enum
from functools import lru_cache
from pathlib import Path
from app.fiscal.validators import NORMALISERS, VALIDATORS
PACK_DIR = Path(__file__).parent / "jurisdictions"
class TaxIdKind(str, Enum):
"""Every document the product can store.
Closed on purpose. A free-form string would make the stored value
uninterpretable, which is the failure this whole design exists to avoid.
A kind names **one specific document**, never a category. Portugal's and
Spain's national numbers are both called NIF and are different documents
with different check rules, so they are different kinds. `vat` is the one
genuinely shared scheme: the country prefix is part of the value.
"""
# Brazil
CNPJ = "cnpj"
CPF = "cpf"
IE = "ie"
IM = "im"
# Iberia
PT_NIF = "pt_nif"
ES_NIF = "es_nif"
# European VAT, including the UK, whose numbers still fit the shape
VAT = "vat"
# Germany's domestic number, distinct from its USt-IdNr
STEUERNUMMER = "steuernummer"
# Italy
PARTITA_IVA = "partita_iva"
CODICE_FISCALE = "codice_fiscale"
SDI = "sdi"
# France
SIRET = "siret"
# United States
EIN = "ein"
# Rest of Europe. Prefixed where the acronym is not unique: SE and NO both
# call theirs an organisasjons/organisationsnummer, and they check
# differently.
NIP = "nip"
SE_ORGNR = "se_orgnr"
NO_ORGNR = "no_orgnr"
CVR = "cvr"
ICO = "ico"
ADOSZAM = "adoszam"
RO_CUI = "ro_cui"
CH_UID = "ch_uid"
INN = "inn"
KZ_BINIIN = "kz_biniin"
EDRPOU = "edrpou"
# Latin America
CUIT = "cuit"
RFC = "rfc"
CL_RUT = "cl_rut"
UY_RUT = "uy_rut"
CO_NIT = "co_nit"
GT_NIT = "gt_nit"
PE_RUC = "pe_ruc"
CR_CEDULA = "cr_cedula"
RNC = "rnc"
# Rest of the world
CA_BN = "ca_bn"
ABN = "abn"
NZBN = "nzbn"
JP_CORPORATE = "jp_corporate"
GSTIN = "gstin"
PAN = "pan"
NPWP = "npwp"
PH_TIN = "ph_tin"
VN_MST = "vn_mst"
SG_UEN = "sg_uen"
USCC = "uscc"
AZ_VOEN = "az_voen"
# The escape hatch. Always offered, never validated.
OTHER = "other"
@dataclass(frozen=True)
class KindSpec:
"""What one document is, independent of who asks for it."""
kind: TaxIdKind
label_key: str
# Presentation only: the frontend applies it, the backend ignores it.
mask: str | None = None
normalise: str = "trim"
validate: str = "none"
def normalised(self, value: str) -> str:
return NORMALISERS[self.normalise](value)
def error_for(self, value: str) -> str | None:
"""None when acceptable, else a short machine-readable reason."""
if not value:
return "empty"
return VALIDATORS[self.validate](value)
def _spec(
kind: TaxIdKind, normalise: str = "trim", validate: str = "none", mask: str | None = None
) -> KindSpec:
return KindSpec(
kind=kind,
label_key=f"fiscal.kind.{kind.value}",
mask=mask,
normalise=normalise,
validate=validate,
)
#: One definition per document. `ie` and `im` are unvalidated on purpose: the
#: twenty-seven Brazilian state schemes disagree with each other, and "ISENTO"
#: is a legitimate value.
#:
#: A mask is only given to a document of **fixed** length. Masks are applied as
#: the user types and truncate at the template's width, so putting one on a
#: variable-length document mangles the short form of it: a seven-digit Chilean
#: RUT under an eight-digit mask reads back as `12.345.67-8`. Those kinds are
#: shown as typed instead, which is correct if plainer.
KIND_SPECS: dict[TaxIdKind, KindSpec] = {
TaxIdKind.CNPJ: _spec(TaxIdKind.CNPJ, "digits", "br_cnpj", "##.###.###/####-##"),
TaxIdKind.CPF: _spec(TaxIdKind.CPF, "digits", "br_cpf", "###.###.###-##"),
TaxIdKind.IE: _spec(TaxIdKind.IE, "upper_alnum"),
TaxIdKind.IM: _spec(TaxIdKind.IM, "upper_alnum"),
TaxIdKind.PT_NIF: _spec(TaxIdKind.PT_NIF, "digits", "pt_nif", "### ### ###"),
TaxIdKind.ES_NIF: _spec(TaxIdKind.ES_NIF, "upper_alnum", "es_nif"),
TaxIdKind.VAT: _spec(TaxIdKind.VAT, "upper_alnum", "eu_vat_format"),
TaxIdKind.STEUERNUMMER: _spec(TaxIdKind.STEUERNUMMER, "digits", "de_steuernummer"),
TaxIdKind.PARTITA_IVA: _spec(TaxIdKind.PARTITA_IVA, "digits", "it_partita_iva"),
TaxIdKind.CODICE_FISCALE: _spec(TaxIdKind.CODICE_FISCALE, "upper_alnum", "it_codice_fiscale"),
TaxIdKind.SDI: _spec(TaxIdKind.SDI, "upper_alnum"),
TaxIdKind.SIRET: _spec(TaxIdKind.SIRET, "digits", "fr_siret", "### ### ### #####"),
TaxIdKind.EIN: _spec(TaxIdKind.EIN, "digits", "us_ein", "##-#######"),
# Rest of Europe
TaxIdKind.NIP: _spec(TaxIdKind.NIP, "digits", "pl_nip", "###-###-##-##"),
TaxIdKind.SE_ORGNR: _spec(TaxIdKind.SE_ORGNR, "digits", "se_orgnr", "######-####"),
TaxIdKind.NO_ORGNR: _spec(TaxIdKind.NO_ORGNR, "digits", "no_orgnr", "### ### ###"),
TaxIdKind.CVR: _spec(TaxIdKind.CVR, "digits", "dk_cvr"),
TaxIdKind.ICO: _spec(TaxIdKind.ICO, "digits", "cz_ico"),
TaxIdKind.ADOSZAM: _spec(TaxIdKind.ADOSZAM, "digits", "hu_adoszam"),
TaxIdKind.RO_CUI: _spec(TaxIdKind.RO_CUI, "digits", "ro_cui"),
# The mask supplies the CHE prefix, so it reads back whole even when only
# the nine digits were typed.
TaxIdKind.CH_UID: _spec(TaxIdKind.CH_UID, "upper_alnum", "ch_uid", "CHE-###.###.###"),
TaxIdKind.INN: _spec(TaxIdKind.INN, "digits", "ru_inn"),
TaxIdKind.KZ_BINIIN: _spec(TaxIdKind.KZ_BINIIN, "digits", "kz_biniin", "### ### ### ###"),
TaxIdKind.EDRPOU: _spec(TaxIdKind.EDRPOU, "digits", "ua_edrpou"),
# Latin America
TaxIdKind.CUIT: _spec(TaxIdKind.CUIT, "digits", "ar_cuit", "##-########-#"),
# `upper_compact` rather than `upper_alnum`: an RFC may contain `&`, which
# dropping would turn a valid document into a different one.
TaxIdKind.RFC: _spec(TaxIdKind.RFC, "upper_compact", "mx_rfc"),
TaxIdKind.CL_RUT: _spec(TaxIdKind.CL_RUT, "upper_alnum", "cl_rut"),
TaxIdKind.UY_RUT: _spec(TaxIdKind.UY_RUT, "digits", "uy_rut"),
TaxIdKind.CO_NIT: _spec(TaxIdKind.CO_NIT, "digits", "co_nit"),
TaxIdKind.GT_NIT: _spec(TaxIdKind.GT_NIT, "upper_alnum"),
TaxIdKind.PE_RUC: _spec(TaxIdKind.PE_RUC, "digits", "pe_ruc"),
TaxIdKind.CR_CEDULA: _spec(TaxIdKind.CR_CEDULA, "digits", "cr_cedula"),
TaxIdKind.RNC: _spec(TaxIdKind.RNC, "digits", "do_rnc"),
# Rest of the world
TaxIdKind.CA_BN: _spec(TaxIdKind.CA_BN, "digits", "ca_bn", "### ### ###"),
TaxIdKind.ABN: _spec(TaxIdKind.ABN, "digits", "au_abn", "## ### ### ###"),
TaxIdKind.NZBN: _spec(TaxIdKind.NZBN, "digits", "nz_nzbn"),
TaxIdKind.JP_CORPORATE: _spec(TaxIdKind.JP_CORPORATE, "digits", "jp_corporate"),
TaxIdKind.GSTIN: _spec(TaxIdKind.GSTIN, "upper_alnum", "in_gstin"),
TaxIdKind.PAN: _spec(TaxIdKind.PAN, "upper_alnum", "in_pan"),
TaxIdKind.NPWP: _spec(TaxIdKind.NPWP, "digits", "id_npwp"),
TaxIdKind.PH_TIN: _spec(TaxIdKind.PH_TIN, "digits", "ph_tin"),
TaxIdKind.VN_MST: _spec(TaxIdKind.VN_MST, "digits", "vn_mst"),
TaxIdKind.SG_UEN: _spec(TaxIdKind.SG_UEN, "upper_alnum", "sg_uen"),
TaxIdKind.AZ_VOEN: _spec(TaxIdKind.AZ_VOEN, "digits", "az_voen", "##########"),
TaxIdKind.USCC: _spec(TaxIdKind.USCC, "upper_alnum", "cn_uscc"),
TaxIdKind.OTHER: _spec(TaxIdKind.OTHER, "trim"),
}
def spec_for(kind: TaxIdKind) -> KindSpec:
"""The definition of a document. Never jurisdiction-dependent."""
return KIND_SPECS[kind]
@dataclass(frozen=True)
class ProductFieldSpec:
"""A fiscal reference a jurisdiction asks for on a catalog item.
What the fiscal document will need per line and the invoice cannot
invent: a goods classification (NCM in Brazil, an HS code in the EU),
a service code, a barcode. Suggested by the pack, stored as free
text on the product, copied onto the line when the product fills
it. Any key stays storable in any workspace, for the same reason as
tax ids: the pack suggests, it never restricts.
"""
key: str
label_key: str
#: Which kinds of product it applies to. Empty means both.
kinds: tuple[str, ...] = ()
@dataclass(frozen=True)
class JurisdictionPack:
code: str
#: Ordered. The first is what the UI defaults to; `other` is always last.
kinds: tuple[TaxIdKind, ...]
product_fields: tuple[ProductFieldSpec, ...] = ()
#: What a deployment with no jurisdiction set gets. Empty of opinions rather
#: than quietly defaulting to somebody's country.
FALLBACK = JurisdictionPack(code="", kinds=(TaxIdKind.OTHER,))
_PRODUCT_KINDS = ("service", "product")
_FIELD_KEY = re.compile(r"^[a-z][a-z0-9_]{0,39}$")
def _load_pack(path: Path) -> JurisdictionPack:
raw = tomllib.loads(path.read_text(encoding="utf-8"))
code = str(raw["code"]).upper()
kinds = [TaxIdKind(name) for name in raw["kinds"]]
for kind in kinds:
if kind not in KIND_SPECS:
raise ValueError(f"{path.name}: {kind.value} has no spec")
# `other` is always available, so any jurisdiction can hold a document
# its pack never anticipated.
if TaxIdKind.OTHER not in kinds:
kinds.append(TaxIdKind.OTHER)
fields = []
for raw_field in raw.get("product_fields", []):
key = str(raw_field["key"])
if not _FIELD_KEY.match(key):
raise ValueError(f"{path.name}: product field key {key!r} is not a valid key")
applies = tuple(str(k) for k in raw_field.get("kinds", ()))
if any(k not in _PRODUCT_KINDS for k in applies):
raise ValueError(f"{path.name}: product field {key} names an unknown product kind")
fields.append(
ProductFieldSpec(key=key, label_key=f"fiscal.productField.{key}", kinds=applies)
)
return JurisdictionPack(code=code, kinds=tuple(kinds), product_fields=tuple(fields))
@lru_cache(maxsize=1)
def _packs() -> dict[str, JurisdictionPack]:
"""Parsed once per process. The files ship with the image."""
return {pack.code: pack for pack in (_load_pack(p) for p in sorted(PACK_DIR.glob("*.toml")))}
def available_jurisdictions() -> list[str]:
"""Codes a pack exists for, for the settings selector."""
return sorted(_packs())
def pack_for(jurisdiction: str | None) -> JurisdictionPack:
"""The pack for a workspace, or FALLBACK when unset or unshipped."""
if not jurisdiction:
return FALLBACK
return _packs().get(jurisdiction.strip().upper(), FALLBACK)
def apply_mask(value: str, mask: str | None) -> str:
"""A stored value formatted for a human to read.
A mask is a template where `#` takes one digit and every other
character is a literal, so `##.###.###/####-##` turns 14 digits into
a CNPJ. A kind with no mask is returned untouched, which is what
keeps a jurisdiction nobody has described from being mangled.
This mirrors `applyMask` in `frontend/src/lib/tax-id.ts` deliberately:
the frontend needs it to format *as the user types*, and the server
needs it because a PDF has no frontend to ask. Same rule, and the
tests on both sides assert the same CNPJ.
"""
if not mask:
return value
digits = [c for c in value if c.isdigit()]
# Only a value that fills the mask exactly is formatted. Too few digits
# would render a half-masked document ("12.3" for "123"), and too many
# would silently drop the tail — both worse than showing what is
# stored. Values reaching here are normalised on write, so a mismatch
# means an unmasked kind or data from before a pack changed.
if len(digits) != mask.count("#"):
return value
out: list[str] = []
index = 0
for char in mask:
if char == "#":
out.append(digits[index])
index += 1
else:
out.append(char)
return "".join(out)
def format_for_display(kind: TaxIdKind, value: str) -> str:
"""The document as it should appear on a rendered page."""
return apply_mask(value, spec_for(kind).mask)
def normalise_and_validate(kind: TaxIdKind, value: str) -> tuple[str, str | None]:
"""Store-ready value, plus a reason when it should be refused.
Takes no jurisdiction: a document is checked by what it is, not by who
is holding it. The jurisdiction decides only what a workspace is offered.
"""
spec = spec_for(kind)
normalised = spec.normalised(value)
return normalised, spec.error_for(normalised)