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.

3 files changed, 188 insertions, 4 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);
+    }
 }
diff --git a/src/Client.php b/src/Client.php
index 4e24b7f..5fd19b1 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -30,7 +30,7 @@ namespace Cepis;
  */
 final class Client
 {
-    public const VERSION = '0.1.0';
+    public const VERSION = '0.2.0';
 
     /**
      * Where the API lives, unless `baseUrl` says otherwise.
@@ -171,6 +171,12 @@ final class Client
      * the API's own message: the format already passed local validation, so
      * the server knows something this client does not.
      *
+     * A 404 is surfaced as {@see CepNotFoundException}, which may carry a
+     * {@see Faixa} naming the municipality the CEP would have belonged to. It
+     * is still a 404 either way: the `faixa` is context for the error, never an
+     * address, and a CEP that has one is just as absent from the DNE as one
+     * that does not.
+     *
      * @throws InvalidCepException the CEP is not 8 digits (no request is made).
      * @throws CepNotFoundException well-formed, but not in the database.
      * @throws RateLimitedException 429 after every attempt.
@@ -184,9 +190,13 @@ final class Client
         [$status, $body] = $this->request('/' . $number);
 
         if ($status === 404) {
-            throw new CepNotFoundException(
-                sprintf('CEP %s does not exist in the DNE database', $number),
-            );
+            $faixa = self::errorFaixa($body);
+            $message = sprintf('CEP %s does not exist in the DNE database', $number);
+            if ($faixa !== null) {
+                $message .= sprintf(' (the range covering it is %s)', $faixa->label());
+            }
+
+            throw new CepNotFoundException($message, $faixa);
         }
         if ($status === 400) {
             throw new InvalidCepException(
@@ -390,6 +400,24 @@ final class Client
     }
 
     /**
+     * Pull the optional `faixa` block out of a 404 body, or `null`.
+     *
+     * Nothing in here throws, by design. The body of a not-found is extra
+     * information on top of an answer the caller already has, so a truncated
+     * response, an HTML error page from a proxy or a `faixa` in a shape this
+     * release does not know must all end the same way: no `faixa`, and the same
+     * {@see CepNotFoundException} that would have been thrown anyway. Note the
+     * plain `json_decode` — {@see Client::decodeJsonObject()} is deliberately
+     * not used here, because its whole job is to throw.
+     */
+    private static function errorFaixa(string $body): ?Faixa
+    {
+        $data = json_decode($body, true);
+
+        return is_array($data) ? Faixa::fromArray($data['faixa'] ?? null) : null;
+    }
+
+    /**
      * Parse the `Retry-After` header in both RFC 9110 forms.
      *
      * It may arrive as a number of seconds (`"120"`) or as an HTTP date
diff --git a/src/Faixa.php b/src/Faixa.php
new file mode 100644
index 0000000..3f4be84
--- /dev/null
+++ b/src/Faixa.php
@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cepis;
+
+/**
+ * The municipality a CEP *would* belong to, when the CEP itself does not exist.
+ *
+ * It arrives on the 404 of `GET /{cep}` and is carried by
+ * {@see CepNotFoundException::$faixa}. **It is context for an error, never an
+ * address.** A CEP with a `faixa` is still a CEP that is not in the DNE: the
+ * answer to the lookup remains "does not exist".
+ *
+ * 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`,
+ * which 957 municipalities never received. Knowing that `25845000` "is Areal"
+ * is what lets you say *"we could not find that CEP in Areal/RJ"* instead of
+ * the useless *"CEP not found"*.
+ *
+ * {@see Faixa::$cep_ini} and {@see Faixa::$cep_fim} are the smallest and the
+ * largest CEP that **actually exist** in that municipality, not the bounds the
+ * Correios publish for it. The DNE's own start for Areal is `25845000` —
+ * exactly the CEP that just failed — and it is not `cep_ini` precisely because
+ * it does not exist.
+ *
+ * **The range is sparse, and the pair is not a list of valid CEPs.** Areal's
+ * 118 CEPs are spread across the ~4,900 numbers between `25845001` and
+ * `25849899`; the overwhelming majority of that interval is empty. That is what
+ * {@see Faixa::$ceps} is for. Never iterate the interval, never present it as
+ * "the CEPs of this city", and never conclude from `cep_ini <= x <= cep_fim`
+ * that `x` exists.
+ *
+ * The whole object is **omitted** by the API — never sent as null — when the
+ * CEP falls in a band no municipality owns, so absence is normal and
+ * {@see CepNotFoundException::$faixa} is null for it.
+ */
+final class Faixa
+{
+    /**
+     * Property names are the API's own JSON keys, `cep_ini` and `cep_fim`
+     * included. See {@see Address} for why they are not translated or
+     * camel-cased.
+     *
+     * @param string $cep_ini Smallest CEP that exists in the municipality, not
+     *     the start the Correios publish for it.
+     * @param string $cep_fim Largest CEP that exists in the municipality.
+     * @param int    $ceps How many CEPs the municipality actually has. Read it
+     *     together with the pair above: the interval is sparse, and this is the
+     *     only number that says how sparse.
+     */
+    public function __construct(
+        public readonly string $localidade,
+        public readonly string $uf = '',
+        public readonly string $estado = '',
+        public readonly string $regiao = '',
+        public readonly string $ibge = '',
+        public readonly string $cep_ini = '',
+        public readonly string $cep_fim = '',
+        public readonly int $ceps = 0,
+    ) {
+    }
+
+    /**
+     * Build from the decoded `faixa` block, or `null` when it is missing,
+     * empty or malformed.
+     *
+     * Deliberately forgiving. A `faixa` this client cannot read must never cost
+     * the caller the answer it came for: the CEP does not exist either way, and
+     * turning a clean not-found into a parse failure would trade a useful
+     * exception for a useless one. Only {@see Faixa::$localidade} is required —
+     * without a municipality name there is nothing to tell the user — and every
+     * other field falls back the way {@see Address} does, to an empty string or
+     * to zero.
+     */
+    public static function fromArray(mixed $data): ?self
+    {
+        if (!is_array($data) || $data === []) {
+            return null;
+        }
+
+        $localidade = self::asString($data['localidade'] ?? null);
+        if ($localidade === '') {
+            return null;
+        }
+
+        return new self(
+            localidade: $localidade,
+            uf: self::asString($data['uf'] ?? null),
+            estado: self::asString($data['estado'] ?? null),
+            regiao: self::asString($data['regiao'] ?? null),
+            ibge: self::asString($data['ibge'] ?? null),
+            cep_ini: self::asString($data['cep_ini'] ?? null),
+            cep_fim: self::asString($data['cep_fim'] ?? null),
+            ceps: self::asInt($data['ceps'] ?? null),
+        );
+    }
+
+    /**
+     * The municipality as you would show it to a person: `"Areal/RJ"`, or just
+     * `"Areal"` when the API sent no UF.
+     */
+    public function label(): string
+    {
+        return $this->uf === '' ? $this->localidade : $this->localidade . '/' . $this->uf;
+    }
+
+    /**
+     * @return array{
+     *     localidade: string, uf: string, estado: string, regiao: string,
+     *     ibge: string, cep_ini: string, cep_fim: string, ceps: int
+     * }
+     */
+    public function toArray(): array
+    {
+        return [
+            'localidade' => $this->localidade,
+            'uf' => $this->uf,
+            'estado' => $this->estado,
+            'regiao' => $this->regiao,
+            'ibge' => $this->ibge,
+            'cep_ini' => $this->cep_ini,
+            'cep_fim' => $this->cep_fim,
+            'ceps' => $this->ceps,
+        ];
+    }
+
+    private static function asString(mixed $value): string
+    {
+        return is_scalar($value) ? (string) $value : '';
+    }
+
+    private static function asInt(mixed $value): int
+    {
+        return is_numeric($value) ? (int) (float) $value : 0;
+    }
+}