/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 * Harvests the INSPIRE Addresses (AD) theme of agentschap Digitaal Vlaanderen into the directory
 * that `#be/adapters/vlaanderen/adapter` reads.
 *
 * `./inspire-addresses.ts` owns what every INSPIRE WFS shares, in GeoJSON. This module is Flanders'
 * own GML paging, kept apart for three reasons the service forced:
 *
 * 1. The component types are small enough to take whole — 167,218 `ad:ThoroughfareName`, 1,190
 *    `ad:PostalDescriptor`, 609 `ad:AdminUnitName` — so the harvest writes one file per type and the
 *    adapter joins locally rather than resolving four references per address against 4,563,062 of
 *    them.
 * 2. `sortBy=gml:identifier` answers HTTP 504, so the service grants no ordering. The manifest
 *    records the pages taken and their order, which is what makes a harvest reproducible even though
 *    a second harvest need not match the first.
 * 3. A bare `resultType=hits` answers `numberMatched="10000"` whatever `count` asks for. The count
 *    has to be taken past index 0: `startIndex=1` answers `numberMatched="4563062"`, and the
 *    bisected tail agrees — `startIndex=4563061` returns one feature and `startIndex=4563062`
 *    returns none.
 *
 * Article 3 of the elected `Modellicentie voor gratis hergebruik Vlaanderen` grants reproduction and
 * transmission, which is what paging performs, and article 6 states that access is free. The
 * capabilities document's `ows:Fees` and `ows:AccessConstraints` describe the service rather than
 * the data, so neither is read here.
 */
import { APIClient } from "@mailwoman/core/api";
import { type PathBuilderLike } from "path-ts";
import { type VlaanderenHarvest } from "#be/adapters/vlaanderen/adapter";
import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
/**
 * The service this module harvests.
 */
export declare const VLAANDEREN_AD_WFS = "https://geo.api.vlaanderen.be/ad/wfs";
/**
 * The largest page the service will serve.
 *
 * A `count=50000` request answers with 10,000 features, so asking for more costs
 * a request and returns the same body.
 */
export declare const MAX_PAGE_SIZE = 10000;
/**
 * One `GetFeature` response, with what its root element states about itself.
 */
export interface FeaturePageBody {
    body: string;
    /**
     * The `numberReturned` the root states, or `null` where it states none.
     */
    numberReturned: number | null;
    /**
     * The `numberMatched` the root states, or `null` where it answers `unknown`.
     *
     * Every results page of this service answers `unknown`, so only a `resultType=hits`
     * request past index 0 yields a number.
     */
    numberMatched: number | null;
}
/**
 * Issues one `GetFeature` against the service.
 *
 * `#tools/fetch/wfs-harvest` owns the request, the exception check and the counts,
 * which every markup-serving WFS in this directory shares.
 * This states the service and its context.
 *
 * @throws When the service answers an OGC exception report, so a 400 carrying
 * `ows:ExceptionCode/NoApplicableCode` raises rather than being written into the harvest as a page.
 */
export declare function readVlaanderenPage(client: Pick<APIClient, "fetch">, params: Readonly<Record<string, string>>): Promise<FeaturePageBody>;
/**
 * The number of features a type holds, asked past index 0.
 *
 * @throws When the service states no count, so a missing count never reads as zero features.
 */
export declare function readVlaanderenFeatureCount(client: Pick<APIClient, "fetch">, typeName: string): Promise<number>;
export interface HarvestVlaanderenOptions {
    /**
     * Where the harvest is written.
     * The adapter reads this same directory.
     */
    outputDir: PathBuilderLike;
    /**
     * Stop after this many address pages, for a probe rather than a full harvest.
     */
    maxPages?: number;
    /**
     * Features per address page, capped at {@link MAX_PAGE_SIZE}.
     *
     * This sizes the address pages only.
     * A probe lowers it to take a small page without also splitting `ad:ThoroughfareName`
     * into 167,218 / `pageSize` requests.
     */
    pageSize?: number;
    /**
     * Features per component page, capped at {@link MAX_PAGE_SIZE} and defaulting to it.
     *
     * Only a test lowers this.
     * A component type is always taken whole, so a smaller page buys requests alone.
     */
    componentPageSize?: number;
    signal?: AbortSignal;
}
export declare function harvestVlaanderenAD(client: Pick<APIClient, "fetch">, options: HarvestVlaanderenOptions): Promise<VlaanderenHarvest>;
/**
 * The directory `#be/adapters/vlaanderen/adapter` reads, given the root a fetch wrote under.
 *
 * The adapter reads the directory rather than one file, because a harvest writes the addresses
 * and each component type as separate documents beside `harvest.json`.
 */
export declare function vlaanderenInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
/**
 * Per-invocation options for the registry entry.
 */
export interface FetchVlaanderenOptions extends BaseFetchOptions {
    maxPages?: number;
    pageSize?: number;
    componentPageSize?: number;
    signal?: AbortSignal;
}
/**
 * The registry entry.
 *
 * `harvestVlaanderenAD` takes a client so a test can drive it against stubbed bodies.
 * This supplies the client the registry's callers expect, and reports the harvest as a
 * {@linkcode FetchSummary}: one harvest is one fetched unit whatever the page count,
 * because the adapter reads the directory rather than any single page.
 */
export declare function fetchVlaanderenAD(options: FetchVlaanderenOptions, report?: (line: string) => void): Promise<FetchSummary>;
//# sourceMappingURL=vlaanderen-ad.d.ts.map