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, 48 insertions, 3 deletions

diff --git a/README.md b/README.md
index ed4988c..67cd2ba 100644
--- a/README.md
+++ b/README.md
@@ -20,9 +20,9 @@ luarocks install cepis
 Targets **Lua 5.4**. It also runs unmodified on 5.1, 5.2, 5.3 and LuaJIT —
 nothing here needs anything newer, so the compatibility was free.
 
-> The rockspec points at `git+https://git.cep.is/lua.git` with tag `v0.1.0`.
+> The rockspec points at `git+https://git.cep.is/lua.git` with tag `v0.2.0`.
 > That repository is not published yet, so `luarocks install cepis` will not
-> resolve until it is. Until then, `luarocks make cepis-0.1.0-1.rockspec` from
+> resolve until it is. Until then, `luarocks make cepis-0.2.0-1.rockspec` from
 > a clone works.
 
 Three rocks are needed, because Lua's standard library ships neither an HTTP
@@ -198,7 +198,8 @@ Every expected failure is returned as `nil, err`. `error()` is raised only for
 programmer mistakes — a bad option table, a wrong argument type.
 
 An error is a table carrying `kind`, `message`, and whichever of `cep`,
-`status` and `retry_after` apply. `tostring(err)` yields the message. The kinds
+`status`, `retry_after` and `faixa` apply. `tostring(err)` yields the message.
+The kinds
 split by **the decision you have to make**, not by the HTTP status that caused
 it:
 
@@ -231,6 +232,50 @@ else a `nil, err` boundary might hand you.
 answering instead of it — a captive Wi-Fi portal, a corporate proxy, an HTML
 error page. Useful as a diagnosis: the problem is not in your code.
 
+### Where a missing CEP would have been
+
+A `not_found` may carry `err.faixa`, naming the municipality the CEP would have
+belonged to. A CEP that fails is rarely a random number: it is usually someone
+who knows the city and guessed the digits, and the classic guess is the `-000`
+that 957 municipalities never received.
+
+```lua
+local address, err = cepis.lookup("25845-000")
+
+err.kind                 -- "not_found"    it still does not exist
+err.faixa:label()        -- "Areal/RJ"
+err.faixa.localidade     -- "Areal"
+err.faixa.uf             -- "RJ"
+err.faixa.ibge           -- "3300225"
+err.faixa.cep_ini        -- "25845001"
+err.faixa.cep_fim        -- "25849899"
+err.faixa.ceps           -- 118
+```
+
+**This is context for an error, not an address.** The lookup failed; `faixa`
+only says where the CEP would have been. Never treat it as a successful
+result.
+
+**`cep_ini` and `cep_fim` are the smallest and largest CEP that actually
+exist** in that municipality — not the range the Correios publish. For Areal
+the published range starts at `25845000`, which is exactly the CEP that just
+failed.
+
+**The range is sparse.** Areal's 118 CEPs are spread over the roughly 4,900
+numbers between `25845001` and `25849899`, so the pair is an interval, never a
+list of valid CEPs — that is what `ceps` is there to say.
+
+`err.faixa` is `nil` whenever the CEP falls in a band no municipality owns: the
+API omits the field there rather than sending null. It is also `nil` if the
+block arrives malformed — a broken piece of context must not turn a clean
+not-found into a parse failure, so always test it before use:
+
+```lua
+if err.kind == cepis.NOT_FOUND and err.faixa then
+  print("no such CEP — did you mean one in " .. err.faixa:label() .. "?")
+end
+```
+
 ## Development
 
 Everything runs through `make`: