Carry the municipality of a CEP that does not existHEADv0.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 the 404 with the
municipality that band belongs to, which is enough to tell the user
"Areal/RJ, but not that number" instead of a bare failure.

It stays an error. Faixa hangs off CEPNotFound rather than becoming a
result, cep_ini/cep_fim are documented as the CEPs that exist there and
not as a range to iterate, and an absent or unreadable block yields
undefined so that context can never cost the caller the clean not-found
it was already getting.

1 files changed, 5 insertions, 1 deletions

diff --git a/src/index.ts b/src/index.ts
index 0ac9631..6acccb3 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -34,7 +34,9 @@
  *   const address = await lookup(cepFromForm);
  * } catch (error) {
  *   if (error instanceof CEPNotFound) {
- *     // the CEP does not exist: ask the user for another
+ *     // the CEP does not exist: ask the user for another. `error.faixa`, when
+ *     // present, names the municipality it would have belonged to — context
+ *     // for the message, not an address.
  *   } else if (error instanceof CepisError) {
  *     // network, server, rate limit: retry later
  *   } else {
@@ -70,9 +72,11 @@ export {
 } from "./errors.js";
 export {
   Address,
+  Faixa,
   Geo,
   Health,
   type AddressFields,
+  type FaixaFields,
   type GeoFields,
   type HealthFields,
   type RawObject,