Report the municipality a missing CEP would have belonged toHEADv0.2.0main

A CEP that fails a lookup is rarely a random number: it is usually someone
who knows the city and guessed, and the classic guess is the -000 that 957
municipalities never received. The API now answers those 404s with a faixa
naming the municipality that owns the band the number fell into, which is
the difference between telling a user "invalid CEP" and "no such CEP in
Areal/RJ".

It is context for an error and never an address, so it rides on the
cepis_not_found condition instead of turning the failure into a success,
and cep_ini/cep_fim are the endpoints that exist rather than the range the
Correios publish - the interval between them is sparse, which is what ceps
counts. Parsing is deliberately unable to signal: a faixa that is null, an
array, a string or half a body leaves a clean not-found behind, because the
caller asked for the CEP, not for the decoration on its absence.

1 files changed, 28 insertions, 2 deletions

diff --git a/R/conditions.R b/R/conditions.R
index 1eebe5b..7cdb45b 100644
--- a/R/conditions.R
+++ b/R/conditions.R
@@ -38,6 +38,32 @@
 #' proxy, an HTML error page. Useful as a diagnosis: the problem is not in
 #' your code.
 #'
+#' @section What cepis_not_found carries:
+#' `cep`, the 8 digits as they went to the API, and `faixa`: a [cepis_faixa]
+#' naming the municipality that owns the band of numbers the CEP fell into,
+#' or `NULL` when it fell in a band nobody owns. The API omits it, it never
+#' sends null, so `NULL` here is the same statement.
+#'
+#' It changes nothing about the answer — the CEP still does not exist, and a
+#' `faixa` is not an address — but it is usually the difference between
+#' telling someone "invalid CEP" and telling them "no such CEP in Areal/RJ":
+#'
+#' ```r
+#' tryCatch(
+#'   cep_lookup("25845000"),
+#'   cepis_not_found = function(e) {
+#'     if (is.null(e$faixa)) {
+#'       "no such CEP"
+#'     } else {
+#'       paste0("no such CEP in ", e$faixa$localidade, "/", e$faixa$uf)
+#'     }
+#'   }
+#' )
+#' ```
+#'
+#' The CEP that failed above is the DNE's own first number for Areal, and it
+#' is the shape of guess this field is for.
+#'
 #' @name cepis_conditions
 NULL
 
@@ -52,8 +78,8 @@ invalid_cep_error <- function(message, value = NULL) {
   cepis_condition("cepis_invalid_cep", message, value = value)
 }
 
-not_found_error <- function(message, cep = NULL) {
-  cepis_condition("cepis_not_found", message, cep = cep)
+not_found_error <- function(message, cep = NULL, faixa = NULL) {
+  cepis_condition("cepis_not_found", message, cep = cep, faixa = faixa)
 }
 
 rate_limited_error <- function(message, retry_after = NULL) {