/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 * Download the FINESS establishment extract for the `fr-finess-overseas` adapter.
 *
 * The extract is a resource of the data.gouv.fr dataset
 * `finess-extraction-du-fichier-des-etablissements`, whose API record at
 * `https://www.data.gouv.fr/api/1/datasets/finess-extraction-du-fichier-des-etablissements/` lists
 * every resource with its URL, `last_modified`, `filesize` and a SHA-1 `checksum`. The establishment
 * extract is the resource whose file is named `etalab-cs1100502-stock-<date>-<time>.csv`; the
 * geolocated extract `etalab-cs1100507-…` and the history archive sit beside it and are not read.
 * {@linkcode selectFinessExtract} picks the newest establishment extract the record lists, so the
 * fetcher follows a republication without a code change.
 *
 * The publisher froze the extract at data dated 2026-05-04 and states on the dataset page that it
 * will not be updated again, so a re-run normally finds the recorded file current and makes no
 * transfer.
 *
 * The transfer is checked against the record: the byte count against `filesize` and the SHA-1
 * against `checksum`. The record's SHA-1 can describe an earlier upload of the same object. Measured
 * on 2026-10-03, the record states `d3c2c0e68a413974dffbe0aabf093e3f40414967` and `last_modified`
 * 2026-05-12, while the object `static.data.gouv.fr` serves has `last-modified` 2026-07-02, SHA-1
 * `8be4bdc362f3f382e3a7de2a26da6c3a5e6074f3` on two separate transfers, the record's 35,786,629
 * bytes, and an ETag equal to its MD5. Where the SHA-1 disagrees, the storage host's ETag MD5
 * decides, and the manifest records all three digests. A file that matches neither is an
 * interrupted transfer or an error page and is removed rather than recorded. The manifest records the SHA-256 the corpus tooling compares,
 * the resource's `last_modified`, and the extract's own first line (`finess;etalab;111;2026-05-12`),
 * which carries the extraction date Licence Ouverte's attribution names.
 */
import { APIClient } from "@mailwoman/core/api";
import { type PathBuilderLike } from "path-ts";
import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download";
/**
 * The dataset's slug on data.gouv.fr.
 */
export declare const FINESS_DATASET_SLUG = "finess-extraction-du-fichier-des-etablissements";
/**
 * The dataset's API record, which lists its resources.
 */
export declare const FINESS_DATASET_API_URL = "https://www.data.gouv.fr/api/1/datasets/finess-extraction-du-fichier-des-etablissements/";
/**
 * The dataset's page, which states the license.
 */
export declare const FINESS_DATASET_PAGE_URL = "https://www.data.gouv.fr/datasets/finess-extraction-du-fichier-des-etablissements";
/**
 * The fields of a data.gouv.fr resource the fetcher reads.
 */
export interface DataGouvResource {
    id: string;
    title?: string;
    url: string;
    last_modified: string;
    filesize?: number | null;
    checksum?: {
        type: string;
        value: string;
    } | null;
}
/**
 * The fields of a data.gouv.fr dataset record the fetcher reads.
 */
export interface DataGouvDataset {
    license?: string;
    resources: readonly DataGouvResource[];
}
/**
 * What the manifest records for the extract, beyond {@linkcode SourceManifest}'s five fields.
 */
export interface FinessExtractManifest extends SourceManifest {
    resource_id: string;
    resource_last_modified: string;
    /**
     * The license id data.gouv.fr states for the dataset, `fr-lo` when this module was written.
     */
    dataset_license: string | null;
    /**
     * The extract's first line, which ends with the extraction date.
     */
    extract_header: string;
    /**
     * The SHA-1 of the bytes written.
     */
    sha1: string;
    /**
     * The SHA-1 the dataset record states, or `null` where it states none.
     */
    record_sha1: string | null;
    /**
     * The MD5 the storage host's ETag stated, read only when the record's SHA-1 disagreed with the bytes.
     */
    served_md5: string | null;
}
/**
 * The MD5 a storage host's ETag states for an object, or `null` when it sends no ETag of that shape.
 *
 * `static.data.gouv.fr` answers `etag: W/"<md5 hex>"`.
 */
export declare function readServedMD5(client: Pick<APIClient, "fetch">, url: string): Promise<string | null>;
/**
 * The newest establishment extract a dataset record lists.
 *
 * @throws When the record lists none, so a renamed resource reports itself rather than reading as no data.
 */
export declare function selectFinessExtract(dataset: DataGouvDataset): DataGouvResource & {
    filename: string;
};
/**
 * Read the dataset's API record.
 */
export declare function readFinessDataset(client: Pick<APIClient, "fetch">): Promise<DataGouvDataset>;
export interface DownloadFinessOptions {
    /**
     * Where the extract and the manifest are written.
     */
    outputDir: PathBuilderLike;
    /**
     * Download even where the manifest records the same resource and the file is on disk.
     */
    force?: boolean;
    retryDelayMs?: number;
    report?: (line: string) => void;
}
export type FetchFinessOptions = BaseFetchOptions & Pick<DownloadFinessOptions, "force">;
/**
 * The directory `#fr/adapters/finess/adapter` reads under a fetch root.
 */
export declare function finessInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
/**
 * Download the newest establishment extract into `options.outputDir` and record it in the manifest.
 *
 * Re-runnable: the transfer is skipped when the manifest records the same resource URL
 * and `last_modified` and the file is on disk at the recorded length.
 */
export declare function downloadFinessExtract(client: Pick<APIClient, "fetch">, options: DownloadFinessOptions): Promise<FetchSummary>;
/**
 * Download the FINESS establishment extract into `<outRoot>/fr-finess-overseas/`.
 *
 * The registry entry point.
 * `#fr/adapters/finess/adapter` is pointed at {@linkcode finessInputPath},
 * and reads the newest extract in it.
 */
export declare function fetchFinessOverseas(options: FetchFinessOptions, report?: (line: string) => void): Promise<FetchSummary>;
//# sourceMappingURL=finess.d.ts.map