@proximap/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,973 @@
+/**
+ * Domain model for proximap. These types are provider-agnostic: OpenStreetMap
+ * is the default backend, but anything implementing {@link GeocodingProvider}
+ * and {@link PlacesProvider} can drive the same pipeline.
+ */
+/** A WGS84 latitude/longitude coordinate, in decimal degrees. */
+interface LatLng {
+    lat: number;
+    lng: number;
+}
+/**
+ * Normalized, top-level categories every POI is bucketed into. This is the
+ * single source of truth — {@link Category} is derived from it.
+ */
+declare const CATEGORIES: readonly ["food", "grocery", "shopping", "healthcare", "education", "finance", "transport", "fuel", "parking", "accommodation", "leisure", "tourism", "worship", "public_service", "utility", "other"];
+/** A normalized amenity/utility category. */
+type Category = (typeof CATEGORIES)[number];
+/**
+ * A single OSM tag selector, e.g. `{ key: 'amenity', value: 'cafe' }` or
+ * `{ key: 'cuisine', value: 'coffee_shop', regex: true }`. An omitted `value`
+ * matches the mere presence of the key.
+ */
+interface CategorySelector {
+    key: string;
+    value?: string;
+    /** Treat `value` as an Overpass regular expression (the `~` operator). */
+    regex?: boolean;
+}
+/** A geocoded location — the resolved origin of a search. */
+interface Place {
+    /** Best-effort short name, e.g. "Eiffel Tower". */
+    name: string;
+    /** Full human-readable label from the geocoder. */
+    displayName: string;
+    location: LatLng;
+    /** Geocoder-provided class/type, e.g. "tourism" or "city". */
+    kind?: string;
+    /** Bounding box as [south, north, west, east], if provided. */
+    boundingBox?: [number, number, number, number];
+    /** Identifier of the provider that produced this result, e.g. "nominatim". */
+    source: string;
+    /** Raw provider payload, for advanced consumers. */
+    raw?: unknown;
+}
+/** A point of interest: an amenity, utility, shop, or similar feature. */
+interface Poi {
+    /** Stable identifier, e.g. "node/123" or "way/456". */
+    id: string;
+    name?: string;
+    category: Category;
+    /** The specific source value behind the category, e.g. "restaurant". */
+    kind?: string;
+    location: LatLng;
+    /** Original source tags/attributes (e.g. OSM tags). */
+    tags: Record<string, string>;
+    source: string;
+    /** Share of expected tags present for this category, in [0, 1]. */
+    completeness?: number;
+    /** Best-effort last-verified date (YYYY-MM-DD) from check_date/survey/meta. */
+    lastVerified?: string;
+}
+/** Whether a place is open at a given time: known states or "not enough data". */
+type OpenState = 'open' | 'closed' | 'unknown';
+/** A {@link Poi} enriched with distance from the search origin and a rank. */
+interface RankedPoi extends Poi {
+    /** Great-circle distance from the origin, in metres. */
+    distanceMeters: number;
+    /** Composite score in [0, 1]; higher is better. */
+    score: number;
+    /** 1-based position after ranking. */
+    rank: number;
+    /** Open/closed/unknown at the queried time — set only when `open` was requested. */
+    openState?: OpenState;
+    /** ISO 8601 timestamp of the next open/closed transition, when computable. */
+    nextChange?: string;
+    /** Travel duration from the origin in seconds — set only when ranking by travel time. */
+    travelSeconds?: number;
+    /** Travel distance from the origin in metres — set only when ranking by travel time. */
+    travelMeters?: number;
+    /** A short human-readable reason for this rank — set only when `explain` is on. */
+    rankingReason?: string;
+}
+/** Options for a geocoding lookup. */
+interface GeocodeOptions {
+    /** Maximum number of candidates to return. */
+    limit?: number;
+    /** Preferred result language, e.g. "en". */
+    language?: string;
+    signal?: AbortSignal;
+}
+/** Resolves place names/addresses to coordinates (and optionally back). */
+interface GeocodingProvider {
+    readonly name: string;
+    geocode(query: string, options?: GeocodeOptions): Promise<Place[]>;
+    reverse?(location: LatLng, options?: GeocodeOptions): Promise<Place | null>;
+}
+/** Options for a nearby-places search. */
+interface NearbyOptions {
+    /** Search radius from the center, in metres. */
+    radiusMeters: number;
+    /** Restrict results to these normalized categories (post-classification). */
+    categories?: Category[];
+    /**
+     * Tag selectors that drive a targeted query (and define what to keep). When
+     * set, the provider should fetch only matching features instead of the broad
+     * default set. Takes precedence over `categories` for query construction.
+     */
+    selectors?: CategorySelector[];
+    /** Upper bound on POIs fetched from the provider. */
+    limit?: number;
+    signal?: AbortSignal;
+}
+/** Finds points of interest around a coordinate. */
+interface PlacesProvider {
+    readonly name: string;
+    findNearby(center: LatLng, options: NearbyOptions): Promise<Poi[]>;
+}
+
+/**
+ * Great-circle distance between two coordinates, in metres, via the haversine
+ * formula. Accurate to within ~0.5% — more than enough to rank nearby places.
+ */
+declare function haversineMeters(a: LatLng, b: LatLng): number;
+/** Format a metre distance as a compact human string ("125 m", "1.4 km"). */
+declare function formatDistance(meters: number): string;
+/** Format a second duration as a compact human string ("8 min", "1 h 5 min"). */
+declare function formatDuration(seconds: number): string;
+/**
+ * Parse a "lat,lng" string (decimal degrees) into a {@link LatLng}, or return
+ * null when the input is not a valid, in-range coordinate pair.
+ */
+declare function parseCoordinates(input: string): LatLng | null;
+
+interface Categorization {
+    category: Category;
+    /** The specific source value that drove the classification, if any. */
+    kind?: string;
+}
+/**
+ * Classify a set of OSM tags into a normalized {@link Category}. Keys are
+ * checked in priority order; a present-but-unknown key falls back to 'other'
+ * while preserving its value as `kind`.
+ */
+declare function categorize(tags: Record<string, string>): Categorization;
+/** Human-friendly display labels for each category. */
+declare const CATEGORY_LABELS: Record<Category, string>;
+/** Type guard: is `value` one of the known {@link Category} names? */
+declare function isCategory(value: string): value is Category;
+
+interface ResolvedCategories {
+    /** Deduplicated selectors for all recognized terms. */
+    selectors: CategorySelector[];
+    /** Recognized terms with their canonical name and category. */
+    matched: {
+        input: string;
+        term: string;
+        category: Category;
+    }[];
+    /** Terms that could not be resolved. */
+    unknown: string[];
+}
+/** Resolve a list of natural-language terms (or category names) to selectors. */
+declare function resolveCategories(terms: readonly string[]): ResolvedCategories;
+/** Is `term` a known category or synonym? */
+declare function isKnownTerm(term: string): boolean;
+/** All canonical query terms with their top-level category. */
+declare function categoryVocabulary(): {
+    term: string;
+    category: Category;
+}[];
+/** Suggest known terms for an unrecognized input (typos, partial matches). */
+declare function suggestCategories(term: string, limit?: number): string[];
+/** Render a selector as an Overpass tag filter, e.g. `["amenity"="cafe"]`. */
+declare function selectorToOverpassFilter(selector: CategorySelector): string;
+/** Does a tag set satisfy a single selector? */
+declare function tagsMatchSelector(tags: Record<string, string>, selector: CategorySelector): boolean;
+/** Does a tag set satisfy any of the selectors? */
+declare function tagsMatchAnySelector(tags: Record<string, string>, selectors: readonly CategorySelector[]): boolean;
+
+/** Fraction of a category's expected tags that are present, in [0, 1]. */
+declare function completenessOf(category: Category, tags: Record<string, string>): number;
+/**
+ * Best-effort "last verified" date (YYYY-MM-DD): an explicit survey/check_date
+ * tag if present, else the element's last-edit timestamp.
+ */
+declare function lastVerifiedOf(tags: Record<string, string>, timestamp?: string): string | undefined;
+/**
+ * Collapse duplicate representations of the same POI (e.g. a node and a building
+ * way) into one, keeping the richer entry. Order of first appearance is kept.
+ */
+declare function dedupePois(pois: Poi[]): Poi[];
+
+interface OpeningEvaluation {
+    state: OpenState;
+    /** ISO 8601 timestamp of the next open/closed transition, when computable. */
+    nextChange?: string;
+}
+/**
+ * A small, dependency-free evaluator for the common subset of the OSM
+ * `opening_hours` grammar: weekday ranges/lists, multiple time ranges,
+ * overnight (midnight-wrapping) ranges, `24/7`, and `off`/`closed`. Public- and
+ * school-holiday rules (`PH`/`SH`) are skipped (no holiday calendar), so a
+ * normal day still evaluates from the regular rules.
+ *
+ * Anything outside this subset — `sunrise`/`sunset`, month/date/week selectors,
+ * open-ended `08:00+`, etc. — yields `unknown` rather than a guess. A missing or
+ * empty value is `unknown` too. We never assert a state we can't justify.
+ *
+ * Times are read from the local-time fields of `when`; to evaluate a POI in
+ * another timezone, pass a `when` already shifted into that zone.
+ */
+declare function isOpenAt(openingHours: string | undefined, when: Date): OpeningEvaluation;
+
+/**
+ * Minimal JSON-over-HTTP helper built on the platform `fetch`. Keeps the core
+ * dependency-free while handling timeouts, cancellation, retries with backoff,
+ * optional caching, and consistent error surfacing across providers.
+ */
+/** Default contact identifier sent to OSM services; override per provider. */
+declare const DEFAULT_USER_AGENT = "proximap/0.1 (+https://github.com/AmeyaBorkar/proximap)";
+/** A pluggable response cache. Values are parsed JSON. */
+interface RequestCache {
+    get(key: string): Promise<unknown> | unknown;
+    set(key: string, value: unknown): Promise<void> | void;
+}
+/** A process-local, unbounded cache. Opt-in — pass it to a provider to enable. */
+declare class InMemoryCache implements RequestCache {
+    private readonly store;
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+}
+/**
+ * Serializes calls so that consecutive `acquire()`s are spaced at least
+ * `minIntervalMs` apart — for honouring usage policies (e.g. Nominatim's 1 req/s).
+ */
+declare class RateLimiter {
+    private readonly minIntervalMs;
+    private last;
+    private chain;
+    constructor(minIntervalMs: number);
+    acquire(): Promise<void>;
+}
+interface RequestOptions {
+    method?: 'GET' | 'POST';
+    headers?: Record<string, string>;
+    body?: string;
+    /** External cancellation signal; merged with the internal timeout. */
+    signal?: AbortSignal;
+    /** Abort the request after this many milliseconds (default 20000). */
+    timeoutMs?: number;
+    /** Retry attempts on transient failures (429/5xx/timeout/network). Default 0. */
+    retries?: number;
+    /** Base backoff delay in ms, doubled each attempt (default 500). */
+    retryDelayMs?: number;
+    /** Optional response cache, keyed by method + url + body. */
+    cache?: RequestCache;
+}
+/** Thrown when a request times out or returns a non-2xx response. */
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(status: number, url: string, message: string);
+}
+/** Perform an HTTP request and parse the JSON body as `T`, with retry + cache. */
+declare function requestJson<T>(url: string, options?: RequestOptions): Promise<T>;
+
+interface NominatimOptions {
+    /** Base URL of the Nominatim instance (no trailing slash required). */
+    endpoint?: string;
+    /** Contact User-Agent, required by the public OSM instance's usage policy. */
+    userAgent?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Minimum spacing between requests in ms (default 1000, per OSM policy). */
+    minIntervalMs?: number;
+    /** Retry attempts on transient failures (default 2). */
+    retries?: number;
+    /** Optional response cache (opt-in). */
+    cache?: RequestCache;
+}
+/**
+ * Geocoding via Nominatim (OpenStreetMap). Free and key-less; please honour the
+ * usage policy (max ~1 req/s, valid User-Agent) or point `endpoint` at your own
+ * instance for production traffic.
+ */
+declare class NominatimGeocoder implements GeocodingProvider {
+    readonly name = "nominatim";
+    private readonly endpoint;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly cache;
+    private readonly limiter;
+    constructor(options?: NominatimOptions);
+    geocode(query: string, options?: GeocodeOptions): Promise<Place[]>;
+    reverse(location: LatLng, options?: GeocodeOptions): Promise<Place | null>;
+    private request;
+    private toPlace;
+}
+
+interface OverpassOptions {
+    /** Overpass interpreter endpoint URL. */
+    endpoint?: string;
+    /** Contact User-Agent sent with each request. */
+    userAgent?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Minimum spacing between requests in ms (default 1000). */
+    minIntervalMs?: number;
+    /** Retry attempts on transient failures (default 2). */
+    retries?: number;
+    /** Optional response cache (opt-in). */
+    cache?: RequestCache;
+}
+/** Build the Overpass QL query for all relevant POIs within `radiusMeters`. */
+declare function buildOverpassQuery(center: LatLng, radiusMeters: number): string;
+/** Build an Overpass query that fetches only features matching `selectors`. */
+declare function buildTargetedOverpassQuery(center: LatLng, radiusMeters: number, selectors: CategorySelector[]): string;
+/**
+ * Nearby-places search via the Overpass API over OpenStreetMap data. Fetches
+ * every relevant feature within the radius, classifies it, and (optionally)
+ * filters by category — distance ranking happens upstream.
+ */
+declare class OverpassPlacesProvider implements PlacesProvider {
+    readonly name = "overpass";
+    private readonly endpoint;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly cache;
+    private readonly limiter;
+    constructor(options?: OverpassOptions);
+    findNearby(center: LatLng, options: NearbyOptions): Promise<Poi[]>;
+    private toPoi;
+}
+
+/** How a route is travelled. Maps to engine-specific profiles per adapter. */
+type TravelMode = 'walk' | 'bike' | 'drive';
+interface RouteMetric {
+    /** Travel duration in seconds. */
+    seconds: number;
+    /** Travel distance in metres. */
+    meters: number;
+}
+/** A polygon ring as [longitude, latitude] pairs (GeoJSON order). */
+type PolygonRing = [number, number][];
+interface RoutingRequestOptions {
+    signal?: AbortSignal;
+}
+/**
+ * Routing is a commodity (OSRM/Valhalla/ORS self-host it); proximap's value is
+ * *composing* it with the amenity layer. This is the seam: a one-to-many matrix
+ * and an optional isochrone, with adapters for real engines and a haversine
+ * fallback so everything degrades gracefully and works key-free out of the box.
+ */
+interface RoutingProvider {
+    readonly name: string;
+    /** Durations/distances from one origin to many targets, aligned with `targets` (null = unreachable). */
+    matrix(origin: LatLng, targets: readonly LatLng[], mode: TravelMode, options?: RoutingRequestOptions): Promise<(RouteMetric | null)[]>;
+    /** Polygon reachable within `minutes`. Optional — absent ⇒ callers fall back to a matrix threshold. */
+    isochrone?(origin: LatLng, minutes: number, mode: TravelMode, options?: RoutingRequestOptions): Promise<PolygonRing>;
+}
+/** Typical speeds (m/s) for the haversine fallback: ~5, ~15, ~40 km/h. */
+declare const MODE_SPEED_MPS: Record<TravelMode, number>;
+/**
+ * Straight-line routing: distance via haversine, duration via a per-mode speed,
+ * isochrone as a circle. The key-free, network-free default — a floor that always
+ * works; pass a real {@link RoutingProvider} (Valhalla/OSRM) for road accuracy.
+ */
+declare class HaversineRoutingProvider implements RoutingProvider {
+    readonly name = "haversine";
+    matrix(origin: LatLng, targets: readonly LatLng[], mode: TravelMode): Promise<RouteMetric[]>;
+    isochrone(origin: LatLng, minutes: number, mode: TravelMode): Promise<PolygonRing>;
+}
+/** Approximate a circle of `radiusMeters` around `center` as a polygon ring ([lng, lat]). */
+declare function circlePolygon(center: LatLng, radiusMeters: number, steps?: number): PolygonRing;
+/** Ray-casting point-in-polygon test; `ring` is [lng, lat] pairs. */
+declare function pointInPolygon(point: LatLng, ring: PolygonRing): boolean;
+
+interface ValhallaOptions {
+    /** Base URL of the Valhalla instance (default: the key-free FOSSGIS instance). */
+    endpoint?: string;
+    userAgent?: string;
+    timeoutMs?: number;
+    /** Minimum spacing between requests in ms (default 1000). */
+    minIntervalMs?: number;
+    retries?: number;
+    cache?: RequestCache;
+}
+/**
+ * Routing via Valhalla. Defaults to the **key-free** public FOSSGIS instance,
+ * which supports pedestrian/bicycle/auto matrices and real isochrone polygons —
+ * please honour its ~1 req/s fair-use policy or self-host for volume.
+ */
+declare class ValhallaRoutingProvider implements RoutingProvider {
+    readonly name = "valhalla";
+    private readonly endpoint;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly cache;
+    private readonly limiter;
+    constructor(options?: ValhallaOptions);
+    matrix(origin: LatLng, targets: readonly LatLng[], mode: TravelMode, options?: RoutingRequestOptions): Promise<(RouteMetric | null)[]>;
+    isochrone(origin: LatLng, minutes: number, mode: TravelMode, options?: RoutingRequestOptions): Promise<PolygonRing>;
+    private post;
+}
+
+interface OsrmOptions {
+    /** Base URL of the OSRM instance (default: the public demo server). */
+    endpoint?: string;
+    userAgent?: string;
+    timeoutMs?: number;
+    minIntervalMs?: number;
+    retries?: number;
+    cache?: RequestCache;
+}
+/**
+ * Travel-time matrices via OSRM's Table service. The public demo server
+ * (`router.project-osrm.org`) only offers the car profile; for walk/bike,
+ * point `endpoint` at a self-hosted OSRM with the matching profile. Matrix only —
+ * OSRM has no isochrone service (use {@link ValhallaRoutingProvider} for that).
+ */
+declare class OsrmRoutingProvider implements RoutingProvider {
+    readonly name = "osrm";
+    private readonly endpoint;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly retries;
+    private readonly cache;
+    private readonly limiter;
+    constructor(options?: OsrmOptions);
+    matrix(origin: LatLng, targets: readonly LatLng[], mode: TravelMode, options?: RoutingRequestOptions): Promise<(RouteMetric | null)[]>;
+}
+
+/** Inputs handed to a scorer for a single POI. */
+interface ScoreInput {
+    poi: Poi;
+    distanceMeters: number;
+    /** Radius used to normalize distance into a [0, 1] proximity. */
+    radiusMeters: number;
+}
+interface RankOptions {
+    /** Per-category multipliers applied to the base score (default 1 each). */
+    categoryWeights?: Partial<Record<Category, number>>;
+    /** Custom scorer (higher = better); overrides the default proximity scorer. */
+    scoreFn?: (input: ScoreInput) => number;
+    /** Distance normalization radius; defaults to the farthest POI found. */
+    radiusMeters?: number;
+}
+/**
+ * Rank POIs by proximity to `origin`. By default results are ordered nearest
+ * first; supplying `categoryWeights` or a custom `scoreFn` switches to
+ * highest-score first (ties broken by distance). Each result gains its
+ * great-circle `distanceMeters`, a `score` in [0, 1], and a 1-based `rank`.
+ */
+declare function rankByProximity(origin: LatLng, pois: Poi[], options?: RankOptions): RankedPoi[];
+
+/**
+ * Composable consumer/accessibility facets that OSM tags carry but most apps
+ * never expose as combinable filters: dietary options, cuisine, payment
+ * methods, connectivity, seating, and step-free access. Each facet compiles to
+ * a predicate over a POI's tags; a POI must satisfy *all* active facets.
+ *
+ * Sparsity note: a missing tag is treated as "unknown", which means the POI is
+ * not a positive match — never that it "fails". We don't claim a place lacks a
+ * feature, only that OSM doesn't record it.
+ */
+interface FacetFilters {
+    /** Dietary options, e.g. "vegan", "vegetarian", "halal" (matches diet:<x>=yes|only). */
+    diet?: string | string[];
+    /** Cuisine tokens, e.g. "italian", "pizza" (matches the ;-separated cuisine tag). */
+    cuisine?: string | string[];
+    /** Accepted payments, e.g. "contactless", "cards", "visa" (matches payment:<x>). */
+    payment?: string | string[];
+    /** Require internet access (internet_access present and not "no"). */
+    internetAccess?: boolean;
+    /** Require outdoor seating. */
+    outdoorSeating?: boolean;
+    /** Require takeaway (takeaway=yes|only). */
+    takeaway?: boolean;
+    /** Require delivery. */
+    delivery?: boolean;
+    /** Required wheelchair value(s), e.g. "yes" or ["yes", "limited"]. */
+    wheelchair?: string | string[];
+    /** Raw tag constraints: `true` = present, `false` = absent, string = equals. */
+    tags?: Record<string, string | boolean>;
+}
+/** A compiled facet check over a POI's tag set. */
+type FacetPredicate = (tags: Record<string, string>) => boolean;
+/** Compile a {@link FacetFilters} object into a list of tag predicates (AND-ed). */
+declare function compileFacets(filters: FacetFilters): FacetPredicate[];
+/** Does a tag set satisfy every compiled facet predicate? */
+declare function matchesFacets(tags: Record<string, string>, predicates: readonly FacetPredicate[]): boolean;
+/**
+ * A ranking scorer for accessibility-first search: step-free (`wheelchair=yes`)
+ * POIs rank above `limited`, which rank above unknown/none — with distance
+ * breaking ties *within* each tier. Tiers occupy non-overlapping score bands so
+ * an accessible-but-slightly-farther place still outranks a closer inaccessible
+ * one, as the use case demands.
+ */
+declare function accessibleScorer(): (input: ScoreInput) => number;
+
+interface ResolveOriginOptions {
+    language?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a place name, a "lat,lng" string, or a {@link LatLng} into an origin
+ * {@link Place}. Coordinate inputs are enriched with a best-effort reverse
+ * geocode when the provider supports it, falling back to the raw coordinates.
+ */
+declare function resolveOrigin(query: string | LatLng, geocoder: GeocodingProvider, options?: ResolveOriginOptions): Promise<Place>;
+
+interface DisambiguateOptions {
+    geocoder?: GeocodingProvider;
+    /** How many candidates to fetch/return (default 5). */
+    limit?: number;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface Disambiguation {
+    query: string;
+    /**
+     * True when several plausible, geographically distinct candidates exist (e.g.
+     * the ~90 US "Springfield"s). Callers should present `candidates` rather than
+     * silently trusting `best`, since geocoder relevance is not correctness.
+     */
+    ambiguous: boolean;
+    /** The top-ranked candidate (the geocoder's best guess), or null if none. */
+    best: Place | null;
+    /** Ranked candidates to disambiguate between. */
+    candidates: Place[];
+}
+/**
+ * Geocode a query and decide whether it is ambiguous — multiple distinct places
+ * a human would need to choose between — instead of silently taking result #1.
+ * This is the agent-safety guard against confidently-wrong locations.
+ */
+declare function disambiguateLocation(query: string, options?: DisambiguateOptions): Promise<Disambiguation>;
+
+/** The closest POI matching a selector set, with its distance from an origin. */
+interface NearestMatch {
+    /** Distance to the nearest match in metres, or null if none matched. */
+    meters: number | null;
+    /** The nearest matching POI, or null if none matched. */
+    poi: Poi | null;
+}
+/**
+ * Find the nearest POI to `origin` whose tags satisfy any of `selectors`.
+ * Shared by the gap and walkability features; returns nulls (never throws)
+ * when nothing matches, so callers can frame absence honestly.
+ */
+declare function nearestMatchingPoi(origin: LatLng, pois: readonly Poi[], selectors: readonly CategorySelector[]): NearestMatch;
+
+interface FindNearbyOptions {
+    /** Search radius in metres (default 1000). */
+    radiusMeters?: number;
+    /**
+     * Restrict to these categories. Accepts the 16 normalized category names and
+     * natural-language terms ("coffee", "pharmacy", "petrol"). Unknown terms throw
+     * with suggestions.
+     */
+    categories?: Array<Category | (string & {})>;
+    /** Max results to return after ranking (default 30; <= 0 means no limit). */
+    limit?: number;
+    /** Preferred language for geocoding results. */
+    language?: string;
+    /** Override the geocoder (default: Nominatim/OSM). */
+    geocoder?: GeocodingProvider;
+    /** Override the places provider (default: Overpass/OSM). */
+    places?: PlacesProvider;
+    /**
+     * Composable consumer/accessibility facets (diet, payment, wifi, wheelchair…).
+     * A POI must satisfy every active facet; a missing tag means "not a match",
+     * never asserted as the feature being absent.
+     */
+    filters?: FacetFilters;
+    /**
+     * Accessibility-first ranking: step-free POIs rank above `limited`, above
+     * unknown/none, with distance breaking ties within each tier. Ignored when a
+     * custom `rank.scoreFn` is supplied.
+     */
+    accessible?: boolean;
+    /**
+     * Keep only places open at this time and annotate each result with
+     * `openState`/`nextChange`. `'now'` uses the current time; `{ at }` takes an
+     * ISO string or Date. Places whose hours are unknown are kept and labelled
+     * `unknown` (never silently dropped); only confirmed-closed places are
+     * removed. Times are read as the POI's local wall-clock (see {@link isOpenAt}).
+     */
+    open?: 'now' | {
+        at: string | Date;
+    };
+    /**
+     * Order results by straight-line `'distance'` (default) or by `'travelTime'`.
+     * Travel-time ranking attaches `travelSeconds`/`travelMeters` to each result.
+     */
+    rankBy?: 'distance' | 'travelTime';
+    /** Travel mode for `rankBy: 'travelTime'` (default `'walk'`). */
+    mode?: TravelMode;
+    /**
+     * Routing engine for travel-time ranking (default: {@link HaversineRoutingProvider},
+     * key-free straight-line estimates). Pass a real engine for road-network times;
+     * if it errors, ranking falls back to haversine and `result.routing.fellBack` is set.
+     */
+    routing?: RoutingProvider;
+    /** Attach a short `rankingReason` to each result (e.g. "closest open cafe, 240 m"). */
+    explain?: boolean;
+    /** Ranking tweaks (category weights or a custom scorer). */
+    rank?: RankOptions;
+    signal?: AbortSignal;
+}
+interface NearbyResult {
+    origin: Place;
+    results: RankedPoi[];
+    /** Number of POIs found before `limit` was applied. */
+    total: number;
+    /** Set when `rankBy: 'travelTime'` was used: which engine answered, and the mode. */
+    routing?: {
+        provider: string;
+        mode: TravelMode;
+        fellBack: boolean;
+    };
+}
+/**
+ * Resolve a place name or coordinate to an origin, find surrounding amenities,
+ * and rank them by distance. This is the headline entry point of proximap.
+ *
+ * @param query A place name/address, a "lat,lng" string, or a {@link LatLng}.
+ */
+declare function findNearbyAmenities(query: string | LatLng, options?: FindNearbyOptions): Promise<NearbyResult>;
+
+interface ReachableOptions {
+    /** Time budget in minutes. */
+    within: number;
+    /** Travel mode (default `'walk'`). */
+    mode?: TravelMode;
+    /** Restrict to these categories/terms (default: all amenities). */
+    categories?: Array<Category | (string & {})>;
+    /**
+     * Routing engine (default {@link HaversineRoutingProvider}). A provider with an
+     * `isochrone` method gives a true reachability polygon; otherwise membership is
+     * decided by a travel-time matrix threshold.
+     */
+    routing?: RoutingProvider;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface ReachableResult {
+    origin: Place;
+    withinMinutes: number;
+    mode: TravelMode;
+    /** The isochrone polygon used ([lng, lat] ring), or null if none was available. */
+    isochrone: PolygonRing | null;
+    /** Amenities reachable within the budget, soonest first. */
+    results: RankedPoi[];
+    count: number;
+}
+/**
+ * Return the amenities reachable within a time budget — the *answer*, not just a
+ * polygon. With an isochrone-capable engine, membership is the true road-network
+ * polygon (point-in-polygon); otherwise it falls back to a travel-time matrix
+ * threshold. Results are annotated with travel time and sorted soonest-first.
+ */
+declare function reachableAmenities(query: string | LatLng, options: ReachableOptions): Promise<ReachableResult>;
+
+/** Everyday needs a well-served neighbourhood should provide nearby. */
+declare const DEFAULT_DAILY_NEEDS: readonly ["grocery", "pharmacy", "healthcare", "food", "finance", "transport", "education", "park"];
+interface GapOptions {
+    /** Category terms to check (default: {@link DEFAULT_DAILY_NEEDS}). */
+    categories?: string[];
+    /** How far to look for the nearest instance, in metres (default 5000). */
+    searchRadiusMeters?: number;
+    /** Distance beyond which a category counts as a gap, in metres (default 1500). */
+    thresholdMeters?: number;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface CategoryGap {
+    /** The requested category term. */
+    category: string;
+    /** Distance to the nearest match, or null if none was found within the search radius. */
+    nearestMeters: number | null;
+    isGap: boolean;
+    /** Data-completeness of the nearest match (a confidence hint), when known. */
+    nearestCompleteness?: number;
+}
+interface GapReport {
+    origin: Place;
+    searchRadiusMeters: number;
+    thresholdMeters: number;
+    /** Every requested category with its nearest-match status. */
+    gaps: CategoryGap[];
+    /** Categories flagged as gaps — i.e. not found in OSM within the threshold. */
+    missing: string[];
+}
+/**
+ * Report which everyday amenities are missing or far from a location — the
+ * inverse of "what's nearby". Because OSM under-maps some areas, absence is
+ * framed as "not found in OSM within the threshold", never asserted as truth;
+ * `nearestCompleteness` hints at data confidence.
+ */
+declare function detectGaps(query: string | LatLng, options?: GapOptions): Promise<GapReport>;
+
+/**
+ * A daily-need category and how much it counts toward the walkability score.
+ * Weights are relative — the score normalizes by their sum.
+ */
+interface CategoryWeight {
+    /** A natural-language category term (resolved via the taxonomy). */
+    term: string;
+    weight: number;
+}
+/**
+ * Default basket of daily needs and weights, loosely modelled on the published
+ * Walk Score categories but fully open and tunable. Groceries, food, pharmacy,
+ * and transit count most; civic/leisure round out a complete neighbourhood.
+ */
+declare const DEFAULT_WALK_CATEGORIES: CategoryWeight[];
+interface WalkabilityDecay {
+    /** At/below this distance (m) a category scores full marks (default 400 ≈ 5-min walk). */
+    idealMeters?: number;
+    /** At/beyond this distance (m) a category scores zero (default 2400 ≈ 30-min walk). */
+    maxMeters?: number;
+}
+interface WalkabilityOptions {
+    /** Daily-need categories and weights (default {@link DEFAULT_WALK_CATEGORIES}). */
+    categories?: CategoryWeight[];
+    /** Distance-decay tuning (defaults: full credit ≤ 400 m, zero ≥ 2400 m). */
+    decay?: WalkabilityDecay;
+    /** How far to search for the nearest of each category (default = decay max). */
+    searchRadiusMeters?: number;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface CategoryScore {
+    category: string;
+    weight: number;
+    /** Distance to the nearest match, or null if none found within the search radius. */
+    nearestMeters: number | null;
+    /** Distance-decay sub-score in [0, 1]. */
+    subScore: number;
+    /** Data-completeness of the nearest match (a confidence hint), when known. */
+    nearestCompleteness?: number;
+}
+interface WalkabilityReport {
+    origin: Place;
+    /** Overall walkability in [0, 100]; higher is more walkable. */
+    score: number;
+    /**
+     * Confidence in [0, 1] reflecting OSM data density around the origin — low
+     * where few categories were found or their tagging is sparse. A low score
+     * with low confidence means "thin data here", not "nothing here".
+     */
+    confidence: number;
+    /** Per-category nearest distance and sub-score. */
+    breakdown: CategoryScore[];
+    /** Categories with no match found within the search radius. */
+    missing: string[];
+    /** The distance-decay bounds actually used. */
+    decay: {
+        idealMeters: number;
+        maxMeters: number;
+    };
+}
+/**
+ * Distance-decay sub-score: full credit within `ideal`, linearly declining to
+ * zero at `max`. Deliberately simple and transparent so the score is auditable
+ * and tunable, unlike opaque proprietary indices.
+ */
+declare function walkSubScore(meters: number | null, idealMeters: number, maxMeters: number): number;
+/**
+ * Score how walkable / well-served a location is: a 0–100 number plus a full
+ * per-category breakdown, the categories that are missing, and a data-confidence
+ * note. An open, transparent, tunable, OSM-native alternative to proprietary
+ * walkability indices — every input is visible and adjustable.
+ */
+declare function walkabilityScore(query: string | LatLng, options?: WalkabilityOptions): Promise<WalkabilityReport>;
+
+interface CompareOptions {
+    /** Dimensions and weights to compare on (default: the walkability basket). */
+    categories?: CategoryWeight[];
+    /** Distance-decay tuning, passed through to each location's scoring. */
+    decay?: WalkabilityDecay;
+    /** How far to search around each location (default = decay max). */
+    searchRadiusMeters?: number;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface LocationScore {
+    origin: Place;
+    /** Walkability score (0–100) under the comparison weights. */
+    score: number;
+    confidence: number;
+    breakdown: CategoryScore[];
+    missing: string[];
+}
+interface DimensionWinner {
+    category: string;
+    weight: number;
+    /** Index into `locations` of the best location for this dimension, or null if none has it. */
+    bestIndex: number | null;
+}
+interface RankedLocation {
+    /** Index into `locations` (input order). */
+    index: number;
+    score: number;
+    origin: Place;
+}
+interface ComparisonReport {
+    /** Each location's score, in input order. */
+    locations: LocationScore[];
+    /** Locations sorted best-first (ties: higher confidence, then input order). */
+    ranked: RankedLocation[];
+    /** The top-ranked location, or null if no candidates were given. */
+    best: RankedLocation | null;
+    /** For each dimension, which location is best served. */
+    dimensions: DimensionWinner[];
+    /** The weights actually used. */
+    weights: CategoryWeight[];
+}
+/**
+ * Compare N candidate locations across weighted daily-need dimensions and rank
+ * them — a key-free, arbitrary-N, OSM-native relocation/siting scorecard. Pure
+ * composition over {@link walkabilityScore}: each location is scored the same
+ * way, then ranked and compared dimension-by-dimension.
+ *
+ * Out of scope by design (not in OSM): transit *frequency*, school quality,
+ * crime, prices. We compare amenity *access*, and carry through walkability's
+ * confidence so thin data reads as low confidence, not a confident zero.
+ */
+declare function compareLocations(queries: ReadonlyArray<string | LatLng>, options?: CompareOptions): Promise<ComparisonReport>;
+
+interface ErrandOptions {
+    /** Categories/terms to hit one of each, e.g. ['pharmacy', 'atm', 'grocery']. */
+    categories: Array<Category | (string & {})>;
+    /** Travel mode for the cost matrix (default `'walk'`). */
+    mode?: TravelMode;
+    /** Optional fixed end point (a place name, "lat,lng", or coordinate). */
+    end?: string | LatLng;
+    /** Nearest candidates considered per category (default 5). */
+    candidatesPerCategory?: number;
+    /** How far to look for candidates, in metres (default 3000). */
+    searchRadiusMeters?: number;
+    /**
+     * Cost engine for the matrix (default {@link HaversineRoutingProvider} — an
+     * honest, instant, key-free straight-line MVP). Pass a real engine for road
+     * times; note it issues one matrix request per point.
+     */
+    routing?: RoutingProvider;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+}
+interface ErrandStop {
+    category: string;
+    poi: Poi;
+    /** Leg from the previous point (origin or prior stop) to this stop. */
+    legSeconds: number;
+    legMeters: number;
+}
+interface ErrandPlan {
+    origin: Place;
+    end: Place | null;
+    mode: TravelMode;
+    /** Chosen places in visit order. */
+    stops: ErrandStop[];
+    totalSeconds: number;
+    totalMeters: number;
+    /** Requested categories with no candidate nearby — skipped, not faked. */
+    missing: string[];
+    candidatesPerCategory: number;
+}
+/**
+ * Plan the shortest trip that buys/visits one of each requested category near an
+ * origin — the **Generalized TSP** ("pick one per set, then optimize") that no
+ * consumer app ships. Fetches the nearest candidates per category, builds a cost
+ * matrix, and solves exactly via a grouped Held-Karp DP (instant at consumer
+ * scale). Categories with no candidate are reported as `missing`, never faked.
+ */
+declare function planErrands(query: string | LatLng, options: ErrandOptions): Promise<ErrandPlan>;
+
+/**
+ * ODbL attribution for exported OpenStreetMap data. OSM's licence lets you store
+ * and redistribute results (unlike the commercial APIs) **provided you keep this
+ * notice** — so exporters emit it and callers should keep it with the data.
+ */
+declare const ODBL_ATTRIBUTION = "\u00A9 OpenStreetMap contributors, ODbL (https://www.openstreetmap.org/copyright)";
+interface GeoJsonFeature {
+    type: 'Feature';
+    /** GeoJSON uses [longitude, latitude] order (RFC 7946). */
+    geometry: {
+        type: 'Point';
+        coordinates: [number, number];
+    };
+    properties: Record<string, unknown>;
+}
+interface GeoJsonFeatureCollection {
+    type: 'FeatureCollection';
+    /** ODbL attribution, per {@link ODBL_ATTRIBUTION}. */
+    attribution: string;
+    features: GeoJsonFeature[];
+}
+/** Serialize a nearby-search result to a GeoJSON FeatureCollection (one Point per POI). */
+declare function toGeoJSON(result: NearbyResult): GeoJsonFeatureCollection;
+/** Serialize a nearby-search result to RFC 4180 CSV (header row + one row per POI). */
+declare function toCSV(result: NearbyResult): string;
+
+/**
+ * A stored snapshot of an area's POIs. OSM data (ODbL) may be freely stored and
+ * redistributed — the advantage commercial APIs forbid — so this is a portable,
+ * offline-queryable dataset. Keep the `attribution` with the data.
+ */
+interface SnapshotDataset {
+    attribution: string;
+    /** ISO timestamp the snapshot was captured. */
+    createdAt: string;
+    /** Center the snapshot was taken around. */
+    center: LatLng;
+    /** Radius captured, in metres. */
+    radiusMeters: number;
+    /** Normalized, deduplicated POIs in the area. */
+    pois: Poi[];
+}
+interface SnapshotOptions {
+    /** Radius to capture, in metres (default 2000). */
+    radiusMeters?: number;
+    /** Restrict the capture to these categories/terms (default: all amenities). */
+    categories?: Array<Category | (string & {})>;
+    geocoder?: GeocodingProvider;
+    places?: PlacesProvider;
+    language?: string;
+    signal?: AbortSignal;
+    /** Override the capture timestamp (ISO) — for deterministic output/tests. */
+    createdAt?: string;
+}
+/**
+ * Capture an area's POIs into a {@link SnapshotDataset} for offline reuse. Pair
+ * with {@link DatasetPlacesProvider} to answer queries with no network calls.
+ */
+declare function snapshotArea(query: string | LatLng, options?: SnapshotOptions): Promise<SnapshotDataset>;
+/**
+ * A {@link PlacesProvider} backed by a stored {@link SnapshotDataset} — answers
+ * nearby queries entirely from memory, with no network. Use a "lat,lng" query
+ * (no geocoding) for a fully offline pipeline.
+ */
+declare class DatasetPlacesProvider implements PlacesProvider {
+    readonly name = "dataset";
+    private readonly pois;
+    constructor(dataset: SnapshotDataset);
+    findNearby(center: LatLng, options: NearbyOptions): Promise<Poi[]>;
+}
+
+/**
+ * @proximap/core — geospatial engine for places, proximity, and amenities.
+ *
+ * Defaults to OpenStreetMap (Nominatim + Overpass) with no API keys, but every
+ * stage is pluggable via the provider interfaces in {@link ./types}.
+ */
+/** Library version, kept in sync with package.json. */
+declare const VERSION = "1.0.0";
+
+export { CATEGORIES, CATEGORY_LABELS, type Categorization, type Category, type CategoryGap, type CategoryScore, type CategorySelector, type CategoryWeight, type CompareOptions, type ComparisonReport, DEFAULT_DAILY_NEEDS, DEFAULT_USER_AGENT, DEFAULT_WALK_CATEGORIES, DatasetPlacesProvider, type DimensionWinner, type DisambiguateOptions, type Disambiguation, type ErrandOptions, type ErrandPlan, type ErrandStop, type FacetFilters, type FacetPredicate, type FindNearbyOptions, type GapOptions, type GapReport, type GeoJsonFeature, type GeoJsonFeatureCollection, type GeocodeOptions, type GeocodingProvider, HaversineRoutingProvider, HttpError, InMemoryCache, type LatLng, type LocationScore, MODE_SPEED_MPS, type NearbyOptions, type NearbyResult, type NearestMatch, NominatimGeocoder, type NominatimOptions, ODBL_ATTRIBUTION, type OpenState, type OpeningEvaluation, type OsrmOptions, OsrmRoutingProvider, type OverpassOptions, OverpassPlacesProvider, type Place, type PlacesProvider, type Poi, type PolygonRing, type RankOptions, type RankedLocation, type RankedPoi, RateLimiter, type ReachableOptions, type ReachableResult, type RequestCache, type RequestOptions, type ResolveOriginOptions, type ResolvedCategories, type RouteMetric, type RoutingProvider, type RoutingRequestOptions, type ScoreInput, type SnapshotDataset, type SnapshotOptions, type TravelMode, VERSION, type ValhallaOptions, ValhallaRoutingProvider, type WalkabilityDecay, type WalkabilityOptions, type WalkabilityReport, accessibleScorer, buildOverpassQuery, buildTargetedOverpassQuery, categorize, categoryVocabulary, circlePolygon, compareLocations, compileFacets, completenessOf, dedupePois, detectGaps, disambiguateLocation, findNearbyAmenities, formatDistance, formatDuration, haversineMeters, isCategory, isKnownTerm, isOpenAt, lastVerifiedOf, matchesFacets, nearestMatchingPoi, parseCoordinates, planErrands, pointInPolygon, rankByProximity, reachableAmenities, requestJson, resolveCategories, resolveOrigin, selectorToOverpassFilter, snapshotArea, suggestCategories, tagsMatchAnySelector, tagsMatchSelector, toCSV, toGeoJSON, walkSubScore, walkabilityScore };