@mailwoman/corpus 9.4.0 → 10.1.0

package/out/sk/adapters/inspire/adapter.js

@@ -0,0 +1,318 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * `sk-inspire`: the INSPIRE Addresses theme the Slovak Ministry of the Interior publishes out of the
+ * national address register, read from saved pages of its Web Feature Service.
+ *
+ * The service is `https://rageo.minv.sk/geoserver/ad/wfs`, a GeoServer WFS 2.0 that advertises
+ * `ImplementsResultPaging` and serves all five AD feature types. Measured 2026-10-02, a
+ * `GetFeature` for `ad:Address` answers `numberMatched="1704196"`, and the other four types hold
+ * 29,315 `ad:ThoroughfareName`, 3,015 `ad:AdminUnitName`, 1,769 `ad:AddressAreaName` and 1,415
+ * `ad:PostalDescriptor`. Acquisition pages each type into its own document and the adapter reads a
+ * directory of those pages, so a build harvests the service once and reads the saved bytes.
+ *
+ * The reference form is a WFS stored-query URL: an `ad:component` href is
+ * `…/ad/ows?…&storedQuery_id=urn:ogc:def:query:OGC-WFS::GetFeatureById&id=AdminUnitName.199`, and
+ * that `id` parameter equals the target's `gml:id` exactly, which a `GetFeatureById` fetch of
+ * `AdminUnitName.199` confirms. `componentJoinKey` reads it. Each reference also repeats its target's
+ * value in `xlink:title`, as Czechia's does, and the adapter reads none of those titles. Three of an
+ * address's references are `ad:AdminUnitName` features whose titles are a region, a district and a
+ * municipality, and only the resolved feature's `ad:level` separates the three.
+ *
+ * That is why the reader takes two passes over the input rather than one. A component page is a
+ * different document from an address page, so a single pass would have to defer an address until the
+ * page holding its municipality arrived, and with 1,704,196 addresses against 35,514 component
+ * features the deferred list is the wrong side of the join to hold. The first pass indexes the four
+ * component types from every document, and the second streams `ad:Address`. The index is therefore
+ * complete before the first address is read, so a reference resolving to no feature is a value the
+ * reader asked for and could not read, and it raises.
+ *
+ * The locator vocabulary is two types, and the publisher's own rendering fixes how they compose.
+ * `ad:designator` repeats and states no position, so selection goes by `ad:type/@xlink:href`:
+ * `addressNumber` is the *číslo popisné* and is present on every address, and `buildingIdentifier`
+ * is the *orientačné číslo* and appears only where the address also references a street. Measured
+ * over 1,000 addresses across ten windows spread through the 1,704,196, `addressNumber` appeared
+ * 1,000 times, `buildingIdentifier` 334 times, and the street count was also exactly 334.
+ *
+ * The same publisher serves its register's own rendered address through `ra:address` on the same
+ * GeoServer, which is what pins the composition. Three records, matched by street, number and postcode:
+ *
+ * | `addressNumber` | `buildingIdentifier` | street | `fulladdress` |
+ * | --- | --- | --- | --- |
+ * | `1760` | `29` | `Lipová` | `Lipová,1760/29,Hurbanovo,94701` |
+ * | `1771` | `4` | `Skalická` | `Skalická,1771/4,Košice-Krásna,04018` |
+ * | `142` | (absent) | (absent) | `142,Sikenička,94359` |
+ *
+ * So the number is `addressNumber` by itself, or `addressNumber/buildingIdentifier` where the
+ * orientation number exists, which is the publisher's own `annotation` field verbatim. A street-less
+ * address is ordinary rather than a defect: 666 of those 1,000 referenced no `ad:ThoroughfareName`.
+ *
+ * The place names come from two types. `ad:AdminUnitName` at `4thOrder` is the municipality and is
+ * referenced by every address measured, 1,080 of 1,080. The `3rdOrder` district and the `2ndOrder`
+ * region are referenced beside it and are not part of a written address. `ad:AddressAreaName` is the
+ * *časť obce*, the settlement part, and 426 of those 1,080 addresses reference one. Of those 426, 325
+ * repeat the municipality and 101 state another place, such as `Lidér Tejed` in the municipality
+ * of `Povoda`, so the adapter writes a dependent locality only where the two differ. The publisher's
+ * own `fulladdress` omits the settlement part in both cases, so a row holding one states a component
+ * that string does not.
+ *
+ * The postcode is `ad:PostalDescriptor/ad:postCode`, written as five digits with its leading zero
+ * intact (`04018`). Slovak usage splits it as `040 18`. The publisher writes it closed up, and the
+ * row stores what the publisher wrote, as the Czech reader does with `66463`.
+ *
+ * The Ministry states one condition of use and states it twice, in its own register record
+ * `https://rpi.gov.sk/api/collection_record/86dea70e-a55b-4241-bd63-4024b3f76b72` and in that
+ * record's INSPIRE export: `Neuplatňujú sa žiadne podmienky (CC0 Voľné dielo)`. That phrase renders
+ * INSPIRE's controlled value for no conditions applying to access and use, in Slovak, with the
+ * publisher's own identification of it as CC0. No version accompanies the label, so the
+ * address-source register writes no SPDX identifier and the rows record the publisher's words.
+ *
+ * The adapter honors `opts.limit` and `opts.signal`. `opts.country` is optional and accepts only `SK`.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address/format";
+import { openReadStream } from "@mailwoman/core/fs/streams";
+import { streamMarkupElements } from "@mailwoman/core/html/elements";
+import { PathBuilder } from "path-ts";
+import { Globerator } from "spliterator/node/fs";
+import { UnsupportedCountryError } from "#adapters/errors";
+import { stableSourceID } from "#adapters/source-id";
+import { adminUnitLevel, componentHrefs, componentJoinKey, designator, designatorsByType, placeName, postalDescriptorCode, thoroughfareName, voidDesignatorTypes, } from "#inspire/address";
+import { UnresolvedComponentReferenceError, VoidDesignatorError } from "#inspire/errors";
+import { SourceRegister } from "#registers";
+import { AddressRole, SurfaceOrigin } from "#types";
+/**
+ * Registry id for this adapter.
+ *
+ * Stamped into every row it emits, so a corpus record can be traced back to the dataset it came from.
+ */
+export const SK_INSPIRE_ADAPTER_ID = "sk-inspire";
+/**
+ * The publication this adapter reads.
+ *
+ * The literal stands in for a `SourceRegister` member until `lib/registers.ts` declares
+ * `SlovakiaInspireAddresses: "sk-minv-inspire-ad"`, which is the id this value spells.
+ */
+export const SK_INSPIRE_REGISTER = SourceRegister.SlovakiaInspireAddresses;
+/**
+ * The one jurisdiction this adapter emits.
+ *
+ * The service's register record states a national spatial scope with a `footprint_geo`
+ * of `Slovenská Republika`, so the set has one member.
+ */
+export const SK_INSPIRE_COUNTRIES = ["SK"];
+/**
+ * The license the address-source register elected for this publisher.
+ *
+ * `unchecked-access-free-sk-ministerstvo-vn-tra-slovenskej-republiky` is elected with
+ * `electedTerms` `Neuplatňujú sa žiadne podmienky (CC0 Voľné dielo)` and no `spdx`,
+ * because the publisher names CC0 without a version.
+ * The rows therefore record the publisher's own words, as Poland's and Czechia's do.
+ */
+export const SK_INSPIRE_DEFAULT_LICENSE = "Neuplatňujú sa žiadne podmienky (CC0 Voľné dielo)";
+/**
+ * The four feature types an address references, read in the first pass.
+ */
+const COMPONENT_TYPES = [
+    "ad:ThoroughfareName",
+    "ad:AddressAreaName",
+    "ad:AdminUnitName",
+    "ad:PostalDescriptor",
+];
+/**
+ * The administrative level that is the municipality.
+ *
+ * Measured over 1,080 addresses, every one references exactly one `ad:AdminUnitName` at this level.
+ * The `3rdOrder` district and the `2ndOrder` region are referenced beside it, so the level
+ * rather than the reference's position picks the municipality.
+ */
+const MUNICIPALITY_LEVEL = "4thOrder";
+/**
+ * The value a referenced feature contributes, read once as the feature arrives.
+ */
+function referencedValue(feature) {
+    if (feature.name === "ad:ThoroughfareName") {
+        return { type: feature.name, value: thoroughfareName(feature) };
+    }
+    if (feature.name === "ad:PostalDescriptor") {
+        return { type: feature.name, value: postalDescriptorCode(feature) };
+    }
+    if (feature.name === "ad:AdminUnitName") {
+        return { type: feature.name, value: placeName(feature), level: adminUnitLevel(feature) };
+    }
+    return { type: feature.name, value: placeName(feature) };
+}
+/**
+ * The house number as the Register adries writes it in its own `annotation` field.
+ *
+ * The descriptive number is the whole value where the publisher states no orientation
+ * number, and the two are joined by a solidus where it does.
+ * The table in this module's header reads that off three records of the publisher's `ra:address` layer.
+ *
+ * @returns The number, or undefined when the publisher states no `addressNumber`.
+ */
+export function slovakHouseNumber(byType) {
+    const descriptive = designator(byType, "addressNumber");
+    if (!descriptive)
+        return undefined;
+    const orientation = designator(byType, "buildingIdentifier");
+    return orientation ? `${descriptive}/${orientation}` : descriptive;
+}
+export function createSKInspireAdapter() {
+    return {
+        id: SK_INSPIRE_ADAPTER_ID,
+        defaultLicense: SK_INSPIRE_DEFAULT_LICENSE,
+        addressRole: AddressRole.Premise,
+        register: SK_INSPIRE_REGISTER,
+        surface: SurfaceOrigin.Rendered,
+        description: "INSPIRE Addresses (Ministerstvo vnútra SR): house-number-level addresses for Slovakia, read from saved WFS pages.",
+        async *rows(opts) {
+            if (opts.country && !SK_INSPIRE_COUNTRIES.includes(opts.country)) {
+                throw new UnsupportedCountryError(SK_INSPIRE_ADAPTER_ID, SK_INSPIRE_COUNTRIES, opts.country);
+            }
+            const documents = await documentPaths(opts.inputPath);
+            /**
+             * The value of every referenced feature in the input, by its `gml:id`.
+             */
+            const referenced = new Map();
+            for (const documentPath of documents) {
+                if (opts.signal?.aborted)
+                    return;
+                for await (const feature of streamMarkupElements(documentChunks(documentPath), COMPONENT_TYPES, {
+                    xml: true,
+                })) {
+                    if (opts.signal?.aborted)
+                        return;
+                    const id = feature.attributes["gml:id"];
+                    if (id) {
+                        referenced.set(id, referencedValue(feature));
+                    }
+                }
+            }
+            let emitted = 0;
+            for (const documentPath of documents) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                for await (const address of streamMarkupElements(documentChunks(documentPath), "ad:Address", {
+                    xml: true,
+                })) {
+                    if (opts.signal?.aborted)
+                        break;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        break;
+                    const row = composeRow(address, referenced);
+                    if (!row)
+                        continue;
+                    yield row;
+                    emitted++;
+                }
+            }
+        },
+    };
+}
+/**
+ * One address's row, or `undefined` when it holds too little to render.
+ *
+ * The component index is complete before this is called, so a reference that
+ * resolves to no feature raises rather than being deferred.
+ */
+function composeRow(address, referenced) {
+    const addressID = address.attributes["gml:id"]?.trim();
+    const voided = voidDesignatorTypes(address);
+    for (const type of ["addressNumber", "buildingIdentifier"]) {
+        if (voided.has(type))
+            throw new VoidDesignatorError(SK_INSPIRE_ADAPTER_ID, addressID, type);
+    }
+    let street;
+    let postcode;
+    let municipality;
+    let settlement;
+    for (const href of componentHrefs(address)) {
+        const key = componentJoinKey(href);
+        const feature = key ? referenced.get(key) : undefined;
+        if (!feature)
+            throw new UnresolvedComponentReferenceError(SK_INSPIRE_ADAPTER_ID, addressID, href);
+        if (feature.type === "ad:ThoroughfareName") {
+            street = feature.value;
+        }
+        else if (feature.type === "ad:PostalDescriptor") {
+            postcode = feature.value;
+        }
+        else if (feature.type === "ad:AddressAreaName") {
+            settlement = feature.value;
+        }
+        else if (feature.type === "ad:AdminUnitName" && feature.level === MUNICIPALITY_LEVEL) {
+            municipality = feature.value;
+        }
+    }
+    const place = municipality ?? settlement;
+    if (!place)
+        return undefined;
+    const components = {};
+    const house = slovakHouseNumber(designatorsByType(address));
+    if (house) {
+        components.house_number = house;
+    }
+    if (street) {
+        components.street = street;
+    }
+    // The settlement part is a dependent locality only where it names something other
+    // than the municipality, which 101 of 426 address-area references do.
+    if (settlement && municipality && settlement !== municipality) {
+        components.dependent_locality = settlement;
+    }
+    if (postcode) {
+        components.postcode = postcode;
+    }
+    components.locality = place;
+    const rendered = formatAddressRow(components, "SK", { singleLine: true });
+    if (!rendered)
+        return undefined;
+    const { raw, components: aligned } = rendered;
+    return {
+        raw,
+        components: aligned,
+        country: "SK",
+        locale: "sk-SK",
+        source: SK_INSPIRE_ADAPTER_ID,
+        source_id: addressID ? `${SK_INSPIRE_ADAPTER_ID}-${addressID}` : stableSourceID(SK_INSPIRE_ADAPTER_ID, aligned),
+        corpus_version: "",
+        license: SK_INSPIRE_DEFAULT_LICENSE,
+    };
+}
+/**
+ * One saved WFS page as the chunk sequence the markup reader takes.
+ */
+function documentChunks(documentPath) {
+    return openReadStream(PathBuilder.from(documentPath));
+}
+/**
+ * Every document under `inputPath`, which is one saved page or a directory holding them.
+ *
+ * A directory is the ordinary case, because the service publishes five feature types
+ * and acquisition writes a document per type.
+ * The walk is recursive, because `#sk/tools/fetch/inspire` gives each type its own
+ * subdirectory so that each keeps its own harvest manifest.
+ *
+ * A directory holding no document raises rather than yielding zero rows, so a wrong
+ * path reports itself instead of reading as an empty publisher.
+ */
+async function documentPaths(inputPath) {
+    const path = PathBuilder.from(inputPath);
+    const basename = path.basename().toLowerCase();
+    if (basename.endsWith(".gml") || basename.endsWith(".xml"))
+        return [path];
+    const names = await Globerator.from("**/*.{gml,xml}", { cwd: path.toString(), absolute: false }).toSorted();
+    if (!names.length) {
+        throw new Error(`${SK_INSPIRE_ADAPTER_ID} adapter: ${path.toString()} holds no GML document`);
+    }
+    return names.map((name) => path(name));
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const skInspireAdapter = createSKInspireAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/sk/adapters/inspire/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../lib/sk/adapters/inspire/adapter.ts"],"names":[],"mappings":"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"}

package/out/sk/tools/fetch/inspire.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ * Harvests Slovakia's INSPIRE Addresses (AD) theme into the GML documents that
+ * `#sk/adapters/inspire/adapter` reads.
+ *
+ * The Ministerstvo vnútra Slovenskej republiky publishes the national address register through
+ * GeoServer at {@linkcode SK_INSPIRE_WFS}. Its register record,
+ * `https://rpi.gov.sk/api/collection_record/86dea70e-a55b-4241-bd63-4024b3f76b72`, names a WMS and
+ * this WFS as the theme's only distributions and states one condition of use, `Neuplatňujú sa žiadne
+ * podmienky (CC0 Voľné dielo)`, which the address-source register elected. There is no INSPIRE ATOM
+ * download service for this theme: the feeds under `inspirews.skgeodesy.sk` belong to the
+ * Geodetický a kartografický ústav, which is a different publisher and a different record.
+ *
+ * `#tools/fetch/wfs-harvest` owns the page read, the appending, the manifest and the resumption.
+ * What is particular to Slovakia is that an address is assembled from five feature types rather
+ * than read from one, which is what shapes the layout this writes.
+ *
+ * ## Five types, five documents, one directory
+ *
+ * `ad:Address` carries a locator and references its street, its settlement part, its administrative
+ * units and its postcode through `ad:component`. The adapter resolves those references locally
+ * against an index it builds in a first pass over every document in `inputPath`, so every type has
+ * to be on disk before the first address is composed. Measured 2026-10-03, `resultType=hits` past
+ * index 0 reports 1,704,196 `ad:Address`, 29,315 `ad:ThoroughfareName`, 3,015 `ad:AdminUnitName`,
+ * 1,769 `ad:AddressAreaName` and 1,415 `ad:PostalDescriptor`.
+ *
+ * Each type is harvested into its own directory under the source root, because a harvest's manifest
+ * sits at a fixed name beside its data file and five types sharing one directory would overwrite
+ * each other's manifest. A run would then re-harvest every type, and the 341 address pages are the
+ * expensive part of this acquisition:
+ *
+ *     sk-inspire/Address/Address.gml            + MANIFEST.json
+ *     sk-inspire/ThoroughfareName/…             + MANIFEST.json
+ *     …
+ *
+ * The adapter reads `inputPath` recursively, so that root is what {@linkcode skInspireInputPath}
+ * states. The four component types are harvested before the addresses, so an interrupted run leaves
+ * the small side of the join complete rather than leaving addresses whose component references the
+ * harvest cannot answer.
+ *
+ * ## What the service states about itself
+ *
+ * Measured 2026-10-03: `ImplementsResultPaging` is `TRUE`, `ImplementsSorting` is `TRUE`,
+ * `CountDefault` is 5000, and the advertised `GetFeature` formats include
+ * `application/gml+xml; version=3.2`, which is the one the adapter's markup reader takes. A
+ * 5,000-feature page of `ad:Address` answered in 17 seconds carrying 13,879,456 bytes, so a full
+ * harvest of that type is 341 requests and roughly 4.7 GB.
+ *
+ * `CountDefault` is 5000 and no type reports 5000 features, so `statedFeatureCount` accepts each
+ * type's `numberMatched` as a count rather than refusing it as a page cap. The register records one
+ * response in nine that carried no `numberMatched` attribute at all;
+ * `readCheckedWFSFeatureCount` reads such a response as no usable count, and the harvest then ends
+ * on the first page that returns no features instead of recording a wrong total.
+ */
+import { type APIClient } from "@mailwoman/core/api";
+import type { PathBuilderLike } from "path-ts";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
+import { type WFSCapabilities } from "#tools/fetch/inspire-addresses";
+import { type FeatureCountStatement, type WFSHarvestManifest } from "#tools/fetch/wfs-harvest";
+/**
+ * The service this module harvests.
+ */
+export declare const SK_INSPIRE_WFS = "https://rageo.minv.sk/geoserver/ad/wfs";
+/**
+ * The output format the harvest asks for, which is the GML the adapter's markup reader takes.
+ */
+export declare const SK_INSPIRE_OUTPUT_FORMAT = "application/gml+xml; version=3.2";
+/**
+ * The property the pages are ordered by.
+ *
+ * Every AD feature type carries `ad:inspireId`, so one sort serves all five.
+ * Without a sort, a resumed harvest would rest on the service returning the same
+ * features in the same order as the earlier run, which no WFS guarantees.
+ */
+export declare const SK_INSPIRE_SORT_BY = "ad:inspireId";
+/**
+ * Features per page.
+ *
+ * The service's own `CountDefault`, which is the largest page it will serve.
+ */
+export declare const SK_INSPIRE_PAGE_SIZE = 5000;
+/**
+ * The feature types harvested, in the order they are taken.
+ *
+ * The four component types come first, each in the thousands, so an interrupted run
+ * leaves the index side of the adapter's join complete.
+ * `Address` is last and is the 1.7-million-feature side.
+ */
+export declare const SK_INSPIRE_TYPES: readonly ["ThoroughfareName", "AddressAreaName", "AdminUnitName", "PostalDescriptor", "Address"];
+/**
+ * One of the five feature types this module harvests.
+ */
+export type SKInspireType = (typeof SK_INSPIRE_TYPES)[number];
+/**
+ * The data file one type is harvested into, inside that type's own directory.
+ */
+export declare function skInspireHarvestFile(type: SKInspireType): string;
+/**
+ * What the service states about itself, with the claims this harvest depends on checked.
+ *
+ * The qualified type names come from the capabilities document rather than from a
+ * constant here, because a service's prefix is its own: this one publishes `ad:Address`
+ * and Estonia's publishes `AD_Address:AD.Address`.
+ *
+ * @throws When the service stops publishing one of the five types, does not advertise
+ * the GML format the adapter reads, or does not advertise result paging.
+ */
+export declare function readSKInspireCapabilities(client: Pick<APIClient, "fetch">): Promise<WFSCapabilities>;
+/**
+ * The count the service states for one type, with how it was obtained.
+ *
+ * `statedFeatureCount` carries no count forward where the reported number equals
+ * the advertised page cap, because such a number describes the largest page the
+ * service will serve rather than what the type holds.
+ * This service's cap is 5000 and no type reports 5000.
+ */
+export declare function readSKInspireFeatureCount(client: Pick<APIClient, "fetch">, options: {
+    typeName: string;
+    pageCap: number | null;
+}): Promise<FeatureCountStatement>;
+export interface HarvestSKInspireTypeOptions {
+    /**
+     * Where this type's harvest is written.
+     *
+     * The adapter reads {@linkcode skInspireHarvestFile} inside it.
+     */
+    outputDir: PathBuilderLike;
+    /**
+     * The qualified name the capabilities document gives this type.
+     */
+    typeName: string;
+    type: SKInspireType;
+    /**
+     * The `CountDefault` the service advertises, read from the capabilities document.
+     *
+     * Passed in rather than read here, so one capabilities request serves both the type name
+     * and the cap a reported count is checked against.
+     */
+    pageCap: number | null;
+    /**
+     * Features per page, capped at {@linkcode SK_INSPIRE_PAGE_SIZE} because the service caps it there.
+     */
+    pageSize?: number;
+    /**
+     * Stop once the manifest holds this many pages, for a probe rather than a full harvest.
+     */
+    maxPages?: number;
+    signal?: AbortSignal;
+    report?: (line: string) => void;
+}
+/**
+ * Harvests one feature type into its own directory, recording each page in a manifest beside it.
+ *
+ * @returns The manifest as written.
+ */
+export declare function harvestSKInspireType(client: Pick<APIClient, "fetch">, options: HarvestSKInspireTypeOptions): Promise<WFSHarvestManifest>;
+/**
+ * Per-invocation options for the registry entry.
+ */
+export interface FetchSKInspireOptions extends BaseFetchOptions {
+    /**
+     * Features per page, capped at {@linkcode SK_INSPIRE_PAGE_SIZE}.
+     */
+    pageSize?: number;
+    /**
+     * Stop each type once its manifest holds this many pages, for a probe rather than a full harvest.
+     */
+    maxPages?: number;
+    signal?: AbortSignal;
+    /**
+     * An injected client, for a test that supplies its own transport.
+     */
+    client?: Pick<APIClient, "fetch">;
+}
+/**
+ * The directory `#sk/adapters/inspire/adapter` reads, given the root a fetch wrote under.
+ *
+ * A directory rather than a file, because the five feature types are five documents
+ * and the adapter indexes four of them before it composes an address out of the fifth.
+ */
+export declare function skInspireInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike;
+/**
+ * Harvests Slovakia's five AD feature types under `<outRoot>/sk-inspire/<type>/`,
+ * for `mailwoman corpus fetch sk-inspire`.
+ *
+ * Each type is reported separately and a type that fails does not stop the rest, because the
+ * documents are read together by the adapter and a partial directory is still worth resuming.
+ * Re-runnable per type: a complete harvest whose file still hashes to its manifest's digest
+ * makes no request, and an interrupted one resumes at the page after the last that reached disk.
+ */
+export declare function fetchSKInspire(options: FetchSKInspireOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=inspire.d.ts.map

package/out/sk/tools/fetch/inspire.d.ts.map

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