1 files changed, 90 insertions, 0 deletions
diff --git a/src/root.zig b/src/root.zig
new file mode 100644
index 0000000..0a83c5c
--- /dev/null
+++ b/src/root.zig
@@ -0,0 +1,90 @@
+//! Zig client for the public CEP API at [cep.is](https://cep.is). Official
+//! Correios data (DNE), refreshed every two weeks.
+//!
+//! Zig has no ambient allocator and, since 0.16, no ambient I/O either, so
+//! there is no module-level `lookup`: everything goes through a `Client` you
+//! build with both. That is one extra line and it is the honest one.
+//!
+//! ```zig
+//! const std = @import("std");
+//! const cepis = @import("cepis");
+//!
+//! pub fn main() !void {
+//!     var debug: std.heap.DebugAllocator(.{}) = .init;
+//!     defer _ = debug.deinit();
+//!     const gpa = debug.allocator();
+//!
+//!     var threaded: std.Io.Threaded = .init(gpa, .{});
+//!     defer threaded.deinit();
+//!
+//!     var client: cepis.Client = try .init(gpa, threaded.io(), .{});
+//!     defer client.deinit();
+//!
+//!     var address = try client.lookup("01001-000", .{});
+//!     defer address.deinit(gpa);
+//!
+//!     std.debug.print("{s} {s}\n", .{ address.localidade, address.uf });
+//! }
+//! ```
+//!
+//! Pointing at a local instance (the API repo brings one up with `just up`)
+//! is a matter of `base_url`:
+//!
+//! ```zig
+//! var client: cepis.Client = try .init(gpa, io, .{ .base_url = "http://localhost:8080" });
+//! ```
+//!
+//! Errors are one set, split by decision — whether retrying helps or not:
+//!
+//! ```zig
+//! var diag: cepis.Diagnostics = .{};
+//! const address = client.lookup(cep_from_form, .{ .diagnostics = &diag }) catch |err| switch (err) {
+//!     error.NotFound => return askForAnotherCep(),
+//!     else => if (cepis.isRetriable(err)) return reschedule() else return err,
+//! };
+//! ```
+//!
+//! 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 value.
+//!
+//! Every value this library returns owns its memory and has a `deinit` taking
+//! the allocator the `Client` was built with. Each type documents exactly what
+//! it owns.
+
+const client = @import("client.zig");
+const errors = @import("errors.zig");
+const model = @import("model.zig");
+
+pub const Client = client.Client;
+pub const Config = client.Config;
+pub const CallOptions = client.CallOptions;
+pub const InitError = client.InitError;
+pub const normalizeCep = client.normalizeCep;
+pub const freeAddresses = client.freeAddresses;
+
+pub const default_url = client.default_url;
+pub const default_user_agent = client.default_user_agent;
+pub const max_batch = client.max_batch;
+pub const retriable_status = client.retriable_status;
+
+/// The version of this library, as sent in the `User-Agent`.
+pub const version = client.version;
+
+pub const Error = errors.Error;
+pub const CepisError = errors.CepisError;
+pub const Diagnostics = errors.Diagnostics;
+pub const isRetriable = errors.isRetriable;
+
+pub const Address = model.Address;
+pub const Geo = model.Geo;
+pub const Health = model.Health;
+
+test {
+    @import("std").testing.refAllDecls(@This());
+    _ = @import("csv.zig");
+    _ = @import("retry.zig");
+    _ = client;
+    _ = errors;
+    _ = model;
+}