geocoding

type CacheConfig struct {
	// L1MaxSize is the maximum number of entries in the in-memory LRU cache.
	// Default: 10000
	L1MaxSize int

	// L1TTL is the time-to-live for L1 cache entries.
	// Default: 24h
	L1TTL time.Duration

	// L2Enabled enables the database-backed persistent cache.
	// Requires a database connection.
	L2Enabled bool
}

type Config struct {
	// Enabled controls whether geocoding is active.
	Enabled bool

	// Provider configuration for the geocoding API.
	Provider ProviderConfig

	// RateLimit configuration to control API request rates.
	RateLimit RateLimitConfig

	// Cache configuration for L1 (in-memory) and L2 (database) caching.
	Cache CacheConfig
}

type Coordinates struct {
	Latitude  float64
	Longitude float64
	// Accuracy indicates the precision level of the geocoding result.
	// Possible values: "rooftop", "street", "city", "state", "country", "approximate"
	Accuracy string
}

type Geocoder interface {
	// Geocode converts an address to geographic coordinates.
	// Returns nil coordinates if the address cannot be geocoded.
	Geocode(ctx context.Context, address search.Address) (*Coordinates, error)

	// Name returns the provider name for logging and metrics.
	Name() string
}

type GoogleGeocoder struct {
	// contains filtered or unexported fields
}

type NoOpGeocoder struct{}

type NominatimGeocoder struct {
	// contains filtered or unexported fields
}

type OpenCageGeocoder struct {
	// contains filtered or unexported fields
}

type ProviderConfig struct {
	// Name of the provider: "opencage", "google", or "nominatim"
	Name string

	// APIKey for authentication with the provider.
	// Can be set via GEOCODING_API_KEY environment variable.
	APIKey string

	// BaseURL allows overriding the default API endpoint.
	// Useful for self-hosted Nominatim instances.
	BaseURL string

	// Timeout for API requests. Default: 10s
	Timeout time.Duration
}

type RateLimitConfig struct {
	// RequestsPerSecond defines the sustained request rate.
	// Free tier typically allows 1/sec, paid tiers allow up to 40/sec.
	RequestsPerSecond float64

	// Burst allows temporary exceeding of the rate limit.
	Burst int
}

type Repository interface {
	// Get retrieves coordinates from the cache by key.
	// Returns nil if not found.
	Get(ctx context.Context, cacheKey string) (*Coordinates, error)

	// Set stores coordinates in the cache.
	Set(ctx context.Context, cacheKey string, coords *Coordinates) error
}

type Service struct {
	// contains filtered or unexported fields
}