/**
 * Utility for resolving location coordinates from various input formats
 */
import { LocationStore } from '../services/locationStore.js';
import { GeocodingService } from '../services/geocoding.js';
import { NominatimService } from '../services/nominatim.js';
export interface LocationInput {
    latitude?: number;
    longitude?: number;
    location_name?: string;
    city_name?: string;
}
export interface ResolvedLocation {
    latitude: number;
    longitude: number;
    source: 'coordinates' | 'saved_location' | 'geocoded' | 'default';
    location_name?: string;
    /**
     * ISO country code, when known from the resolution path (saved location or
     * geocoded city_name). Casing follows the upstream source as-is (e.g. saved
     * locations store uppercase "US"/"GB"; geocoding providers vary) — consumers
     * normalize as needed. Unset for raw coordinates and for defaults that are
     * not themselves a saved/geocoded location.
     */
    country_code?: string;
}
/**
 * Build a header line describing how a location name was resolved.
 *
 * Returns an empty string for direct-coordinate requests (nothing to disclose),
 * otherwise a Markdown line showing the matched name and coordinates so an
 * ambiguous saved/geocoded lookup is transparent to the user. Shared across all
 * weather handlers so location disclosure is consistent.
 *
 * @param resolved - Result from resolveLocation/resolveLocationAsync
 * @returns Markdown line (with trailing blank line) or '' for coordinate input
 */
export declare function formatLocationLine(resolved: ResolvedLocation): string;
/**
 * Prepend the resolved-location header to a handler's text content, if any.
 *
 * Mutates the first text block of a standard `{ content: [...] }` handler result
 * so name-based lookups (saved location or geocoded city) surface what matched.
 * A no-op for direct-coordinate requests.
 *
 * `text` is optional in the constraint because a handler may return mixed
 * content — get_weather_imagery's composite branch returns `[text, image]`,
 * and an image block carries no `text`. The runtime guard below already
 * checks for a leading text block, so behaviour is unchanged.
 *
 * @param result - Handler result whose first text block will be prefixed
 * @param resolved - Result from resolveLocationAsync
 * @returns The same result object (for convenient chaining)
 */
export declare function prependLocationLine<T extends {
    content: Array<{
        type: string;
        text?: string;
    }>;
}>(result: T, resolved: ResolvedLocation): T;
/**
 * Prepend an already-formatted critical-alert banner to a handler's text content, if any.
 *
 * Mutates the first text block of a standard `{ content: [...] }` handler result,
 * the same shape `prependLocationLine` uses. This function stays deliberately
 * ignorant of what a critical alert is or how one is formatted — it takes the
 * finished `banner` string and only prepends it, so this file never imports
 * `src/utils/criticalAlert.ts` and never grows a dependency cycle.
 *
 * Ordering: the banner is outermost. Callers run `prependLocationLine` first
 * and this function second, so rendered text reads `banner` -> `**Location:**`
 * -> `# Heading`. That ordering is exactly what leaves the two whole-string
 * `prependLocationLine` locks in `tests/unit/locationResolver.test.ts`
 * unedited — this function only ever adds *above* the location line, never
 * between it and the heading.
 *
 * `text` is optional in the constraint for the same reason it is on
 * `prependLocationLine`: a handler may return mixed content (e.g.
 * get_weather_imagery's composite branch returns `[text, image]`), and an
 * image block carries no `text`. The runtime guard below already checks for
 * a leading text block, so behaviour is unchanged.
 *
 * @param result - Handler result whose first text block will be prefixed
 * @param banner - Already-formatted banner string (empty string is a no-op)
 * @returns The same result object (for convenient chaining)
 */
export declare function prependCriticalAlertBanner<T extends {
    content: Array<{
        type: string;
        text?: string;
    }>;
}>(result: T, banner: string): T;
/**
 * Clear the module-level city geocode cache.
 * Exposed primarily for tests to guarantee a clean slate.
 */
export declare function clearCityGeocodeCache(): void;
/**
 * Resolve location coordinates from either direct coordinates or a saved location name
 *
 * @param args - Arguments containing either (latitude + longitude) OR location_name
 * @param locationStore - Location store instance
 * @returns Resolved coordinates and metadata
 * @throws Error if neither coordinates nor location_name provided, or if validation fails
 */
export declare function resolveLocation(args: LocationInput, locationStore: LocationStore): ResolvedLocation;
/**
 * Resolve location coordinates from direct coordinates, a saved location name,
 * or a free-text city name that is geocoded on demand.
 *
 * Resolution precedence: coordinates > location_name (saved) > city_name (geocoded)
 * > server default (WEATHER_DEFAULT_LOCATION, when configured). Geocoded city
 * lookups are cached (see cityGeocodeCache) so repeated requests for the same
 * place do not re-hit the geocoding providers.
 *
 * @param args - Arguments containing coordinates, a saved location_name, or a city_name
 * @param locationStore - Location store instance (for saved locations)
 * @param geocodingService - Geocoding service (for city_name lookups)
 * @returns Resolved coordinates and metadata
 * @throws Error if nothing usable is provided (and no default is configured),
 *   validation fails, or geocoding finds no match
 */
export declare function resolveLocationAsync(args: LocationInput, locationStore: LocationStore, geocodingService: GeocodingService): Promise<ResolvedLocation>;
/**
 * Country resolution, in the order get_alerts uses: a `country_code` the
 * resolution path already knows (saved location / geocoded city) > a cached
 * country-level Nominatim reverse lookup > nothing (the caller falls back to
 * `isInUS`).
 *
 * A missing service (test harnesses) skips the lookup silently; only a
 * *failed* lookup sets `lookupFailed`, which earns the one-line note.
 */
export declare function resolveCountryCode(resolvedCountryCode: string | undefined, latitude: number, longitude: number, nominatimService?: NominatimService): Promise<{
    countryCode: string | null;
    lookupFailed: boolean;
}>;
//# sourceMappingURL=locationResolver.d.ts.map