Open-source personal finance manager. Self-hosted, privacy-first.
"""What the active workspace's jurisdiction asks for.
The frontend needs labels, masks and ordering to render a document field; the
backend needs normalisation and validation to accept one. Both come from the
same definition, served here, so the two cannot drift into disagreeing about
what a CNPJ looks like.
The response is presentation metadata only. It carries no workspace data and
changes only when the deployment's packs change, so it caches like
`/api/info`.
"""
from fastapi import APIRouter, Depends
from app.core.workspace_context import WorkspaceContext, current_workspace
from app.fiscal.registry import (
TaxIdKind,
available_jurisdictions,
pack_for,
spec_for,
)
router = APIRouter(prefix="/api/fiscal", tags=["fiscal"])
def _kind_payload(kind: TaxIdKind, offered: bool) -> dict:
spec = spec_for(kind)
return {
"kind": kind.value,
"label_key": spec.label_key,
"mask": spec.mask,
# True when this jurisdiction asks for it. Everything else stays
# selectable: the counterparty's country is not the workspace's, so a
# BR workspace still has to be able to store a German VAT number.
"offered": offered,
}
@router.get("/jurisdictions")
async def list_jurisdictions():
"""Codes a pack ships for, for the workspace settings selector.
An empty jurisdiction is a valid choice, not a missing one, so the
frontend offers it alongside these.
"""
return {"jurisdictions": available_jurisdictions()}
@router.get("/product-fields")
async def list_product_fields(ctx: WorkspaceContext = Depends(current_workspace)):
"""Fiscal references this jurisdiction asks for on a catalog item.
Suggestions for the product form: which keys to offer, under which
label, for which kind of product. A workspace may store any key it
likes on top of these; an empty list is a valid answer for a country
whose pack has no opinion yet.
"""
pack = pack_for(ctx.workspace.tax_jurisdiction)
return {
"jurisdiction": pack.code or None,
"fields": [
{"key": f.key, "label_key": f.label_key, "kinds": list(f.kinds)}
for f in pack.product_fields
],
}
@router.get("/tax-id-kinds")
async def list_tax_id_kinds(ctx: WorkspaceContext = Depends(current_workspace)):
"""Document kinds for the active workspace, plus which country uses what.
Two lists, because the picker needs both:
- `kinds`: every document, with the ones this jurisdiction asks for
first and flagged `offered`. The rest stay selectable, since a
counterparty's country is not the workspace's.
- `jurisdictions`: the country-to-documents map, so the picker can
group by country and be searched by country name. It has to come
from here: which documents a country uses *is* the pack, and a
second copy in the frontend would drift from it.
"""
pack = pack_for(ctx.workspace.tax_jurisdiction)
offered = list(pack.kinds)
rest = [kind for kind in TaxIdKind if kind not in offered]
return {
"jurisdiction": pack.code or None,
"kinds": [_kind_payload(kind, True) for kind in offered]
+ [_kind_payload(kind, False) for kind in rest],
"jurisdictions": [
{
"code": code,
# `other` is appended to every pack and would be noise
# repeated under each country; the picker offers it once.
"kinds": [
kind.value
for kind in pack_for(code).kinds
if kind is not TaxIdKind.OTHER
],
}
for code in available_jurisdictions()
],
}