Expose the municipality behind a not-found CEPHEADv0.2.0main

A CEP that fails a lookup is rarely random: it is usually someone who
knows the city and guessed the number, and the classic guess is the -000
that 957 municipalities never received. The API now names, on the 404
itself, the municipality that CEP would have belonged to, so a caller can
say "not found — did you mean somewhere in Areal/RJ?" instead of just
"not found".

CepNotFound carries it as an optional Faixa. It stays an error: the block
is context, not an address, and the range it describes is sparse, which
is why it reports a count alongside the first and last CEP that actually
exist there rather than the bounds the Correios publish. Parsing it is
best-effort on purpose — a missing, empty or malformed block leaves the
optional empty, since a 404 is already the answer and reading the hint
attached to it must never cost the diagnosis.

1 files changed, 19 insertions, 0 deletions

diff --git a/src/models.cpp b/src/models.cpp
index 84e03f9..088283b 100644
--- a/src/models.cpp
+++ b/src/models.cpp
@@ -124,6 +124,25 @@ Address Address::from_json(const Json& data) {
   return address;
 }
 
+std::optional<Faixa> Faixa::from_json(const Json& data) {
+  if (!data.is_object()) {
+    return std::nullopt;
+  }
+  Faixa faixa;
+  faixa.localidade = as_field(data.find("localidade"));
+  faixa.uf = as_field(data.find("uf"));
+  if (faixa.localidade.empty() || faixa.uf.empty()) {
+    return std::nullopt;
+  }
+  faixa.estado = as_field(data.find("estado"));
+  faixa.regiao = as_field(data.find("regiao"));
+  faixa.ibge = as_field(data.find("ibge"));
+  faixa.cep_ini = as_field(data.find("cep_ini"));
+  faixa.cep_fim = as_field(data.find("cep_fim"));
+  faixa.ceps = as_integer(data.find("ceps")).value_or(0);
+  return faixa;
+}
+
 Health Health::from_json(const Json& data) {
   Health health;
   health.status = as_field(data.find("status"));