/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 * Fetches CC0 sub-venue concept labels and airport-terminal names from the Wikidata Query Service.
 * The labels are candidates that need curation before any recipe uses them as designators.
 */
import { APIClient, type ClockLike } from "@mailwoman/core/api";
import type { PathBuilderLike } from "path-ts";
import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
/**
 * The public SPARQL endpoint of the Wikidata Query Service.
 */
export declare const WDQS_ENDPOINT = "https://query.wikidata.org/sparql";
/**
 * The descriptive `User-Agent` that Wikidata requires, with the tool name, URL and contact address.
 */
export declare const WIKIDATA_USER_AGENT = "mailwoman/1.0 (https://github.com/sister-software/mailwoman; teffen@sister.software) corpus-subvenue-fetch";
/**
 * A Wikidata concept whose labels are collected for one sub-venue designator.
 */
export interface SubVenueConcept {
    designatorID: string;
    qid: string;
    /**
     * An English description that lets a reviewer confirm the QID.
     */
    gloss: string;
}
/**
 * The concepts whose labels and aliases the fetcher collects.
 */
export declare const SUBVENUE_CONCEPTS: readonly SubVenueConcept[];
/**
 * Builds a query for the labels and aliases of the concepts in every language.
 */
export declare function buildDesignatorLabelQuery(concepts?: readonly SubVenueConcept[]): string;
/**
 * Builds a query for the labels of instances of the class and its subclasses.
 *
 * The subclass walk returns some unrelated items.
 * Consumers must filter them.
 */
export declare function buildTerminalInstanceQuery(classQID?: string): string;
/**
 * The SPARQL JSON results shape.
 */
export interface SPARQLResults {
    results: {
        bindings: Array<Record<string, {
            type: string;
            value: string;
            "xml:lang"?: string;
        }>>;
    };
}
/**
 * Reports whether a value has the SPARQL JSON results shape.
 */
export declare function isSPARQLResults(value: unknown): value is SPARQLResults;
/**
 * Options for {@link createWikidataClient}.
 */
export interface CreateWikidataClientOptions {
    /**
     * The directory of the on-disk response cache.
     */
    cacheDir: PathBuilderLike;
    /**
     * The clock for pacing and retries.
     * Tests can replace it.
     */
    clock?: ClockLike;
    /**
     * Axios overrides.
     * Replacement headers must keep the required `User-Agent`.
     */
    axios?: ConstructorParameters<typeof APIClient>[0]["axios"];
}
/**
 * A paced, cached and retrying Wikidata Query Service client.
 */
export declare class WikidataClient extends APIClient {
    /**
     * Runs one SPARQL query.
     */
    query(sparql: string): Promise<SPARQLResults>;
}
/**
 * Creates a Wikidata client with the fetcher's pacing, retry, cache and header defaults.
 */
export declare function createWikidataClient(options: CreateWikidataClientOptions): WikidataClient;
/**
 * Options for {@link fetchWikidataSubVenue}.
 */
export type FetchWikidataSubVenueOptions = BaseFetchOptions;
/**
 * Runs the label and terminal queries.
 * It saves their raw JSON and writes a manifest.
 */
export declare function fetchWikidataSubVenue(options: FetchWikidataSubVenueOptions, report?: (line: string) => void): Promise<FetchSummary>;
//# sourceMappingURL=wikidata-subvenue.d.ts.map