Pure address query normalisation and hashing — no I/O, no side effects.

Pure geographic math functions — no I/O, no side effects.

Protocol definitions for the geo module.

FC/IS rule: protocols are interfaces — no implementation here.
Adapters (shell layer) implement these protocols.

Malli validation schemas for the geo module.

Google Maps Geocoding API adapter.

Requires a valid Google Maps API key with the Geocoding API enabled.

Usage:
  (def adapter (create-google-adapter {:api-key "AIza..."}))
  (geocode adapter {:address "Damrak 1, Amsterdam"})

Mapbox Geocoding API adapter.

Requires a valid Mapbox access token.
Note: Mapbox returns coordinates as [longitude, latitude] (GeoJSON order).

Usage:
  (def adapter (create-mapbox-adapter {:api-key "pk.eyJ1..."}))
  (geocode adapter {:address "Damrak 1, Amsterdam"})

OpenStreetMap Nominatim geocoding adapter.

Rate limit: 1 request per second (OSM usage policy requires this).
No API key required. A descriptive User-Agent header is mandatory.

Usage:
  (def adapter (create-nominatim-adapter {:user-agent "MyApp/1.0 (contact@example.com)"}))
  (geocode adapter {:postcode "1012 JS" :city "Amsterdam"})

DB-backed geocoding cache implementing GeoCacheProtocol.

Uses a `geo_cache` table with a SHA-256 address hash as primary key.
Run the migration in resources/wagoe/geo/migrations/001-geo-cache.sql
before using this component.

TTL is enforced at lookup time by comparing `created_at` to `NOW() - cache-ttl`.

Integrant wiring for the geo module.

Config key: :wagoe/geo-service

Example (single provider, no caching):
  :wagoe/geo-service
  {:provider  :openstreetmap
   :user-agent "MyApp/1.0 (contact@example.com)"}

Example (Google with DB cache):
  :wagoe/geo-service
  {:provider   :google
   :api-key    #env WAG_GEO_API_KEY
   :cache-ttl  86400
   :db         #ig/ref :wagoe/db}

Example (fallback chain):
  :wagoe/geo-service
  {:provider   [:openstreetmap :google]
   :api-key    #env WAG_GEO_API_KEY
   :cache-ttl  86400
   :db         #ig/ref :wagoe/db}

Public API for the geo module.

Entry points:
- geocode!         — forward geocoding with cache-first lookup
- reverse-geocode! — reverse geocoding (no caching, coordinates not hashed)
- distance         — pure Haversine distance delegate

`geocode!` flow:
  1. Compute query-hash from the AddressQuery
  2. If a cache is configured, attempt cache-lookup
  3. On cache miss, iterate providers until one returns a result
  4. Cache-store! the result (if cache configured and result non-nil)
  5. Return result or nil