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

A CEP that fails at the checkout is almost never a random number. It is
a shopper who knows perfectly well which town they live in and got a
digit wrong, most often by reaching for the -000 that 957 municipalities
never received. The API now names the municipality such a number would
have belonged to, in the body of its own 404, so the message can say
"that would be in Areal/RJ, which has CEPs from 25845-001 to 25849-899"
instead of leaving the shopper at a dead end with nothing to act on.

It stays an error. Nothing from it is written into a checkout field, on
either checkout and in either lookup mode: a CEP that does not exist has
no address, and filling one in from the municipality behind it means a
parcel delivered to the wrong town and a chargeback behind that. The one
module that reads the 404 body hands its callers a finished sentence and
never the data itself, so there is no shape in which it could leak into
a field later. The two CEPs quoted are the lowest and the highest that
really exist there, never a list and never a suggestion, because the
range is sparse enough that a number out of the middle of it would most
likely not exist either.

The widget correctly throws its 404 away without reading it, so the body
is fetched once more, on the miss path only and once per CEP. In proxy
mode PHP passes the municipality through with the 404 and caches it with
the miss, which is what keeps the two modes indistinguishable from the
browser. Anything missing or misshapen falls back to the message the
plugin has always shown.

1 files changed, 31 insertions, 1 deletions

diff --git a/README.md b/README.md
index be2a9f3..2233555 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,36 @@ message appears under the CEP field, styleable through
 Both fill billing and shipping. The cart block's shipping calculator is not
 covered.
 
+## When the CEP does not exist
+
+A CEP that fails at the checkout is rarely a random number. It is usually a
+shopper who knows perfectly well which town they live in and got a digit wrong
+— most often by trying the `-000`, which 957 municipalities never received.
+Areal/RJ, for one, answers from 25845-001 upwards and never at 25845-000.
+
+When the API says which municipality the number would have belonged to, so does
+the message:
+
+> CEP not found. This number would be in Areal/RJ, which has CEPs from
+> 25845-001 to 25849-899. Check the number.
+
+It is still an **error**. Nothing from it is ever written into a checkout field
+— not the city, not the state, nothing at all. A CEP that does not exist has no
+address, and filling one in from the municipality behind it means a parcel
+delivered to the wrong town.
+
+The two CEPs quoted are the lowest and the highest that really exist there, not
+a list of valid ones and not a suggestion. The range is sparse — 118 real CEPs
+across nearly five thousand numbers, in Areal's case — so a number picked out of
+the middle of it would most likely not exist either.
+
+When the API names no municipality, because the CEP falls in no range at all,
+the message is the one it has always been.
+
+Reading it costs one extra request, on the miss path only and once per CEP.
+Both checkouts do it and both lookup modes support it: with **This site**
+selected the municipality is passed through with the 404 and cached with it.
+
 Verified on WordPress 7.0.2, WooCommerce 10.9.4, PHP 8.3. `Requires at least`
 is declared as 6.9 because that is what WooCommerce 10.x itself requires; older
 WordPress was not tested.
@@ -116,7 +146,7 @@ make            # list the targets
 make test       # stand a store up in Docker and drive the checkout in Chromium
 make lint       # php -l, prettier --check, and phpcs when installed
 make format     # apply prettier (writes)
-make build      # produce dist/cepis-woocommerce-0.1.0.zip
+make build      # produce dist/cepis-woocommerce-0.2.0.zip
 make check      # lint, then test, then build
 make clean      # remove build output and throw the test containers away
 ```