(defpackage #:cepis
  (:use #:common-lisp)
  (:documentation
   "Common Lisp client for the public CEP API at https://cep.is.

Quick use — the functions take the client as a keyword argument, defaulting
to the shared client in `*client*':

    (cepis:lookup \"01001-000\")

In an application, build a client once and pass it explicitly:

    (defvar *cep* (cepis:make-client :timeout 5 :total-timeout 15))
    (cepis:lookup \"01001000\" :client *cep*)

Pointing at a local instance (the API repo brings one up with `just up'):

    (cepis:make-client :base-url \"http://localhost:8080\")

Errors are conditions split by the decision the caller has to make — whether
retrying helps or not. Everything derives from `cepis-error':

    (handler-case (cepis:lookup cep)
      (cepis:cep-not-found () :ask-again)
      (cepis:cepis-error () :retry-later))

Note on field names: the API surface is English, but the data fields keep the
API's own Portuguese names (`logradouro', `bairro', `localidade'). What you
read in the JSON is what you access on the object; the only adaptation is
Lisp's hyphenation, so the JSON `raio_m' is the slot `raio-m', read with
`geo-raio-m'.")
  (:export
   #:+default-url+
   #:+max-batch+
   #:+version+

   #:cepis-error
   #:invalid-cep
   #:cep-not-found
   #:network-error
   #:server-error
   #:rate-limited
   #:invalid-response
   #:error-message
   #:server-error-status
   #:rate-limited-retry-after
   #:cep-not-found-faixa

   #:faixa
   #:faixa-p
   #:make-faixa
   #:faixa-localidade
   #:faixa-uf
   #:faixa-estado
   #:faixa-regiao
   #:faixa-ibge
   #:faixa-cep-ini
   #:faixa-cep-fim
   #:faixa-ceps

   #:geo
   #:geo-p
   #:make-geo
   #:geo-lat
   #:geo-lon
   #:geo-raio-m
   #:geo-precisao
   #:geo-precise-p

   #:address
   #:address-p
   #:make-address
   #:address-cep
   #:address-logradouro
   #:address-complemento
   #:address-unidade
   #:address-bairro
   #:address-localidade
   #:address-uf
   #:address-estado
   #:address-regiao
   #:address-ibge
   #:address-gia
   #:address-ddd
   #:address-siafi
   #:address-geo
   #:address-raw
   #:address-formatted-cep

   #:health
   #:health-p
   #:make-health
   #:health-status
   #:health-dne
   #:health-ceps
   #:health-geo
   #:health-base-gerada-em
   #:health-ok-p

   #:client
   #:make-client
   #:client-base-url
   #:client-timeout
   #:client-max-attempts
   #:client-backoff-base
   #:client-backoff-max
   #:client-total-timeout
   #:client-user-agent
   #:*client*

   #:normalize-cep
   #:lookup
   #:lookup-many))