From 4ebb31f26efed74f8fcb049fe27ddf7cf5388a08 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:31:55 -0300 Subject: Carry the municipality of a CEP that does not exist 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. --- src/index.ts | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) (limited to 'src/index.ts') 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, -- cgit v1.3