Carry the municipality on a CEP that does not existHEADv0.2.0main

A CEP that fails 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
block naming the municipality that owns the band, so the library can say
"25845000 does not exist in Areal/RJ" instead of "not found".

It stays an error: lookup still throws Cepis::Error::CEPNotFound, and the
faixa hangs off the exception rather than turning a miss into an address.
Parsing it is deliberately forgiving — a missing, empty or malformed block
yields undef, because losing the clean not-found to a parse failure would be
a worse outcome than losing the context.

cep_ini and cep_fim are the smallest and largest CEP that actually exist,
not the bounds the Correios publish, and the interval between them is
sparse. That is why ceps is exposed alongside them and why the docs say
twice that the pair is not a list of valid CEPs.

1 files changed, 29 insertions, 8 deletions

diff --git a/lib/Cepis/Error.pm b/lib/Cepis/Error.pm
index 080b0a1..37f2a08 100644
--- a/lib/Cepis/Error.pm
+++ b/lib/Cepis/Error.pm
@@ -3,7 +3,7 @@ package Cepis::Error;
 use strict;
 use warnings;
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 use overload
     '""'     => sub { $_[0]->message },
@@ -30,7 +30,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 package Cepis::Error::CEPNotFound;
 
@@ -38,7 +38,9 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
+
+sub faixa { return $_[0]->{faixa} }
 
 package Cepis::Error::Network;
 
@@ -46,7 +48,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 package Cepis::Error::ServerError;
 
@@ -54,7 +56,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 sub status { return $_[0]->{status} }
 
@@ -64,7 +66,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 sub retry_after { return $_[0]->{retry_after} }
 
@@ -74,7 +76,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 1;
 
@@ -171,6 +173,25 @@ message.
 
 The CEP is well-formed but does not exist in the DNE database.
 
+=over 4
+
+=item C<< $err->faixa >>
+
+A L<Cepis::Faixa> naming the municipality the CEP I<would> belong to, or
+C<undef> when it fell in a band no municipality owns. The API omits the block
+rather than sending null, and a malformed one is dropped rather than turning the
+not-found into a parse failure.
+
+It is context for the error, B<not> an address: the lookup still failed. What it
+buys is telling the user "25845000 does not exist in Areal/RJ" instead of "not
+found" — worth having, 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
+C<-000> that 957 municipalities never received.
+
+When it is present, the message already names the municipality.
+
+=back
+
 =head2 Cepis::Error::Network
 
 The request never completed: DNS, refused connection, timeout, TLS.
@@ -217,7 +238,7 @@ as a diagnosis: the problem is not in your code.
 
 =head1 SEE ALSO
 
-L<Cepis>, L<Cepis::Client>
+L<Cepis>, L<Cepis::Client>, L<Cepis::Faixa>
 
 =head1 LICENCE