Name the municipality behind a CEP that does not existHEADv0.2.0main

A CEP lookup that fails is rarely a random number: it is usually someone
who knows the city and guessed the last digits, most often the -000 that
957 municipalities never received. The API now answers those 404s with a
`faixa` naming the municipality the number would have belonged to and the
first and last CEP that really exist there, so the shopper can be told
"esse número seria de Areal/RJ" instead of a bare "não encontrado".

It stays an error. The address does not exist, so no field is filled from
`faixa` — quietly writing the city of a CEP that does not exist would
produce a wrong address, which is worse than an empty form. Only the
wording of the message changes. The range is sparse (Areal has 118 CEPs
over some 4,900 numbers), so it is shown as a hint of where to look, never
as a list to pick from.

Parsing is defensive throughout: a body that is not JSON, a `faixa` that is
not an object, a missing localidade or uf, a malformed range — each falls
back to the message shipped before, and none of it can throw.

1 files changed, 26 insertions, 1 deletions

diff --git a/test/server.js b/test/server.js
index 720f4a0..db31c63 100644
--- a/test/server.js
+++ b/test/server.js
@@ -40,6 +40,26 @@ const ADDRESSES = {
   },
 };
 
+/**
+ * The `faixa` a 404 carries when the CEP falls inside a municipality that
+ * simply never received that number. `25845000` is the real Areal/RJ shape —
+ * the `-000` that municipality never got. `25845999` is deliberately broken,
+ * so the tests can prove a malformed `faixa` degrades to the plain message.
+ */
+const FAIXAS = {
+  25845000: {
+    localidade: "Areal",
+    uf: "RJ",
+    estado: "Rio de Janeiro",
+    regiao: "Sudeste",
+    ibge: "3300225",
+    cep_ini: "25845001",
+    cep_fim: "25849899",
+    ceps: 118,
+  },
+  25845999: { uf: "RJ", cep_ini: 25845001 },
+};
+
 const CORS = {
   "Access-Control-Allow-Origin": "*",
   "Content-Type": "application/json; charset=utf-8",
@@ -105,8 +125,13 @@ export function startApi() {
       }
       const address = ADDRESSES[path];
       if (!address) {
+        const faixa = FAIXAS[path];
         return new Response(
-          JSON.stringify({ erro: "cep_nao_encontrado", mensagem: "CEP não existe na base do DNE" }),
+          JSON.stringify({
+            erro: "cep_nao_encontrado",
+            mensagem: "CEP não existe na base do DNE",
+            ...(faixa ? { faixa } : {}),
+          }),
           { status: 404, headers: CORS },
         );
       }