Initial importv0.1.0

1 files changed, 100 insertions, 0 deletions

diff --git a/src/package.lisp b/src/package.lisp
new file mode 100644
index 0000000..20d6f32
--- /dev/null
+++ b/src/package.lisp
@@ -0,0 +1,100 @@
+(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
+
+   #: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))