@mailwoman/corpus 9.4.0 → 10.1.0

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

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

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

@@ -0,0 +1,209 @@
+/**
+ * @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, assertNoOGCServiceException } from "@mailwoman/core/api";
+import { ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { tryStat } from "@mailwoman/core/fs/readers";
+import { makeDirectories } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { PathBuilder } from "path-ts";
+import { ES_GIPUZKOA_ADAPTER_ID } from "#es/adapters/gipuzkoa/adapter";
+import { feedChunks, linkWithRel, readAtomFeed } from "#tools/fetch/atom";
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download";
+/**
+ * The ATOM download service for the province's Addresses theme.
+ */
+export 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 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 const ES_GIPUZKOA_ATTRIBUTION = "«© Gipuzkoa Provincial Council»";
+const SLUG = ES_GIPUZKOA_ADAPTER_ID;
+/**
+ * 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 async function resolveGipuzkoaArchive(client, options = {}) {
+    const { report } = options;
+    report?.(`=== ${SLUG}: reading ${ES_GIPUZKOA_SERVICE_URL}`);
+    const { data: feedXML } = await client.fetch({
+        method: "GET",
+        url: ES_GIPUZKOA_SERVICE_URL,
+        responseType: "text",
+        timeout: 120_000,
+        signal: options.signal,
+    });
+    assertNoOGCServiceException(String(feedXML), `${SLUG} download service`);
+    const feed = await readAtomFeed(feedChunks(String(feedXML)));
+    const entry = feed.entries[0];
+    if (!entry) {
+        throw new Error(`${SLUG}: ${ES_GIPUZKOA_SERVICE_URL} holds no <entry>, so the archive covering the province ` +
+            `could not be resolved.`);
+    }
+    // The alternate by name rather than the entry's first link: the `describedby` link beside it
+    // addresses the ISO 19139 record, and downloading that would store metadata under a `.zip` name.
+    const link = linkWithRel(entry.links, "alternate");
+    if (!link?.href) {
+        throw new Error(`${SLUG}: the entry titled "${entry.title}" carries no rel="alternate" link, so its dataset ` +
+            `could not be resolved. Its links are ` +
+            `${entry.links.length ? entry.links.map((each) => `${each.rel || "no rel"}=${each.href}`).join(", ") : "absent"}.`);
+    }
+    report?.(`  archive: ${link.href}`);
+    return {
+        archiveURL: link.href,
+        entryTitle: entry.title,
+        feedUpdated: entry.updated || 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 async function readGipuzkoaPublication(client, archiveURL, options = {}) {
+    const head = await client.fetch({
+        method: "HEAD",
+        url: archiveURL,
+        timeout: 120_000,
+        signal: options.signal,
+    });
+    const headers = head.headers;
+    const reported = Number(headers?.["content-length"] ?? Number.NaN);
+    return {
+        lastModified: String(headers?.["last-modified"] ?? "") || null,
+        reportedBytes: Number.isFinite(reported) ? reported : null,
+    };
+}
+/**
+ * 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 function gipuzkoaPublicationIsRecorded(recorded, bytesOnDisk, publication) {
+    if (publication.lastModified === null)
+        return false;
+    return recorded.last_modified === publication.lastModified && recorded.bytes === bytesOnDisk;
+}
+/**
+ * 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 async function downloadGipuzkoa(client, options) {
+    const { report } = options;
+    const destDir = PathBuilder.from(options.outputDir);
+    const archivePath = destDir(ES_GIPUZKOA_ARCHIVE_FILENAME);
+    const manifestPath = destDir("MANIFEST.json");
+    // Resolved before the directory is made, so a publisher that answers with an
+    // exception report leaves no empty source directory behind.
+    const { archiveURL, feedUpdated } = await resolveGipuzkoaArchive(client, {
+        signal: options.signal,
+        report,
+    });
+    const publication = await readGipuzkoaPublication(client, archiveURL, { signal: options.signal });
+    report?.(`  HEAD: ${publication.reportedBytes === null ? "no content-length" : ByteFormatter.formatIEC(publication.reportedBytes)}` +
+        `, last-modified ${publication.lastModified ?? "unstated"}`);
+    await makeDirectories(destDir);
+    const recorded = await readManifest(manifestPath);
+    const stat = await tryStat(archivePath);
+    if (!options.force && recorded && stat && gipuzkoaPublicationIsRecorded(recorded, stat.size, publication)) {
+        report?.(`  present, and the publisher's last-modified is unchanged`);
+        return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] };
+    }
+    const { bytes } = await downloadToFile({
+        url: archiveURL,
+        dest: archivePath,
+        retries: options.retries,
+        retryDelayMs: options.retryDelayMs,
+        report,
+    });
+    const sha256 = await sha256File(archivePath);
+    report?.(`  ✓ ${ByteFormatter.formatIEC(bytes)}  sha256=${sha256}`);
+    const manifest = {
+        source_url: archiveURL,
+        service_url: ES_GIPUZKOA_SERVICE_URL,
+        filename: ES_GIPUZKOA_ARCHIVE_FILENAME,
+        bytes,
+        sha256,
+        last_modified: publication.lastModified,
+        feed_updated: feedUpdated,
+        attribution: ES_GIPUZKOA_ATTRIBUTION,
+        downloaded_at: new Date().toISOString(),
+    };
+    await writeManifest(manifestPath, manifest);
+    report?.(`  MANIFEST written to ${manifestPath}`);
+    return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] };
+}
+/**
+ * The path `#es/adapters/gipuzkoa/adapter` reads, given the root a fetch wrote under.
+ */
+export function esGipuzkoaInputPath(outRoot) {
+    return outRoot(SLUG, ES_GIPUZKOA_ARCHIVE_FILENAME);
+}
+/**
+ * The registry entry.
+ */
+export async function fetchESGipuzkoa(options, report) {
+    await using client = new APIClient({ displayName: SLUG, 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 downloadGipuzkoa(client, {
+        outputDir: options.outRoot(SLUG),
+        force: options.force,
+        retries: options.retries,
+        retryDelayMs: options.retryDelayMs,
+        signal: options.signal,
+        report,
+    });
+}
+//# sourceMappingURL=gipuzkoa.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gipuzkoa.js","sourceRoot":"","sources":["../../../../lib/es/tools/fetch/gipuzkoa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,SAAS,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAA;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAwB,MAAM,SAAS,CAAA;AAE3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEnF;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,yDAAyD,CAAA;AAEhG;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,iCAAiC,CAAA;AAExE,MAAM,IAAI,GAAG,sBAAsB,CAAA;AA8CnC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC3C,MAAgC,EAChC,OAAO,GAA8D,EAAE;IAEvE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAE1B,MAAM,EAAE,CAAC,OAAO,IAAI,aAAa,uBAAuB,EAAE,CAAC,CAAA;IAE3D,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAS;QACpD,MAAM,EAAE,KAAK;QACb,GAAG,EAAE,uBAAuB;QAC5B,YAAY,EAAE,MAAM;QACpB,OAAO,EAAE,OAAO;QAChB,MAAM,EAAE,OAAO,CAAC,MAAM;KACtB,CAAC,CAAA;IAEF,2BAA2B,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,mBAAmB,CAAC,CAAA;IAExE,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;IAE7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACd,GAAG,IAAI,KAAK,uBAAuB,0DAA0D;YAC5F,wBAAwB,CACzB,CAAA;IACF,CAAC;IAED,6FAA6F;IAC7F,iGAAiG;IACjG,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;IAElD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACd,GAAG,IAAI,uBAAuB,KAAK,CAAC,KAAK,oDAAoD;YAC5F,uCAAuC;YACvC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CACnH,CAAA;IACF,CAAC;IAED,MAAM,EAAE,CAAC,cAAc,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IAEnC,OAAO;QACN,UAAU,EAAE,IAAI,CAAC,IAAI;QACrB,UAAU,EAAE,KAAK,CAAC,KAAK;QACvB,WAAW,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;KAClC,CAAA;AACF,CAAC;AAcD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC5C,MAAgC,EAChC,UAAkB,EAClB,OAAO,GAA6B,EAAE;IAEtC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,KAAK,CAAU;QACxC,MAAM,EAAE,MAAM;QACd,GAAG,EAAE,UAAU;QACf,OAAO,EAAE,OAAO;QAChB,MAAM,EAAE,OAAO,CAAC,MAAM;KACtB,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,IAAI,CAAC,OAA6C,CAAA;IAClE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,gBAAgB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAA;IAElE,OAAO;QACN,YAAY,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC,IAAI,IAAI;QAC9D,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;KAC1D,CAAA;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAC5C,QAA0B,EAC1B,WAAmB,EACnB,WAAgC;IAEhC,IAAI,WAAW,CAAC,YAAY,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAEnD,OAAO,QAAQ,CAAC,aAAa,KAAK,WAAW,CAAC,YAAY,IAAI,QAAQ,CAAC,KAAK,KAAK,WAAW,CAAA;AAC7F,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,MAAgC,EAChC,OAAgC;IAEhC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IAC1B,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACnD,MAAM,WAAW,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAA;IACzD,MAAM,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAE7C,6EAA6E;IAC7E,4DAA4D;IAC5D,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,MAAM,sBAAsB,CAAC,MAAM,EAAE;QACxE,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;KACN,CAAC,CAAA;IAEF,MAAM,WAAW,GAAG,MAAM,uBAAuB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAEjG,MAAM,EAAE,CACP,WAAW,WAAW,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE;QACzH,mBAAmB,WAAW,CAAC,YAAY,IAAI,UAAU,EAAE,CAC5D,CAAA;IAED,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IAE9B,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAmB,YAAY,CAAC,CAAA;IACnE,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IAEvC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,QAAQ,IAAI,IAAI,IAAI,6BAA6B,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC;QAC3G,MAAM,EAAE,CAAC,2DAA2D,CAAC,CAAA;QAErE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;IAC9D,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC;QACtC,GAAG,EAAE,UAAU;QACf,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM;KACN,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAA;IAE5C,MAAM,EAAE,CAAC,OAAO,aAAa,CAAC,SAAS,CAAC,KAAK,CAAC,YAAY,MAAM,EAAE,CAAC,CAAA;IAEnE,MAAM,QAAQ,GAAqB;QAClC,UAAU,EAAE,UAAU;QACtB,WAAW,EAAE,uBAAuB;QACpC,QAAQ,EAAE,4BAA4B;QACtC,KAAK;QACL,MAAM;QACN,aAAa,EAAE,WAAW,CAAC,YAAY;QACvC,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,uBAAuB;QACpC,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACvC,CAAA;IAED,MAAM,aAAa,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAA;IAE3C,MAAM,EAAE,CAAC,yBAAyB,YAAY,EAAE,CAAC,CAAA;IAEjD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAoC;IACvE,OAAO,OAAO,CAAC,IAAI,EAAE,4BAA4B,CAAC,CAAA;AACnD,CAAC;AAYD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,OAA+B,EAC/B,MAA+B;IAE/B,YAAY,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,yFAAyF;IACzF,0DAA0D;IAC1D,OAAO,MAAM,gBAAgB,CAAC,MAAM,EAAE;QACrC,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;KACN,CAAC,CAAA;AACH,CAAC"}

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

@@ -0,0 +1,189 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvest the INSPIRE Addresses archives the Gobierno de Navarra publishes into the directory
+ * `#es/adapters/navarra/adapter` reads.
+ *
+ * The service is one ATOM document rather than two levels. The service document at
+ * `https://filescartografia.navarra.es/2_CARTOGRAFIA_TEMATICA/2_7_CATASTRO/2_7_3_INSPIRE_ATOM/2_7_3_3_AD/Addresses_ServiceATOM_Navarra.xml`
+ * lists one entry per partition, and each entry links that partition's zipped GML directly.
+ * Measured 2026-10-03: the document answered http 200 with 671,131 bytes holding 272 entries,
+ * sha256 `6971dd61d87e2fc047e953e956b09c6cc88aaa92e16ffb3bbc4750a1edb1ab60`.
+ *
+ * Four properties of this service decide the harvest's shape.
+ *
+ * 1. **The archive link is the `enclosure` link, and the `alternate` link is not it.** Each entry
+ *    carries six links, three of which address the same archive under `enclosure`, `section` and
+ *    `alternate`. The entry's *first* `alternate` link is the relative href
+ *    `Addresses_DatasetATOM_Navarra.xml`, which is the dataset feed, so a reader taking the first
+ *    `alternate` link downloads an ATOM document in place of the archive. This harvest takes
+ *    `enclosure` and refuses an entry that carries none.
+ * 2. **An entry leaves its own area unstated.** Every one of the 272 entries is titled
+ *    `Address Navarra` and every `<id>` is empty, so the archive's own file name,
+ *    `AD_Navarra_<n>.gml.zip`, is the only statement of which partition an entry offers. The
+ *    numbers are not contiguous: the 272 published partitions run from 1 to 908. A partition
+ *    therefore cannot be selected by place from the feed, and this module claims no mapping from a
+ *    partition number to a municipality.
+ * 3. **The `length` attribute is one number repeated.** All 272 entries claim 34,987 bytes, while
+ *    partition 1 delivers 7,476. Every byte count this module records is counted off the delivered
+ *    body.
+ * 4. **Every entry states one `<updated>`, which is also the feed's own.** All 272 read
+ *    `2026-04-14T12:06:58Z`, 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 273 requests and roughly 10 MB: a systematic sample of 10 of the 272 archives
+ * on 2026-10-03 ran from 7,476 to 112,830 bytes. The harvest is bound by round trips rather than by
+ * bandwidth and is dispatched serially through one `APIClient` at
+ * {@linkcode ES_NAVARRA_REQUEST_INTERVAL_MS}.
+ *
+ * The archives stay compressed. `#es/adapters/navarra/adapter` reads the GML member through
+ * `inspireGMLChunks`, which inflates from the archive, and partition 1's member is 307,117 bytes
+ * against its archive's 7,476.
+ */
+import { APIClient } from "@mailwoman/core/api";
+import { type PathBuilderLike } from "path-ts";
+import type { AtomFeed } from "#tools/fetch/atom";
+import type { BaseFetchOptions, FetchSummary, SourceCollectionManifest, SourceManifest } from "#tools/fetch/download";
+/**
+ * The ATOM service document, which lists one zipped GML partition per entry.
+ */
+export declare const ES_NAVARRA_SERVICE_FEED_URL = "https://filescartografia.navarra.es/2_CARTOGRAFIA_TEMATICA/2_7_CATASTRO/2_7_3_INSPIRE_ATOM/2_7_3_3_AD/Addresses_ServiceATOM_Navarra.xml";
+/**
+ * The attribution the publisher's license requires.
+ *
+ * Every entry's `<rights>` elects `Creative Commons Attribution 4.0 International (CC BY 4.0)`,
+ * whose attribution clause requires naming the creator, so a model card carrying
+ * this source credits the publisher.
+ */
+export declare const ES_NAVARRA_ATTRIBUTION = "Gobierno de Navarra";
+/**
+ * The minimum spacing between two requests to `filescartografia.navarra.es`, in milliseconds.
+ *
+ * Four requests per second against one government host.
+ * The publisher states no rate limit, and a full harvest is 273 requests.
+ */
+export declare const ES_NAVARRA_REQUEST_INTERVAL_MS = 250;
+/**
+ * One partition, as the service document states it.
+ */
+export interface ESNavarraPartition {
+    /**
+     * The partition number the archive's file name states.
+     *
+     * Kept as the digits the publisher wrote rather than as a number, because it
+     * is part of a file name rather than a quantity.
+     */
+    partition: string;
+    /**
+     * The entry's title, which reads `Address Navarra` on every entry.
+     */
+    title: string;
+    /**
+     * The entry's `<updated>`, which dates the publication.
+     */
+    updated: string;
+    archiveURL: string;
+    /**
+     * The file name the archive is written under, which is the name the publisher gave it
+     * and the name the adapter globs.
+     */
+    filename: string;
+}
+/**
+ * The partitions the service document lists.
+ *
+ * @throws When the document holds no entry, when an entry carries no `enclosure` link, when a
+ * linked archive is not named `AD_Navarra_<n>.gml.zip`, or when two entries name one archive.
+ * Each of those would otherwise write zero archives while reporting a completed run.
+ */
+export declare function readESNavarraServiceFeed(feed: AtomFeed): readonly ESNavarraPartition[];
+/**
+ * One archive, as the harvest's manifest records it.
+ */
+export interface ESNavarraArchiveEntry extends SourceManifest {
+    partition: string;
+    /**
+     * The `<updated>` the service document stated when this archive was fetched.
+     *
+     * A later run that reads the same value leaves the file alone.
+     * The publisher moves it when it publishes a new edition.
+     */
+    feed_updated: string;
+    /**
+     * The `Last-Modified` the host served the archive under, or `null` where it served none.
+     */
+    last_modified: string | null;
+}
+/**
+ * The harvest's `MANIFEST.json`.
+ */
+export interface ESNavarraHarvestManifest extends SourceCollectionManifest {
+    /**
+     * How many partitions the service document listed when this manifest was written.
+     *
+     * The denominator for `files`, read from the feed on each run rather than fixed here.
+     */
+    partitions_listed: number;
+    files: ESNavarraArchiveEntry[];
+}
+export interface HarvestESNavarraOptions {
+    /**
+     * Where the archives and the manifest are written, which is the adapter's `inputPath`.
+     */
+    outputDir: PathBuilderLike;
+    /**
+     * Harvest only these partition numbers, for a probe or for a repair of named partitions.
+     *
+     * A number the service document does not list is reported as a failure rather than ignored.
+     */
+    partitions?: readonly string[];
+    /**
+     * Stop after this many partitions, counting the ones already on disk.
+     */
+    limit?: number;
+    /**
+     * Re-read the sha256 of every archive already on disk instead of comparing its byte count.
+     *
+     * The default compares the recorded byte count against the file's size, which is one `stat`.
+     */
+    verifyDigests?: boolean;
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}
+/**
+ * Harvest the partitions the service document lists into `options.outputDir`.
+ *
+ * The client is injected so the harvest is testable without the network and so a caller decides
+ * the pacing. {@linkcode fetchESNavarra} is the registry entry point and supplies both.
+ *
+ * @returns What was fetched, what the feed states is already recorded, and which partitions failed.
+ * @throws When the service document lists no partition, which would otherwise answer
+ * `{fetched: 0, skipped: 0, failed: 0}` and read to a caller as a completed fetch of an empty publisher.
+ */
+export declare function harvestESNavarra(client: Pick<APIClient, "fetch">, options: HarvestESNavarraOptions): Promise<FetchSummary>;
+/**
+ * The path `#es/adapters/navarra/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 declare function esNavarraInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
+export interface FetchESNavarraOptions extends BaseFetchOptions, Pick<HarvestESNavarraOptions, "partitions" | "limit" | "verifyDigests" | "signal"> {
+    /**
+     * The minimum spacing between two requests, in milliseconds.
+     *
+     * Defaults to {@linkcode ES_NAVARRA_REQUEST_INTERVAL_MS}.
+     */
+    minRequestIntervalMs?: number;
+}
+/**
+ * Harvest the Gobierno de Navarra's INSPIRE Addresses partitions into `<outRoot>/es-navarra/`.
+ *
+ * Re-runnable: a partition whose recorded publication date is still the one the feed states,
+ * and whose archive is still on disk at the recorded length, costs no request.
+ */
+export declare function fetchESNavarra(options: FetchESNavarraOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=navarra.d.ts.map

package/out/es/tools/fetch/navarra.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navarra.d.ts","sourceRoot":"","sources":["../../../../lib/es/tools/fetch/navarra.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,SAAS,EAA+B,MAAM,qBAAqB,CAAA;AAM5E,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,SAAS,CAAA;AAG3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAIrH;;GAEG;AACH,eAAO,MAAM,2BAA2B,4IACkG,CAAA;AAE1I;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,wBAAwB,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,MAAM,CAAA;AAoBjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,kBAAkB,EAAE,CAsDtF;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IAC5D,SAAS,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB;IACzE;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAA;IACzB,KAAK,EAAE,qBAAqB,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,SAAS,EAAE,eAAe,CAAA;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAC/B;AAiED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACrC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,YAAY,CAAC,CAmHvB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,CAAC,SAAS,CAAC,GAAG,eAAe,CAExF;AAED,MAAM,WAAW,qBAChB,SAAQ,gBAAgB,EAAE,IAAI,CAAC,uBAAuB,EAAE,YAAY,GAAG,OAAO,GAAG,eAAe,GAAG,QAAQ,CAAC;IAC5G;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CACnC,OAAO,EAAE,qBAAqB,EAC9B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CAiBvB"}