Name the municipality behind a CEP that does not existHEADv0.2.0main

A CEP lookup that fails is rarely a random number: it is usually someone
who knows the city and guessed the last digits, most often the -000 that
957 municipalities never received. The API now answers those 404s with a
`faixa` naming the municipality the number would have belonged to and the
first and last CEP that really exist there, so the shopper can be told
"esse número seria de Areal/RJ" instead of a bare "não encontrado".

It stays an error. The address does not exist, so no field is filled from
`faixa` — quietly writing the city of a CEP that does not exist would
produce a wrong address, which is worse than an empty form. Only the
wording of the message changes. The range is sparse (Areal has 118 CEPs
over some 4,900 numbers), so it is shown as a hint of where to look, never
as a list to pick from.

Parsing is defensive throughout: a body that is not JSON, a `faixa` that is
not an object, a missing localidade or uf, a malformed range — each falls
back to the message shipped before, and none of it can throw.

1 files changed, 67 insertions, 11 deletions

diff --git a/README.md b/README.md
index 242859a..0489a3d 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ widget fills the street, neighbourhood, city and state fields you point it
 at. Official Correios data (DNE).
 
 One `<script>` tag, no build step, no framework, no dependencies.
-**3.3 KB minified and gzipped** (7.7 KB minified, 7859 bytes).
+**3.7 KB minified and gzipped** (8.8 KB minified, 9042 bytes).
 
 ```html
 <script src="cepis-autofill.js"></script>
@@ -134,15 +134,16 @@ to render nothing and drive your own UI from `onStatus`.
 Every failure has its own message, in Portuguese, and reaches both the
 status region and `onError`:
 
-| `error.code`       | message                                                                   | worth retrying? |
-| ------------------ | ------------------------------------------------------------------------- | --------------- |
-| `invalid`          | CEP inválido. Digite os 8 dígitos.                                        | no              |
-| `not_found`        | CEP não encontrado. Confira o número ou preencha o endereço manualmente.  | no              |
-| `rate_limited`     | Muitas consultas em pouco tempo. Aguarde alguns segundos e tente de novo. | later           |
-| `server`           | O serviço de CEP está indisponível. Preencha o endereço manualmente.      | later           |
-| `network`          | Não foi possível consultar o CEP. Verifique sua conexão e tente de novo.  | later           |
-| `timeout`          | A consulta do CEP demorou demais. Tente de novo ou preencha manualmente.  | later           |
-| `invalid_response` | Resposta inesperada do serviço de CEP. Preencha o endereço manualmente.   | probably not    |
+| `error.code`       | message                                                                                   | worth retrying? |
+| ------------------ | ----------------------------------------------------------------------------------------- | --------------- |
+| `invalid`          | CEP inválido. Digite os 8 dígitos.                                                        | no              |
+| `not_found`        | CEP não encontrado. Confira o número ou preencha o endereço manualmente.                  | no              |
+| `not_found` + city | CEP não encontrado. Esse número seria de Areal/RJ, que tem CEPs de 25845-001 a 25849-899. | no              |
+| `rate_limited`     | Muitas consultas em pouco tempo. Aguarde alguns segundos e tente de novo.                 | later           |
+| `server`           | O serviço de CEP está indisponível. Preencha o endereço manualmente.                      | later           |
+| `network`          | Não foi possível consultar o CEP. Verifique sua conexão e tente de novo.                  | later           |
+| `timeout`          | A consulta do CEP demorou demais. Tente de novo ou preencha manualmente.                  | later           |
+| `invalid_response` | Resposta inesperada do serviço de CEP. Preencha o endereço manualmente.                   | probably not    |
 
 Override any of them with `messages`:
 
@@ -156,6 +157,59 @@ CepisAutofill.attach({
 
 `rate_limited` carries `retryAfterMs` and `server` carries `status`.
 
+### When the CEP does not exist, but the city does
+
+A CEP that fails is rarely a random number. It is usually someone who knows
+the city and guessed the last digits — most often the `-000` that 957
+municipalities never received. Areal/RJ, for one, answers from `25845-001`
+up, and never at `25845-000`.
+
+So when the API can tell which municipality the number would have belonged
+to, the message says it:
+
+> CEP não encontrado. Esse número seria de Areal/RJ, que tem CEPs de
+> 25845-001 a 25849-899.
+
+**Nothing is filled in.** This is still a `not_found`: the address does not
+exist, so the widget writes no field — not the city, not the state, nothing.
+Filling the city from a CEP that does not exist would quietly produce a wrong
+address, which is worse than an empty form. Only the wording of the message
+changes.
+
+The range is not a list of valid CEPs either. `cep_ini` and `cep_fim` are the
+lowest and the highest CEP that really exist in that municipality, and what
+lies between them is sparse — Areal has 118 CEPs spread over some 4,900
+numbers. Show it as a hint of where to look; never suggest a CEP from inside
+it.
+
+Where the API says nothing about a municipality, the plain
+`CEP não encontrado…` message stands, exactly as before. The same goes for a
+reply this widget cannot make sense of.
+
+Two extra entries in `messages` carry the wording, with `{localidade}`,
+`{uf}`, `{cep_ini}` and `{cep_fim}` filled in:
+
+| key                    | used when                                   |
+| ---------------------- | ------------------------------------------- |
+| `not_found_city_range` | the municipality and its first and last CEP |
+| `not_found_city`       | the municipality, but no usable range       |
+
+```js
+CepisAutofill.attach({
+  cep: "#cep",
+  localidade: "#cidade",
+  messages: {
+    not_found_city_range:
+      "Esse CEP não existe. Em {localidade}/{uf} eles vão de {cep_ini} a {cep_fim}.",
+  },
+});
+```
+
+`onError` gets the whole thing as `error.faixa` — `localidade`, `uf`, and
+whichever of `estado`, `regiao`, `ibge`, `cep_ini`, `cep_fim` and `ceps` the
+API sent — for a richer UI of your own. It is absent, never null, when there
+is no municipality to name.
+
 ### Looking a CEP up yourself
 
 `CepisAutofill.lookup` is the request layer on its own — same cache, same
@@ -169,7 +223,9 @@ address.uf; // "SP"
 
 It resolves to the API's own JSON: Portuguese field names, empty strings
 rather than nulls, and `geo` present only for the roughly 57% of CEPs that
-have a coordinate.
+have a coordinate. It rejects with a `CepisAutofillError`, whose `faixa` —
+when the CEP does not exist but its municipality does — is
+[described above](#when-the-cep-does-not-exist-but-the-city-does).
 
 ## Mapping your platform's fields