Expose the band of a CEP that does not existHEADv0.2.0main

A CEP that fails a lookup is rarely a random number: it is someone who
knows the city and guessed the digits, most often the -000 that 957
municipalities never received. The API now answers that 404 with an
optional faixa naming the municipality those numbers belong to, so the
caller can say "not found, but you seem to be looking at Areal/RJ"
instead of just "not found".

It stays an error. Faixa hangs off CEPNotFound and nothing about it
promotes a nonexistent CEP into an address. Its cep_ini/cep_fim are the
smallest and largest CEP that really exist there, not the published
bounds — the DNE's own start for Areal is the CEP that just failed — and
the band is sparse, which is what ceps is for; both facts are spelled
out in the docs so nobody iterates the pair.

Parsing is deliberately toothless: a missing, empty or malformed faixa,
or a 404 body that is not JSON at all, all yield nil. Losing the
consolation prize must never replace a clean not-found with a parse
failure.

1 files changed, 19 insertions, 1 deletions

diff --git a/lib/cepis/errors.rb b/lib/cepis/errors.rb
index 7a15841..71b8a29 100644
--- a/lib/cepis/errors.rb
+++ b/lib/cepis/errors.rb
@@ -27,7 +27,25 @@ module Cepis
   class InvalidCEP < Error; end
 
   # The CEP is well-formed but does not exist in the DNE database.
-  class CEPNotFound < Error; end
+  class CEPNotFound < Error
+    # The municipality that owns the band this CEP falls into, as a {Faixa},
+    # or `nil` when no municipality owns it — or when the API did not say.
+    #
+    # It is context for the failure, not a fallback address: the CEP asked for
+    # does not exist, and this only names the neighbourhood of numbers it
+    # would have belonged to. Useful because a CEP that fails is usually a
+    # guess by someone who knows the city, so the municipality is the one
+    # thing about it that tends to be right.
+    #
+    # Read {Faixa} before showing `cep_ini`/`cep_fim` to anyone: the band is
+    # sparse, and the pair is not a range of valid CEPs.
+    attr_reader :faixa
+
+    def initialize(message, faixa: nil)
+      super(message)
+      @faixa = faixa
+    end
+  end
 
   # The request never completed: DNS, refused connection, timeout, TLS.
   #