Carry the municipality of a missing CEP on not_foundHEADv0.2.0main

A CEP that fails is rarely a random number: it is someone who knows the
city and guessed the digits, and the classic guess is the -000 that 957
municipalities never received. The API now answers that 404 with an
optional faixa block naming where the CEP would have been, so a caller
can turn "CEP does not exist" into something the user can act on.

It hangs off the error, never off an address: the lookup still failed.
Parsing gives up quietly at every step — no block, a block that is not
an object, one without a municipality to name — because a broken piece
of context must not turn a clean not-found into a parse failure.

cep_ini and cep_fim are the CEPs that exist, not the range the Correios
publish, and the interval between them is sparse; ceps is what keeps the
pair from being read as a list of valid CEPs.

1 files changed, 5 insertions, 0 deletions

diff --git a/cepis.lua b/cepis.lua
index e120af1..1027db3 100644
--- a/cepis.lua
+++ b/cepis.lua
@@ -65,6 +65,9 @@ M.Address = models.Address
 --- The `Geo` metatable.
 M.Geo = models.Geo
 
+--- The `Faixa` metatable, for the `faixa` a `not_found` error may carry.
+M.Faixa = models.Faixa
+
 --- The `Health` metatable.
 M.Health = models.Health
 
@@ -72,6 +75,8 @@ M.Health = models.Health
 M.INVALID_CEP = errors.INVALID_CEP
 
 --- Error kind: well-formed, but absent from the DNE database.
+--
+-- `err.faixa` may name the municipality the CEP would have belonged to.
 M.NOT_FOUND = errors.NOT_FOUND
 
 --- Error kind: 429 on every attempt. `err.retry_after` may hold seconds.