/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 *   Fetch GeoNames per-country GAZETTEER dumps — the 19-column `<CC>.txt` files under
 *   `https://download.geonames.org/export/dump/` (NOT the postal exports; those are `export/zip/` and
 *   `geonames-postal.ts`'s job). The dumps carry feature classes and codes (column 8: `PPLC` national capital,
 *   `PPLA` first-order administrative seat), which is what the capitals reference build consumes (#1880).
 *
 *   The catalog question is answered by the SOURCE, not by an ISO list: `countryInfo.txt` in the same directory
 *   enumerates every country GeoNames publishes, one row per ISO alpha-2 code, and also names each country's
 *   capital — the cross-check the capitals build grades its `PPLC` extraction against. Fetch that first; derive
 *   the country set from it; then a dump absent from disk is a measured gap against the source's own catalog
 *   rather than a silent hole. The dump directory may hold files this tool did not fetch: present files are never
 *   overwritten, and a present `<CC>.txt` that is NOT a 19-column gazetteer dump (GeoNames' postal exports share
 *   the basename) is reported as `wrong_format_present`, never counted as coverage.
 */
import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
export interface FetchGeonamesDumpOptions extends BaseFetchOptions {
    /**
     * ISO alpha-2 codes, any casing. Absent → every country `countryInfo.txt` enumerates.
     */
    countries?: readonly string[];
    /**
     * Dump directory to read from. Defaults to GeoNames' own; exists so the 404 and coverage behaviour can be exercised
     * against a local server.
     */
    baseURL?: string;
    /**
     * Refetch a dump whose `<CC>.txt` already exists. Default false — the tool fills gaps.
     */
    force?: boolean;
}
interface GeonamesDumpFileEntry {
    country: string;
    filename: string;
    source_url: string;
    sha256: string;
    bytes: number;
}
export interface GeonamesDumpManifest {
    source: string;
    base_url: string;
    license: string;
    attribution: string;
    downloaded_at: string;
    files: GeonamesDumpFileEntry[];
    /**
     * `<CC>.txt` files already on disk and left alone — the hand-fetched population this tool extends.
     */
    skipped_present: string[];
    /**
     * Countries in the source catalog that the source's dump directory nonetheless 404s — a fact about the source,
     * recorded so a later reader does not spend the fetch to rediscover it.
     */
    unavailable: string[];
    /**
     * Present `<CC>.txt` files that are NOT 19-column gazetteer dumps — GeoNames' postal exports share the same basename,
     * and seven tier-1 postal files sat at these paths reading as "present" until the capitals build found them
     * capital-less. Left in place (this tool never overwrites data it did not fetch); the fix is to move the file to its
     * own home and rerun.
     */
    wrong_format_present: string[];
}
/**
 * True when the first non-empty line carries the gazetteer dump's 19 tab-separated columns. Accepts a partial head read
 * — the first line is the whole question, so callers need not hand it a resident 350 MB dump.
 *
 * Walk the string directly rather than constructing a spliterator: the capitals builder already holds whole country
 * dumps as strings, and a byte-oriented spliterator would UTF-8 encode that input — allocating up to another 350 MB —
 * merely to inspect its first non-empty line.
 */
export declare function looksLikeGazetteerDump(text: string): boolean;
/**
 * Parse the ISO codes (column 1) and capital names (column 6) out of `countryInfo.txt` — `#`-prefixed lines are the
 * file's own commentary.
 */
export declare function parseCountryInfo(text: string): Array<{
    country: string;
    capital: string;
}>;
/**
 * Download `countryInfo.txt` plus every missing `<CC>.zip`, extracting each to `<outRoot>/<CC>.txt` beside the
 * hand-fetched dumps, with a `MANIFEST.json` naming fetched, skipped-present, and source-unavailable countries.
 */
export declare function fetchGeonamesDumps(options: FetchGeonamesDumpOptions, report?: (line: string) => void): Promise<FetchSummary & {
    skippedPresent: string[];
}>;
export {};
//# sourceMappingURL=dump.d.ts.map