Carry the municipality of a not-found CEP on the exceptionHEADv0.2.0main

The API now sends an optional faixa block on the 404 of GET /{cep}, naming
the municipality the CEP would have belonged to. That failing CEP is rarely
random: it is usually someone who knows the city and guessed the number,
most often the -000 that 957 municipalities never received. Knowing the
lookup failed "in Areal/RJ" is the difference between a message a user can
act on and a bare "CEP not found".

It stays an error. Faixa hangs off CepNotFoundException, never off Address,
and parsing is deliberately forgiving: a missing, empty or malformed block
yields null rather than turning a clean not-found into a parse failure.
Its cep_ini/cep_fim are the CEPs that exist, not the bounds the Correios
publish, and the interval between them is sparse -- hence ceps, and hence
the docblocks insisting the pair is not a list of valid CEPs.

1 files changed, 19 insertions, 0 deletions

diff --git a/src/CepNotFoundException.php b/src/CepNotFoundException.php
index c64de8b..e9511e7 100644
--- a/src/CepNotFoundException.php
+++ b/src/CepNotFoundException.php
@@ -9,7 +9,26 @@ namespace Cepis;
  *
  * Extends `\OutOfBoundsException`, the SPL type for a value that is not a
  * valid key: looking a CEP up is conceptually a key lookup.
+ *
+ * {@see CepNotFoundException::$faixa} may name the municipality the CEP would
+ * have belonged to. It does not soften the answer — the CEP still does not
+ * exist — it only makes the failure sayable: *"we could not find that CEP in
+ * Areal/RJ"* rather than *"CEP not found"*.
  */
 final class CepNotFoundException extends \OutOfBoundsException implements CepisException
 {
+    /**
+     * @param Faixa|null $faixa The municipality whose range covers the CEP, or
+     *     `null` when the API sent none — which is the case for a CEP in a band
+     *     no municipality owns, and also whenever the block cannot be read.
+     *     Never assume it is there. See {@see Faixa} for why the range it
+     *     carries is not a list of valid CEPs.
+     */
+    public function __construct(
+        string $message,
+        public readonly ?Faixa $faixa = null,
+        ?\Throwable $previous = null,
+    ) {
+        parent::__construct($message, 0, $previous);
+    }
 }