mailwoman_client/lib.rs
1//! Typed Rust clients for Mailwoman's four HTTP surfaces — the three drop-in geocoding APIs
2//! plus the native `/v1/*` surface `mailwoman serve` ships.
3//!
4//! Each submodule is generated at compile time by [`progenitor`]'s `generate_api!` proc-macro
5//! from the OpenAPI 3.0.3 document (the "diet" flavor — progenitor's `openapiv3` dependency
6//! only understands 3.0.x) vendored under `openapi/` — nothing here is hand-written except the
7//! thin default-`base_url` constructors below. Regenerate with `mailwoman clients generate`;
8//! there is no code to hand-edit. See `examples/basic.rs` for a runnable call.
9
10/// Photon-compatible autocomplete / reverse geocoding client (`/api`, `/reverse`).
11pub mod photon {
12 progenitor::generate_api!("openapi/photon.json");
13}
14
15/// Nominatim-compatible geocoding client (`/search`, `/reverse`, `/lookup`, `/status`).
16pub mod nominatim {
17 progenitor::generate_api!("openapi/nominatim.json");
18}
19
20/// libpostal-compatible parse / expand client (`/parse`, `/expand`).
21pub mod libpostal {
22 progenitor::generate_api!("openapi/libpostal.json");
23}
24
25/// The native Mailwoman client (`/v1/parse`, `/v1/geocode`, `/v1/batch`, `/v1/resolve`, `/v1/format`).
26pub mod mailwoman {
27 progenitor::generate_api!("openapi/mailwoman.json");
28}
29
30/// The hosted public Photon trial endpoint (conservative rate limits). Only Photon has a
31/// hosted trial; the other three surfaces are self-host only.
32pub const PHOTON_HOSTED_BASE_URL: &str = "https://photon.sister.software";
33
34/// Default local `npx @mailwoman/photon serve` base URL.
35pub const PHOTON_LOCAL_BASE_URL: &str = "http://127.0.0.1:2322";
36/// Default local `npx @mailwoman/nominatim serve` base URL.
37pub const NOMINATIM_LOCAL_BASE_URL: &str = "http://127.0.0.1:8080";
38/// Default local `npx @mailwoman/libpostal serve` base URL.
39pub const LIBPOSTAL_LOCAL_BASE_URL: &str = "http://127.0.0.1:8081";
40/// Default local `mailwoman serve` base URL.
41pub const MAILWOMAN_LOCAL_BASE_URL: &str = "http://127.0.0.1:3000";
42
43/// A Photon client pointed at the hosted public trial endpoint ([`PHOTON_HOSTED_BASE_URL`]).
44pub fn photon_hosted() -> photon::Client {
45 photon::Client::new(PHOTON_HOSTED_BASE_URL)
46}
47
48/// A Photon client pointed at a local `serve` server ([`PHOTON_LOCAL_BASE_URL`]).
49pub fn photon_local() -> photon::Client {
50 photon::Client::new(PHOTON_LOCAL_BASE_URL)
51}
52
53/// A Nominatim client pointed at a local `serve` server ([`NOMINATIM_LOCAL_BASE_URL`]).
54pub fn nominatim_local() -> nominatim::Client {
55 nominatim::Client::new(NOMINATIM_LOCAL_BASE_URL)
56}
57
58/// A libpostal client pointed at a local `serve` server ([`LIBPOSTAL_LOCAL_BASE_URL`]).
59pub fn libpostal_local() -> libpostal::Client {
60 libpostal::Client::new(LIBPOSTAL_LOCAL_BASE_URL)
61}
62
63/// A Mailwoman client pointed at a local `mailwoman serve` server ([`MAILWOMAN_LOCAL_BASE_URL`]).
64pub fn mailwoman_local() -> mailwoman::Client {
65 mailwoman::Client::new(MAILWOMAN_LOCAL_BASE_URL)
66}