Carry the municipality range on a not-found CEPHEADv0.2.0main

A CEP that fails a lookup is rarely a random number. It is usually
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
those 404s with a faixa naming the municipality whose band the number
falls into, so a caller can ask "did you mean somewhere in Areal/RJ?"
instead of returning a bare "not found".

Cep_not_found becomes an inline record so the context rides along with
the message, matching how Rate_limited and Server_error already carry
theirs. It is still a 404: faixa is context on the failure and never
promotes it to an address, and its bounds are the smallest and largest
CEP that actually exist there — sparse across the interval, which is
what the ceps count is for — not the bounds the Correios publish.

Parsing is deliberately lenient. A missing, null, malformed or
municipality-less faixa yields None rather than an error: a 404 is a
clean answer, and no shape of this field should turn it into an
Invalid_response.

1 files changed, 51 insertions, 4 deletions

diff --git a/lib/cepis.mli b/lib/cepis.mli
index 3deeb0b..6920a9d 100644
--- a/lib/cepis.mli
+++ b/lib/cepis.mli
@@ -116,6 +116,37 @@ val is_ok : health -> bool
 
 (** {1 Errors} *)
 
+type faixa = {
+  localidade : string;
+  uf : string;
+  estado : string;
+  regiao : string;
+  ibge : string;
+  cep_ini : string;
+  cep_fim : string;
+  ceps : int;
+}
+(** The municipality that owns the band a {b nonexistent} CEP falls into.
+
+    This is {b context for an error, not an address}. It arrives on
+    {!Cep_not_found}, the lookup still failed, and nothing here says the CEP
+    exists — it says which city it {i would} belong to if it did. Never promote
+    it to a result: the number the caller typed is not deliverable.
+
+    It exists because a failing CEP 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.
+
+    [cep_ini] and [cep_fim] are the smallest and the largest CEP that
+    {b actually exist} in that municipality — not the bounds the Correios
+    publish. For Areal/RJ the DNE's own start is [25845000], which is precisely
+    the CEP that just failed; [cep_ini] is [25845001].
+
+    The range is {b sparse}, and that is what [ceps] is for. Areal's 118 CEPs
+    are scattered across the ~4,900 numbers between [25845001] and [25849899].
+    Presenting the pair as "valid from … to …" would be wrong for about 98% of
+    the interval: it is a bounding box, not a list. *)
+
 (** Everything that can go wrong, split by
     {b the decision the caller has to make} rather than by the HTTP status that
     caused it.
@@ -129,9 +160,17 @@ type error =
       (** The CEP is not 8 digits. Usually produced {b without} a request ever
           being made — the client checks the format before going to the network.
           Retrying is pointless. *)
-  | Cep_not_found of string
+  | Cep_not_found of { message : string; faixa : faixa option }
       (** The CEP is well-formed but does not exist in the DNE database.
-          Retrying is pointless. *)
+          Retrying is pointless.
+
+          [faixa] names the municipality whose band that number falls into, when
+          it falls into one — enough to answer "did you mean Areal/RJ?" instead
+          of a bare "not found". It is [None] when the CEP lands in a band no
+          municipality owns, and also whenever the field cannot be read: a 404
+          is a clean answer, and no shape of [faixa] turns it into a
+          {!Invalid_response}. See {!faixa} for what its bounds do and do not
+          mean. *)
   | Rate_limited of { message : string; retry_after : float option }
       (** The API (or the edge in front of it) answered 429 on every attempt.
           [retry_after] is what the server asked for, in seconds, or [None] if
@@ -155,7 +194,11 @@ val error_message : error -> string
 (** The human-readable message carried by an error, without its kind. *)
 
 val string_of_error : error -> string
-(** The error rendered for a log line: kind, then message. *)
+(** The error rendered for a log line: kind, then message.
+
+    A {!Cep_not_found} carrying a {!faixa} names the municipality, because "CEP
+    25845000 does not exist" and "…and it would have been in Areal/RJ" are two
+    very different lines to find in a log. *)
 
 (** {1 Validation} *)
 
@@ -234,7 +277,11 @@ module Client : sig
 
       A 400 from the API surfaces as {!Invalid_cep} carrying the API's own
       message: the format already passed local validation, so the server knows
-      something this client does not. *)
+      something this client does not.
+
+      A 404 surfaces as {!Cep_not_found}, and it may carry a {!faixa} naming the
+      municipality the number would have belonged to. That is context on the
+      failure; it never becomes an [Ok]. *)
 
   val lookup_many : t -> string list -> (address option list, error) result
   (** [lookup_many client ceps] resolves many CEPs in one batch.