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, 5 insertions, 2 deletions

diff --git a/include/cepis/client.hpp b/include/cepis/client.hpp
index 205ba85..3a0d863 100644
--- a/include/cepis/client.hpp
+++ b/include/cepis/client.hpp
@@ -15,7 +15,7 @@
 namespace cepis {
 
 /// The library version, as it appears in the default `User-Agent`.
-inline constexpr std::string_view kVersion = "0.1.0";
+inline constexpr std::string_view kVersion = "0.2.0";
 
 /// Where the public API lives.
 inline constexpr std::string_view kDefaultBaseUrl = "https://cep.is";
@@ -33,7 +33,7 @@ inline constexpr std::size_t kMaxBatch = 500;
 /// trip for the server to say so wastes both sides' time.
 std::string normalize_cep(std::string_view value);
 
-/// The default `User-Agent`, e.g. `cepis-cpp/0.1.0 (+https://cep.is)`.
+/// The default `User-Agent`, e.g. `cepis-cpp/0.2.0 (+https://cep.is)`.
 std::string default_user_agent();
 
 /// How a `Client` behaves. Every field has a working default; in practice only
@@ -108,6 +108,9 @@ class Client {
   /// 5xx after every attempt; `NetworkError` when the request never
   /// completed; `InvalidResponse` when a success status carries a body that
   /// is not a JSON object.
+  ///
+  /// A `CepNotFound` often carries `faixa()`, the municipality the CEP would
+  /// have belonged to. It is context for the error, not an address.
   [[nodiscard]] Address lookup(std::string_view cep) const;
 
   /// Looks up many CEPs in one batch.