/** * @fileoverview Geographic helpers shared by location-aware tools — great-circle * distance and parsing of the `geoFilter` center coordinates. * @module mcp-server/tools/utils/geo-helpers */ import type { StudyLocation } from '../../../services/clinical-trials/types.js'; /** Mean Earth radius in miles, used by the Haversine formula. */ export declare const EARTH_RADIUS_MI = 3958.7613; /** A study location annotated with its distance from a reference point. */ export type LocationWithDistance = StudyLocation & { distanceMi?: number; }; /** A distance in miles to the one decimal content[] renders, so both surfaces carry the same value. */ export declare function roundMi(distanceMi: number): number; /** Great-circle distance in miles between two lat/lon points (Haversine). */ export declare function haversineMi(a: { lat: number; lon: number; }, b: { lat: number; lon: number; }): number; /** * Extract the center coordinates from a `geoFilter` value of the form * `distance(lat, lon, radius)`. The radius (with an optional `mi`/`km` suffix) is * already applied by the upstream query, so only lat/lon are returned here — used * to re-rank a study's locations by proximity. Tolerates surrounding whitespace. * Returns undefined when the value isn't a parseable distance expression. */ export declare function parseGeoFilterCenter(geoFilter: string | undefined): { lat: number; lon: number; } | undefined; /** * Describe why a `geoFilter` value cannot be sent upstream, or `undefined` when * it is well formed. * * ClinicalTrials.gov does not reject every bad geo expression: a radius with no * unit returns 200 with an empty result set (the number is read as meters), a * zero radius answers 500 through the whole retry budget, and an out-of-range * coordinate answers 400 with a bare `Search error` body that carries nothing * to classify on. Each surfaced as something other than a bad-input error, so * the caller saw an empty cohort, a service outage, or an unreasoned validation * failure instead of the mistake they made. * * Shapes upstream does reject with `incorrect format` are caught here early * with the same message the service would have thrown, so only the round trip * changes. Range and positivity violations — which have no upstream * counterpart — name the offending value as well. * * This is the validation gate; `parseGeoFilterCenter` is not. That one reads a * center for re-ranking and must keep answering silently for anything it cannot * parse. The value is matched as supplied — the blank check has already run, * and upstream rejects surrounding whitespace too, so trimming here would pass * a string the request then fails on. */ export declare function describeGeoFilterRejection(geoFilter: string): string | undefined; //# sourceMappingURL=geo-helpers.d.ts.map