@mailwoman/corpus 10.0.0 → 10.1.0

package/out/es/tools/fetch/catastro.js

@@ -0,0 +1,486 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvest the INSPIRE Addresses archives of the Dirección General del Catastro into the directory
+ * `#es/adapters/catastro/adapter` reads.
+ *
+ * The service is a two-level ATOM download service. The national service document at
+ * `https://www.catastro.hacienda.gob.es/INSPIRE/Addresses/ES.SDGC.AD.atom.xml` lists one entry per
+ * territorial office, each entry links that office's province feed, and a province feed lists one
+ * zipped GML per municipality:
+ *
+ *     ES.SDGC.AD.atom.xml  →  ES.SDGC.ad.atom_<pp>.xml  →  A.ES.SDGC.AD.<ppmmm>.zip
+ *
+ * Measured 2026-10-03: the service document answered http 200 with 681,783 bytes holding 55
+ * entries, sha256 `4342d37b6d5527eb7b8bebadc97966c90f1a041068ae9398b90183f2176898b9`.
+ *
+ * Five properties of this service decide the harvest's shape.
+ *
+ * 1. **Three of the entries belong to other publishers.** Fifty-two are titled
+ *    `Territorial office <pp> <name>` and are the Dirección General del Catastro's own provinces.
+ *    The other three are titled `Provincial Council of Bizkaia`, `… of Gipuzkoa` and
+ *    `… of Navarra`, which publish their own cadastres through this feed and state their own terms.
+ *    Each of those has its own address-source register row, its own license and its own adapter, so
+ *    this harvest selects the territorial offices by a positive match on their title rather than by
+ *    excluding three names. A feed that renames its offices then matches zero titles and raises.
+ * 2. **A province feed declares ISO-8859-1 and means it, while the national feed declares UTF-8.**
+ *    `ES.SDGC.ad.atom_15.xml` writes A Coruña's directory name with the byte `0xD1` for `Ñ`.
+ *    Decoding that feed as UTF-8 yields U+FFFD, and the URL built from the replacement character
+ *    answers an html error page under http 200 rather than the archive. So both levels are read as
+ *    bytes and decoded through {@linkcode decodeDeclaredXML}, which reads each document's own
+ *    declaration.
+ * 3. **An archive URL cannot be composed, and the href it is read from is not request-ready.** The
+ *    directory segment is the municipality's own name, so Madrid sits under `28900-MADRID` while
+ *    the composable `28079` answers an html page. The publisher writes that segment with literal
+ *    spaces and with non-ASCII letters, and {@linkcode archiveRequestURL} percent-encodes both.
+ * 4. **The municipality code is stated twice, and the two are checked against each other.** An
+ *    entry's title reads `55101-CEUTA addresses` and its archive is named
+ *    `A.ES.SDGC.AD.55101.zip`. The file keeps the publisher's own name rather than one built from
+ *    the code, so the code decides which entry is read and never where the file lands. A
+ *    disagreement between the publisher's two statements of it is a change in the feed's layout
+ *    rather than a municipality without a code.
+ * 5. **Every entry of every feed states one `<updated>`, the edition's publication date.** All 55
+ *    national entries and all 87 entries of `ES.SDGC.ad.atom_02.xml` read
+ *    `2026-08-21T00:00:00Z`, so the value dates the publication rather than the file. It is still
+ *    the freshness signal a re-run compares, because a new edition moves it. A skip requires the
+ *    feed to state a value: where it states none, both sides read an empty string and an equality
+ *    test would keep an archive of unknown age for as long as the feed stayed silent.
+ *
+ * A full harvest is one request for the service document, 52 for the province feeds and one per
+ * municipality. The archives are small enough to buffer: Ceuta is 354,647 bytes, A Coruña 907,574
+ * and Madrid 7,104,627, measured 2026-10-03. The harvest is dispatched serially through one
+ * `APIClient` at {@linkcode ES_CATASTRO_REQUEST_INTERVAL_MS}, and
+ * {@linkcode HarvestESCatastroOptions.provinces} and {@linkcode HarvestESCatastroOptions.limit}
+ * bound a run that is not harvesting the whole country.
+ *
+ * The archives stay compressed. `#es/adapters/catastro/adapter` reads the GML member through
+ * `inspireGMLChunks`, which inflates from the archive, and Ceuta's member is 11,861,975 bytes
+ * against its archive's 354,647.
+ */
+import { APIClient, assertNoOGCServiceException } from "@mailwoman/core/api";
+import { ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { tryStat } from "@mailwoman/core/fs/readers";
+import { decodeBytes } from "@mailwoman/core/fs/streams";
+import { makeDirectories } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { PathBuilder } from "path-ts";
+import { ES_CATASTRO_ADAPTER_ID, ES_CATASTRO_LICENSE } from "#es/adapters/catastro/adapter";
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom";
+import { loadCollectionFiles, writeManifest } from "#tools/fetch/download";
+import { downloadZipArchive } from "#tools/fetch/zip-archive";
+/**
+ * The national ATOM service document, which lists one province feed per territorial office.
+ */
+export const ES_CATASTRO_SERVICE_FEED_URL = "https://www.catastro.hacienda.gob.es/INSPIRE/Addresses/ES.SDGC.AD.atom.xml";
+/**
+ * The attribution the publisher's own rights statement requires.
+ *
+ * A province feed's `<rights>` reads `This service can be used free of charge in every instance, as
+ * long as that the D. G. of the Cadastre (Ministry of Finance) is mentioned as author and owner of
+ * the information`, so a model card carrying this source credits the office in its own language.
+ */
+export const ES_CATASTRO_ATTRIBUTION = "Dirección General del Catastro (Ministerio de Hacienda)";
+/**
+ * The minimum spacing between two requests to `catastro.hacienda.gob.es`, in milliseconds.
+ *
+ * Four requests per second against one government host.
+ * The publisher states no rate limit, and a national harvest is roughly 8,100 requests,
+ * so the harvest is paced rather than parallel.
+ */
+export const ES_CATASTRO_REQUEST_INTERVAL_MS = 250;
+/**
+ * The directory the harvest writes under, which is the adapter's `inputPath`.
+ */
+const SLUG = ES_CATASTRO_ADAPTER_ID;
+/**
+ * How many archives are written between two manifest writes.
+ *
+ * The manifest is what makes an interrupted harvest resumable, and writing it after every
+ * archive would rewrite a document with one entry per municipality once per municipality.
+ * At this interval an interruption re-fetches at most this many archives that are already on disk.
+ */
+const MANIFEST_INTERVAL = 25;
+/**
+ * How much of a document is read to find its encoding declaration.
+ */
+const DECLARATION_WINDOW = 512;
+/**
+ * The encoding an XML declaration states, read from the head of the document.
+ */
+const DECLARED_ENCODING = /<\?xml[^>]*encoding="([^"]+)"/iu;
+/**
+ * A national entry's title, `Territorial office 02 Albacete`.
+ *
+ * The three entries belonging to the foral cadastres are titled `Provincial Council of <name>`
+ * and do not match, which is how they are left to their own adapters.
+ */
+const TERRITORIAL_OFFICE_TITLE = /^Territorial office\s+(\d{2})\s+(\S.*)$/u;
+/**
+ * The province code a province feed's own file name states, `ES.SDGC.ad.atom_02.xml` → `02`.
+ */
+const PROVINCE_FEED_CODE = /atom_(\d{2})\.xml$/iu;
+/**
+ * A municipality entry's title, `55101-CEUTA addresses`.
+ */
+const MUNICIPALITY_TITLE = /^(\d{5})-(.*?)\s+addresses$/u;
+/**
+ * A municipality archive's file name, `A.ES.SDGC.AD.55101.zip`.
+ */
+const ARCHIVE_FILENAME = /^A\.ES\.SDGC\.AD\.(\d{5})\.zip$/iu;
+/**
+ * The document's text, decoded from the encoding its own declaration states.
+ *
+ * The national feed declares UTF-8 and a province feed declares ISO-8859-1, so a reader
+ * that fixed either encoding would mojibake the other publisher's accented place names.
+ * A document that declares no encoding is decoded as UTF-8, which is what XML's own default states.
+ */
+export function decodeDeclaredXML(bytes) {
+    const head = Buffer.from(bytes.subarray(0, DECLARATION_WINDOW)).toString("latin1");
+    return decodeBytes(bytes, DECLARED_ENCODING.exec(head)?.[1] ?? "utf8");
+}
+/**
+ * The URL an href is requested at.
+ *
+ * A province feed writes a municipality's directory segment as the publisher spells it,
+ * with literal spaces and with non-ASCII letters: `…/15/15900-A CORUÑA/A.ES.SDGC.AD.15900.zip`.
+ * `URL` percent-encodes both, which is what the host serves the archive at.
+ */
+export function archiveRequestURL(href) {
+    return new URL(href).toString();
+}
+/**
+ * The territorial offices the national service document lists.
+ *
+ * @throws When the document holds no entry, when it holds no territorial-office entry at all,
+ * when an office carries no province-feed link, or when two offices claim one province code.
+ * Each of those would otherwise write zero archives while reporting a completed run.
+ */
+export function readESCatastroServiceFeed(feed) {
+    if (!feed.entries.length) {
+        throw new Error(`${ES_CATASTRO_SERVICE_FEED_URL}: the service document holds no <entry>, so the territorial offices ` +
+            `it offers could not be read`);
+    }
+    const provinces = [];
+    const seen = new Set();
+    for (const entry of feed.entries) {
+        const titled = TERRITORIAL_OFFICE_TITLE.exec(entry.title.trim());
+        // An entry that is not a territorial office belongs to a foral cadastre with its own
+        // register row, license and adapter, so it is left out rather than refused.
+        if (!titled)
+            continue;
+        const code = titled[1];
+        const name = titled[2].trim();
+        // The province feed is the entry's `enclosure` link.
+        // The feed-level `describedby` link beside it is the ISO 19139 metadata record,
+        // and reading either as the other costs a request that answers XML of the wrong kind.
+        const link = linkWithRel(entry.links, "enclosure");
+        if (!link?.href) {
+            throw new Error(`${ES_CATASTRO_SERVICE_FEED_URL}: the entry titled ${stringifyJSON(entry.title)} carries no ` +
+                `rel="enclosure" link, so its province feed could not be read`);
+        }
+        const fromHref = PROVINCE_FEED_CODE.exec(link.href)?.[1];
+        if (fromHref !== undefined && fromHref !== code) {
+            throw new Error(`${ES_CATASTRO_SERVICE_FEED_URL}: the entry titled ${stringifyJSON(entry.title)} states province ` +
+                `${code} in its title and links ${link.href}, which names province ${fromHref}`);
+        }
+        if (seen.has(code)) {
+            throw new Error(`${ES_CATASTRO_SERVICE_FEED_URL}: province ${code} is listed twice, so one province feed would ` +
+                `be read in place of the other`);
+        }
+        seen.add(code);
+        provinces.push({
+            code,
+            name,
+            title: entry.title.trim(),
+            provinceFeedURL: link.href,
+            updated: entry.updated,
+        });
+    }
+    if (!provinces.length) {
+        throw new Error(`${ES_CATASTRO_SERVICE_FEED_URL}: none of the ${feed.entries.length} entries is titled ` +
+            `"Territorial office <code> <name>", so no province of the Dirección General del Catastro ` +
+            `could be selected. The titles read ${feed.entries.map((entry) => stringifyJSON(entry.title)).join(", ")}.`);
+    }
+    return provinces;
+}
+/**
+ * The municipalities one province feed lists.
+ *
+ * @throws When the feed holds no entry, when an entry carries no archive link,
+ * when the municipality code its title states disagrees with the one its archive
+ * is named for, or when two entries name one archive.
+ */
+export function readESCatastroProvinceFeed(feed, province) {
+    if (!feed.entries.length) {
+        throw new Error(`${province.provinceFeedURL}: the province feed holds no <entry>, so the municipalities of province ` +
+            `${province.code} could not be read`);
+    }
+    const datasets = [];
+    const seen = new Set();
+    for (const entry of feed.entries) {
+        const link = linkWithRel(entry.links, "enclosure");
+        if (!link?.href) {
+            throw new Error(`${province.provinceFeedURL}: the entry titled ${stringifyJSON(entry.title)} carries no ` +
+                `rel="enclosure" link, so its archive could not be read`);
+        }
+        // The publisher's own file name, taken off the href before it is percent-encoded,
+        // so the file on disk is named the way the feed names it.
+        const filename = link.href.slice(link.href.lastIndexOf("/") + 1);
+        const fromFilename = ARCHIVE_FILENAME.exec(filename)?.[1];
+        if (!fromFilename) {
+            throw new Error(`${province.provinceFeedURL}: the entry titled ${stringifyJSON(entry.title)} links ` +
+                `${stringifyJSON(filename)}, which is not named A.ES.SDGC.AD.<code>.zip`);
+        }
+        const titled = MUNICIPALITY_TITLE.exec(entry.title.trim());
+        if (!titled) {
+            throw new Error(`${province.provinceFeedURL}: the entry linking ${stringifyJSON(filename)} is titled ` +
+                `${stringifyJSON(entry.title)}, which states no municipality code, so the archive's ` +
+                `${fromFilename} could not be checked against the title`);
+        }
+        const fromTitle = titled[1];
+        if (fromTitle !== fromFilename) {
+            throw new Error(`${province.provinceFeedURL}: the entry titled ${stringifyJSON(entry.title)} states municipality ` +
+                `${fromTitle} and links an archive named for ${fromFilename}, so the municipality it offers ` +
+                `is ambiguous`);
+        }
+        if (seen.has(filename)) {
+            throw new Error(`${province.provinceFeedURL}: ${stringifyJSON(filename)} is listed twice, so one of the two ` +
+                `archives would overwrite the other`);
+        }
+        seen.add(filename);
+        datasets.push({
+            provinceCode: province.code,
+            code: fromTitle,
+            name: titled[2].trim(),
+            title: entry.title.trim(),
+            archiveURL: archiveRequestURL(link.href),
+            updated: entry.updated,
+            filename,
+        });
+    }
+    return datasets;
+}
+/**
+ * Whether the archive recorded for one municipality is still the one the province feed describes.
+ *
+ * A skip requires the feed to state an `<updated>` value.
+ * Where it states none, both sides read an empty string and an equality test would hold,
+ * which would keep an archive of unknown age for as long as the feed stayed silent.
+ */
+async function isCurrent(recorded, dataset, path, verifyDigests) {
+    if (!recorded || !dataset.updated || recorded.feed_updated !== dataset.updated)
+        return false;
+    const stat = await tryStat(path);
+    if (!stat || stat.size !== recorded.bytes)
+        return false;
+    // The digest check reads the whole file rather than its metadata, which is why it is opt-in.
+    if (!verifyDigests)
+        return true;
+    return (await sha256File(path)) === recorded.sha256;
+}
+/**
+ * Reads one ATOM document, decoded from the encoding it declares.
+ */
+async function readFeed(client, options) {
+    const { data } = await client.fetch({
+        method: "GET",
+        url: options.url,
+        responseType: "arraybuffer",
+        timeout: 120_000,
+        signal: options.signal,
+    });
+    const text = decodeDeclaredXML(Buffer.from(data));
+    // A feed shares the http 200 an exception report arrives on.
+    assertNoOGCServiceException(text, options.context);
+    return await readAtomFeed(feedChunks(text));
+}
+/**
+ * The provinces this run reads, and the codes a caller named that the service document does not list.
+ */
+function selectProvinces(listed, wanted) {
+    if (!wanted)
+        return { selected: listed, unknown: [] };
+    const byCode = new Map(listed.map((province) => [province.code, province]));
+    const selected = [];
+    const unknown = [];
+    for (const code of wanted) {
+        const province = byCode.get(code);
+        if (province) {
+            selected.push(province);
+        }
+        else {
+            unknown.push(code);
+        }
+    }
+    return { selected, unknown };
+}
+/**
+ * Harvest the municipalities the selected province feeds list into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller decides
+ * the pacing. {@linkcode fetchESCatastro} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what the feed states is already recorded, and which codes failed.
+ * @throws When the service document lists no territorial office, or
+ * when a selected province feed lists no municipality.
+ * Either would otherwise answer `{fetched: 0, skipped: 0, failed: 0}`, which a caller
+ * reads as a fetch that completed and found the publisher empty.
+ */
+export async function harvestESCatastro(client, options) {
+    const { report, signal } = options;
+    const destDir = PathBuilder.from(options.outputDir);
+    const manifestPath = destDir("MANIFEST.json");
+    report?.(`=== ${SLUG}: reading ${ES_CATASTRO_SERVICE_FEED_URL}`);
+    const service = await readFeed(client, {
+        url: ES_CATASTRO_SERVICE_FEED_URL,
+        context: `${SLUG} service document`,
+        signal,
+    });
+    const listed = readESCatastroServiceFeed(service);
+    report?.(`  ${listed.length} territorial offices listed of ${service.entries.length} entries`);
+    const provinces = selectProvinces(listed, options.provinces);
+    for (const code of provinces.unknown) {
+        report?.(`  ✗ province ${code} is not listed in the service document`);
+    }
+    // Resolved before the directory is made, so a publisher that answers an exception
+    // report leaves no empty source directory behind.
+    await makeDirectories(destDir);
+    const previous = await loadCollectionFiles(manifestPath);
+    const files = new Map();
+    // An entry for a municipality this run does not consider is carried through,
+    // so a bounded run never drops what an earlier run recorded.
+    for (const [filename, entry] of previous) {
+        files.set(filename, entry);
+    }
+    let fetched = 0;
+    let skipped = 0;
+    let municipalitiesListed = 0;
+    let provincesHarvested = 0;
+    const failedCodes = [...provinces.unknown];
+    const requested = options.municipalities === undefined ? undefined : new Set(options.municipalities);
+    const found = new Set();
+    const writeHarvestManifest = async () => {
+        const manifest = {
+            source: SLUG,
+            source_url: ES_CATASTRO_SERVICE_FEED_URL,
+            license: ES_CATASTRO_LICENSE,
+            attribution: ES_CATASTRO_ATTRIBUTION,
+            downloaded_at: new Date().toISOString(),
+            provinces_listed: listed.length,
+            provinces_harvested: provincesHarvested,
+            municipalities_listed: municipalitiesListed,
+            files: [...files.values()].toSorted((left, right) => left.filename < right.filename ? -1 : left.filename > right.filename ? 1 : 0),
+        };
+        await writeManifest(manifestPath, manifest);
+    };
+    for (const province of provinces.selected) {
+        if (signal?.aborted)
+            break;
+        if (options.limit !== undefined && fetched + skipped >= options.limit)
+            break;
+        report?.(`  province ${province.code} ${province.name}: reading ${province.provinceFeedURL}`);
+        const provinceFeed = await readFeed(client, {
+            url: province.provinceFeedURL,
+            context: `${SLUG} province feed ${province.code}`,
+            signal,
+        });
+        const municipalities = readESCatastroProvinceFeed(provinceFeed, province);
+        provincesHarvested++;
+        municipalitiesListed += municipalities.length;
+        report?.(`    ${municipalities.length} municipalities listed`);
+        for (const dataset of municipalities) {
+            if (signal?.aborted)
+                break;
+            if (options.limit !== undefined && fetched + skipped >= options.limit)
+                break;
+            if (requested && !requested.has(dataset.code))
+                continue;
+            found.add(dataset.code);
+            const dest = destDir(dataset.filename);
+            if (await isCurrent(files.get(dataset.filename), dataset, dest, options.verifyDigests ?? false)) {
+                skipped++;
+                continue;
+            }
+            try {
+                const delivered = await downloadZipArchive(client, {
+                    url: dataset.archiveURL,
+                    dest,
+                    timeout: 600_000,
+                    signal,
+                });
+                files.set(dataset.filename, {
+                    province_code: dataset.provinceCode,
+                    municipality_code: dataset.code,
+                    filename: dataset.filename,
+                    source_url: dataset.archiveURL,
+                    downloaded_at: new Date().toISOString(),
+                    sha256: delivered.sha256,
+                    bytes: delivered.bytes,
+                    feed_updated: dataset.updated,
+                    last_modified: delivered.lastModified,
+                });
+                fetched++;
+                report?.(`    ✓ ${dataset.code} ${ByteFormatter.formatIEC(delivered.bytes)} sha256=${delivered.sha256}`);
+            }
+            catch (error) {
+                report?.(`    ✗ ${dataset.code}: ${error instanceof Error ? error.message : String(error)}`);
+                failedCodes.push(dataset.code);
+                continue;
+            }
+            if (fetched % MANIFEST_INTERVAL === 0) {
+                await writeHarvestManifest();
+            }
+        }
+    }
+    // A municipality a caller named and no selected province feed listed is reported
+    // rather than dropped, because a municipality that is not published is a different
+    // condition from a selection that holds no municipality.
+    for (const code of requested ?? []) {
+        if (found.has(code))
+            continue;
+        report?.(`  ✗ municipality ${code} is not listed by any province feed this run read`);
+        failedCodes.push(code);
+    }
+    await writeHarvestManifest();
+    report?.(`=== ${SLUG} summary`);
+    report?.(`fetched: ${fetched}`);
+    report?.(`skipped: ${skipped} (the province feed states the publication date already recorded)`);
+    report?.(`failed:  ${failedCodes.length}`);
+    return { fetched, skipped, failed: failedCodes.length, failedCodes };
+}
+/**
+ * The path `#es/adapters/catastro/adapter` reads, given the root a fetch wrote under.
+ *
+ * The adapter takes one archive or a directory holding them, and a harvest writes a directory.
+ */
+export function esCatastroInputPath(outRoot) {
+    return outRoot(SLUG);
+}
+/**
+ * Harvest the Dirección General del Catastro's INSPIRE Addresses archives into `<outRoot>/es-catastro/`.
+ *
+ * Re-runnable: a municipality whose recorded publication date is still the one its province
+ * feed states, and whose archive is still on disk at the recorded length, costs no request.
+ */
+export async function fetchESCatastro(options, report) {
+    await using client = new APIClient({
+        displayName: SLUG,
+        minRequestIntervalMs: options.minRequestIntervalMs ?? ES_CATASTRO_REQUEST_INTERVAL_MS,
+        retry: true,
+    });
+    // Awaited rather than returned: `await using` disposes the client when this scope exits,
+    // and a disposed `APIClient` refuses every later request.
+    return await harvestESCatastro(client, {
+        outputDir: options.outRoot(SLUG),
+        provinces: options.provinces,
+        municipalities: options.municipalities,
+        limit: options.limit,
+        verifyDigests: options.verifyDigests,
+        signal: options.signal,
+        report,
+    });
+}
+//# sourceMappingURL=catastro.js.map

package/out/es/tools/fetch/catastro.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catastro.js","sourceRoot":"","sources":["../../../../lib/es/tools/fetch/catastro.ts"],"names":[],"mappings":"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"}

package/out/es/tools/fetch/gipuzkoa.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Downloads the INSPIRE Addresses theme the Diputación Foral de Gipuzkoa publishes for the whole
+ *   province.
+ *
+ *   ## One feed, one entry, one archive
+ *
+ *   The ATOM download service at `https://b5m.gipuzkoa.eus/inspire/download/addresses.xml` holds a
+ *   single entry covering the province rather than one entry per municipality, so the resolution is
+ *   one request:
+ *
+ *       addresses.xml  →  GML/ES.GFA.AD.zip
+ *
+ *   That entry links its dataset through `rel="alternate"`. It carries no `rel="enclosure"` link at
+ *   all, and the `rel="describedby"` link beside the alternate is the ISO 19139 metadata record. A
+ *   reader that looks for an enclosure therefore finds no dataset here, and a reader that takes the
+ *   first link of any relation downloads the metadata record instead of 7,959,103 bytes of
+ *   addresses. {@linkcode resolveGipuzkoaArchive} asks for the alternate by name.
+ *
+ *   ## The entry's `<updated>` is not a freshness signal
+ *
+ *   The entry states `<updated>2017-01-01T08:08:00Z</updated>` while the archive it links was last
+ *   modified 2026-08-08, and the entry's own summary states a weekly refresh. The feed's value has
+ *   therefore not moved across at least one refresh, so comparing it against a recorded copy would
+ *   keep one archive forever. The archive's HTTP `last-modified` is the signal this fetcher compares,
+ *   and {@linkcode gipuzkoaPublicationIsRecorded} requires the publisher to state one before it
+ *   agrees to skip a download. The feed's value is recorded beside it, unused, because it is what
+ *   the publisher says about the dataset.
+ *
+ *   ## Why the archive stays compressed
+ *
+ *   `#es/adapters/gipuzkoa/adapter` reads the member through `inspireGMLChunks`, which inflates from
+ *   the archive. The member `ES.GFA.AD.gml` is 313,162,472 bytes against the archive's 7,959,103, so
+ *   unpacking it here would cost 39 times the disk for no reader that wants it.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { type PathBuilderLike } from "path-ts";
+import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetch/download";
+/**
+ * The ATOM download service for the province's Addresses theme.
+ */
+export declare const ES_GIPUZKOA_SERVICE_URL = "https://b5m.gipuzkoa.eus/inspire/download/addresses.xml";
+/**
+ * The name the archive is written under, which is what the adapter's `inputPath` states.
+ */
+export declare const ES_GIPUZKOA_ARCHIVE_FILENAME = "ES.GFA.AD.zip";
+/**
+ * The attribution the publisher's own `<rights>` element requires, quoted as the English feed writes it.
+ *
+ * The feed's subtitle states the same requirement under the publisher's Basque
+ * name, `Gipuzkoako Foru Aldundia`.
+ */
+export declare const ES_GIPUZKOA_ATTRIBUTION = "\u00AB\u00A9 Gipuzkoa Provincial Council\u00BB";
+/**
+ * What one run recorded.
+ *
+ * `last_modified` is the header the download was decided on.
+ * `feed_updated` is the entry's own `<updated>`, recorded rather than compared,
+ * because this publisher's value has not moved since 2017.
+ */
+export interface GipuzkoaManifest extends SourceManifest {
+    service_url: string;
+    last_modified: string | null;
+    feed_updated: string | null;
+    attribution: string;
+}
+/**
+ * Per-invocation options.
+ */
+export interface DownloadGipuzkoaOptions {
+    outputDir: PathBuilderLike;
+    /**
+     * Downloads the archive even where the publisher reports the recorded `last-modified`.
+     */
+    force?: boolean;
+    retries?: number;
+    retryDelayMs?: number;
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}
+/**
+ * Where the archive is, and what the feed states about the entry that links it.
+ */
+export interface GipuzkoaArchiveReference {
+    archiveURL: string;
+    /**
+     * The entry's title, which states the theme rather than a municipality.
+     */
+    entryTitle: string;
+    /**
+     * The entry's own `<updated>`, or `null` where the entry states none.
+     */
+    feedUpdated: string | null;
+}
+/**
+ * Resolves the download service to the one archive its single entry links.
+ *
+ * Raises where the feed lists no entry, and where the entry carries no `rel="alternate"` link.
+ * The alternative would return `{fetched: 0, skipped: 0, failed: 0}`, which a caller
+ * reads as a fetch that completed and found the publisher empty.
+ *
+ * Separate from {@linkcode downloadGipuzkoa} because the resolution is the part a test can drive.
+ * The download runs on global `fetch`, which a unit test cannot intercept.
+ */
+export declare function resolveGipuzkoaArchive(client: Pick<APIClient, "fetch">, options?: {
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}): Promise<GipuzkoaArchiveReference>;
+/**
+ * What the publisher's HEAD response states about the archive it holds.
+ *
+ * Both fields read `null` where the header is absent, rather than an empty string or zero.
+ * An absent `last-modified` is the service declining to state a version, which is a
+ * different fact from a version that happens to match the one on disk.
+ */
+export interface GipuzkoaPublication {
+    lastModified: string | null;
+    reportedBytes: number | null;
+}
+/**
+ * Reads the publisher's HEAD response for one archive URL.
+ *
+ * Separate from {@linkcode downloadGipuzkoa} for the same reason {@linkcode resolveGipuzkoaArchive}
+ * is: this request carries the whole freshness decision.
+ */
+export declare function readGipuzkoaPublication(client: Pick<APIClient, "fetch">, archiveURL: string, options?: {
+    signal?: AbortSignal;
+}): Promise<GipuzkoaPublication>;
+/**
+ * Whether the archive on disk is the one the publisher now serves.
+ *
+ * A publisher that states no `last-modified` answers false.
+ * Comparing an absent header against an absent recorded value makes `null === null` hold,
+ * and that reading keeps a stale archive for as long as the service stays silent.
+ */
+export declare function gipuzkoaPublicationIsRecorded(recorded: GipuzkoaManifest, bytesOnDisk: number, publication: GipuzkoaPublication): boolean;
+/**
+ * Resolves the feed to its one archive and downloads it unless the publisher's
+ * `last-modified` and the file on disk already agree with the manifest.
+ */
+export declare function downloadGipuzkoa(client: Pick<APIClient, "fetch">, options: DownloadGipuzkoaOptions): Promise<FetchSummary>;
+/**
+ * The path `#es/adapters/gipuzkoa/adapter` reads, given the root a fetch wrote under.
+ */
+export declare function esGipuzkoaInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
+/**
+ * Per-invocation options for the registry entry.
+ */
+export interface FetchESGipuzkoaOptions extends BaseFetchOptions {
+    force?: boolean;
+    retries?: number;
+    retryDelayMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * The registry entry.
+ */
+export declare function fetchESGipuzkoa(options: FetchESGipuzkoaOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=gipuzkoa.d.ts.map