/** * @copyright Sister Software * @license AGPL-3.0 * @author Teffen Ellis, et al. * * Download the overseas records of the Annuaire de l'éducation for the * `fr-annuaire-education-overseas` adapter. * * The education ministry publishes the directory as the OpenDataSoft dataset * `fr-en-annuaire-education` on `data.education.gouv.fr`. Its Explore API v2.1 serves the catalog * record (license, `modified`, record count) at `/api/explore/v2.1/catalog/datasets/` and a whole * or filtered export at `/exports/jsonl?where=`. The fetcher asks the export for the overseas * departments the adapter reads, which is 3,145 records of the dataset's 68,564 on 2026-10-03, and * writes them as JSON Lines. * * Two checks keep a short transfer from reading as a small directory. The records endpoint is asked * for the `total_count` of the same filter before the export, and the written file must hold exactly * that many lines. A mismatch removes the file and fails the fetch. A re-run compares the catalog * record's `modified` against the manifest and makes no transfer when they agree and the file is on * disk at the recorded length. */ import { APIClient } from "@mailwoman/core/api"; import { type PathBuilderLike } from "path-ts"; import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download"; /** * The dataset's id on `data.education.gouv.fr`. */ export declare const ANNUAIRE_EDUCATION_DATASET_ID = "fr-en-annuaire-education"; /** * The dataset's Explore API v2.1 root. */ export declare const ANNUAIRE_EDUCATION_API_URL = "https://data.education.gouv.fr/api/explore/v2.1/catalog/datasets/fr-en-annuaire-education"; /** * The dataset's page, which states the license. */ export declare const ANNUAIRE_EDUCATION_PAGE_URL = "https://data.education.gouv.fr/explore/dataset/fr-en-annuaire-education/"; /** * The file the export is written to, which is the adapter's input. */ export declare const ANNUAIRE_EDUCATION_FILENAME = "fr-en-annuaire-education-overseas.jsonl"; /** * The ODSQL filter selecting the overseas departments the adapter reads. */ export declare function annuaireOverseasFilter(): string; /** * The export URL for the overseas records, as JSON Lines. */ export declare function annuaireExportURL(): string; /** * The records URL that answers how many records the overseas filter selects. */ export declare function annuaireCountURL(): string; /** * The fields of the catalog record the fetcher reads. */ export interface AnnuaireCatalogRecord { metas?: { default?: { modified?: string; license?: string; license_url?: string; publisher?: string; records_count?: number; }; }; } /** * What the manifest records for the export, beyond {@linkcode SourceManifest}'s five fields. */ export interface AnnuaireExportManifest extends SourceManifest { /** * The catalog record's `modified`, which the re-run check compares. */ dataset_modified: string; dataset_license: string | null; dataset_license_url: string | null; /** * The record count the filter selected, which the written line count matched. */ records: number; } /** * Read the catalog record's `modified`, license and publisher. * * @throws When the record states no `modified`, because the re-run check would * then read every run as current. */ export declare function readAnnuaireCatalog(client: Pick): Promise<{ modified: string; license: string | null; licenseURL: string | null; }>; /** * Read how many records the overseas filter selects. * * @throws When the endpoint answers no `total_count`. */ export declare function readAnnuaireOverseasCount(client: Pick): Promise; /** * The number of non-empty lines in a JSON Lines file, read as a stream. */ export declare function countJSONLines(path: PathBuilderLike): Promise; export interface DownloadAnnuaireOptions { /** * Where the export and the manifest are written. */ outputDir: PathBuilderLike; /** * Download even where the catalog's `modified` matches the manifest. */ force?: boolean; retryDelayMs?: number; report?: (line: string) => void; } export type FetchAnnuaireEducationOptions = BaseFetchOptions & Pick; /** * The file `#fr/adapters/annuaire-education/adapter` reads under a fetch root. */ export declare function annuaireEducationInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike; /** * Export the overseas records into `options.outputDir` and record the export in the manifest. */ export declare function downloadAnnuaireEducation(client: Pick, options: DownloadAnnuaireOptions): Promise; /** * Export the overseas records of the Annuaire de l'éducation into `/fr-annuaire-education-overseas/`. * * The registry entry point. */ export declare function fetchAnnuaireEducationOverseas(options: FetchAnnuaireEducationOptions, report?: (line: string) => void): Promise; //# sourceMappingURL=annuaire-education.d.ts.map