Arquitetura

O pt-fiscal é um conjunto de funções puras agrupadas por domínio, sem estado partilhado e sem dependências em runtime. Cada validador normaliza o input, aplica uma verificação estrutural e um checksum/dígito de controlo.

flowchart LR
  IN["input em bruto<br/>(NIF / IBAN / CP7)"] --> N["normalizar<br/>(tirar espaços, prefixo PT)"]
  N --> S{"estrutura ok?"}
  S -- não --> F["false"]
  S -- sim --> C["checksum / dígito de controlo<br/>(mod-11 · ISO 7064 mod-97)"]
  C --> R["valid : boolean"]

Mapa de módulos

Módulo	Responsabilidade
nif.ts	Normalizar NIF, classificar tipo de entidade, dígito de controlo mod-11
iban.ts	Normalizar IBAN, checksum ISO 7064 mod-97, regra de comprimento PT
postal.ts	Validação e normalização do formato CP7
atcud.ts	Construir/validar o código único de documento
qrcode.ts	Compor a string de campos do QR da fatura da AT
index.ts	Superfície da API pública

Princípios de design

• Puras & determinísticas — cada função é input → output, segura no cliente ou servidor.
• Zero dependências em runtime — nada para auditar ou atualizar; distribuído como ESM com tipos.
• Estrutura, não existência — a validação prova a forma e os dígitos de controlo, nunca que um identificador está atribuído/ativo.
• Composição em vez de bundling — o builder do QR devolve uma string; a renderização é escolha tua (mantém o pacote sem dependências).