1 files changed, 47 insertions, 0 deletions
diff --git a/include/cepis/cepis.hpp b/include/cepis/cepis.hpp
new file mode 100644
index 0000000..4ac3f1f
--- /dev/null
+++ b/include/cepis/cepis.hpp
@@ -0,0 +1,47 @@
+#ifndef CEPIS_CEPIS_HPP
+#define CEPIS_CEPIS_HPP
+
+/// C++ client for the public CEP API at https://cep.is — official Correios
+/// data (DNE), refreshed every two weeks.
+///
+/// Quick use — for a script, the free functions are enough:
+///
+/// ```cpp
+/// #include <cepis/cepis.hpp>
+///
+/// const cepis::Address a = cepis::lookup("01001-000");
+/// std::cout << a.localidade << ' ' << a.uf << '\n';   // São Paulo SP
+/// ```
+///
+/// In an application, build a `cepis::Client` once and reuse it:
+///
+/// ```cpp
+/// cepis::Config config;
+/// config.base_url = "http://localhost:8080";
+/// config.timeout = std::chrono::seconds{5};
+/// const cepis::Client client(config);
+/// const cepis::Address a = client.lookup("01001000");
+/// ```
+///
+/// Errors are explicit and split by decision — whether retrying helps or not:
+///
+/// ```cpp
+/// try {
+///   const cepis::Address a = cepis::lookup(cep_from_form);
+/// } catch (const cepis::CepNotFound&) {
+///   // the CEP does not exist: ask the user for another
+/// } catch (const cepis::Error&) {
+///   // network, server, rate limit: 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.
+
+#include "cepis/client.hpp"
+#include "cepis/errors.hpp"
+#include "cepis/json.hpp"
+#include "cepis/models.hpp"
+
+#endif  // CEPIS_CEPIS_HPP