@mailwoman/corpus 9.1.0 → 9.3.0

package/out/tools/fetch/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The `mailwoman corpus fetch <source>` family — reproducible bulk-download recovery modules for
+ *   the open-data sources the corpus build pipeline consumes. Each module writes the raw download
+ *   files **plus** a sibling `MANIFEST.json` capturing the origin URL, fetch timestamp, byte count,
+ *   and sha256 so downstream adapters can verify provenance.
+ *
+ *   The corpus build pipeline itself does NOT call these modules — the existing convention is for
+ *   operators to pre-download into an out-root and point adapters at the resulting files. These
+ *   modules exist for **reproducibility** (disk-loss recovery, weekly refresh, fresh-environment
+ *   bootstrap).
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   # Default: writes under ./data/corpus/sources/ relative to the working directory
+ *   mailwoman corpus fetch state-sources
+ *   mailwoman corpus fetch hrsa
+ *
+ *   # Or point at the standard mailwoman data root
+ *   mailwoman corpus fetch state-sources --out-root /data/corpus/sources
+ *   ```
+ *
+ *   Each adapter under `corpus/src/adapters/<adapter>/README.md` documents the specific URL its
+ *   input was pulled from; these modules mirror those URLs in a single executable place.
+ *
+ *   ## Coverage
+ *
+ *   - `ban` — French BAN (Base Adresse Nationale), all départements incl. DOM/TOM. Tier B (Licence
+ *       Ouverte 2.0).
+ *   - `nad` — US DOT National Address Database (~97M address points, ArcGIS FeatureServer). Tier A
+ *       (US PD).
+ *   - `geonames-postal` — GeoNames per-country postal exports (~80 countries). Tier B (CC-BY-4.0,
+ *       attribute "GeoNames"). The only source in this family carrying `(postcode, locality, region)`
+ *       with the names INLINE, which is why it exists: the `parent_id` join route covers exactly five
+ *       countries and the nearest-centroid fallback measured under 50% agreement on four of those five.
+ *       GeoNames does not publish every country — Venezuela 404s.
+ *   - `hrsa` — HRSA Health Center Service Delivery Sites (federal). Tier A (US PD).
+ *   - `imls-pls` — IMLS Public Libraries Survey, outlet-level (~17K library branches, FY 2023).
+ *       Tier A (US PD).
+ *   - `nppes` — NPPES NPI registry, full monthly dissemination (~7M provider venue+address rows).
+ *       Tier A (US PD).
+ *   - `openaddresses` — OpenAddresses country collections (default: Canada / `ca`). Tier B/C mixed
+ *       — per-row filter.
+ *   - `ourairports` — OurAirports global airport CSVs (~83K airports + the country/region/runway
+ *       joins). Tier A (public domain). The VENUE half of the sub-venue arc (#35); it carries no
+ *       interior structure, which comes from `@mailwoman/osm/sdk`'s `extractOSMSubVenues`.
+ *   - `wikidata-subvenue` — the multilingual sub-venue DESIGNATOR vocabulary, pulled as the labels
+ *       and aliases of eight Wikidata concepts (terminal, gate, concourse, campus, …) plus the
+ *       airport-terminal instance labels as attested usage. Tier A (CC0). The only module in this
+ *       family built on `APIClient` — see its docstring for why.
+ *   - `state-sources` — NY/TX/DE/OR notaries, IA contractors, WA health providers, HI lobbyists.
+ *       Tier A (state PD-equivalent).
+ *   - `state-hi-schools` — Hawaii DOE school directory (original XLSX; HIDOE + PCS sheets). Tier A
+ *       (state PD-equivalent).
+ *   - `tiger-full` — US Census TIGER 2024 ADDRFEAT, all US counties. Tier A (US PD).
+ *
+ *   License tiers per `docs/licensing-strategy.md` (or the playpen knowledge base mirror at
+ *   `docs/docs/projects/mailwoman/licensing-strategy.md`). `openaddresses` is a **Tier-mixed**
+ *   source: the downloaded collection includes CC0, CC-BY, OGL, and ODbL/CC-BY-SA rows. The per-row
+ *   `LICENSE` filter in the `openaddresses` adapter is essential — Tier-C (ODbL, CC-BY-SA) rows are
+ *   dropped at ingest by default to protect proprietary-weights training.
+ *
+ *   ### OpenAddresses authentication (as of 2026-05-18)
+ *
+ *   `batch.openaddresses.io` now requires a free registered account for bulk downloads (auth check
+ *   prevents CDN abuse; data remains openly licensed). `fetchOpenAddresses` reads `OA_BATCH_TOKEN`
+ *   from the environment:
+ *
+ *   ```sh
+ *   # One-time: register at https://batch.openaddresses.io/register
+ *   # Log in → Profile → "Create Token" → copy token
+ *   export OA_BATCH_TOKEN=<your-token>
+ *
+ *   # Download Canada (~2 GiB compressed, ~7 GiB uncompressed)
+ *   mailwoman corpus fetch openaddresses --country ca \
+ *     --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
+ *
+ *   # Or any other OA country code
+ *   mailwoman corpus fetch openaddresses --country fr
+ *   ```
+ *
+ *   Without a token the command prints setup instructions and reports the failure.
+ *
+ *   ## Adding a new source
+ *
+ *   1. Pick the right module (or create a sibling one if the source is from a meaningfully
+ *      different family).
+ *   2. Append to the `SOURCES` array: `{ slug, filename, url }`.
+ *   3. Confirm the destination URL via `curl -sI -L <url> | head` before committing — state
+ *      open-data portals occasionally rotate Socrata view IDs.
+ *   4. Run the command against a scratch `--out-root` to verify the download succeeds + the
+ *      MANIFEST is well-formed.
+ *   5. Add the source's adapter (or extend an existing one) under `corpus/src/adapters/`.
+ */
+import { fetchBan } from "#tools/fetch/ban";
+import { fetchGeonamesDumps } from "#tools/fetch/geonames-dump";
+import { fetchGeonamesPostal } from "#tools/fetch/geonames-postal";
+import { fetchHRSA } from "#tools/fetch/hrsa";
+import { fetchIMLSPLS } from "#tools/fetch/imls-pls";
+import { fetchNAD } from "#tools/fetch/nad";
+import { fetchNPPES } from "#tools/fetch/nppes";
+import { fetchOpenAddresses } from "#tools/fetch/openaddresses";
+import { fetchOurAirports } from "#tools/fetch/ourairports";
+import { fetchStateHISchools } from "#tools/fetch/state-hi-schools";
+import { fetchStateSources } from "#tools/fetch/state-sources";
+import { fetchTigerFull } from "#tools/fetch/tiger-full";
+import { fetchWikidataSubVenue } from "#tools/fetch/wikidata-subvenue";
+export * from "#tools/fetch/ban";
+export * from "#tools/fetch/geonames-dump";
+export * from "#tools/fetch/geonames-postal";
+export * from "#tools/fetch/hrsa";
+export * from "#tools/fetch/imls-pls";
+export * from "#tools/fetch/nad";
+export * from "#tools/fetch/nppes";
+export * from "#tools/fetch/openaddresses";
+export * from "#tools/fetch/ourairports";
+export * from "#tools/fetch/state-hi-schools";
+export * from "#tools/fetch/state-sources";
+export * from "#tools/fetch/tiger-full";
+export * from "#tools/fetch/wikidata-subvenue";
+/**
+ * The fetch-source registry: id → module entry point. Each entry point takes its own options interface.
+ */
+export declare const FETCH_SOURCES: {
+    readonly ban: typeof fetchBan;
+    readonly nad: typeof fetchNAD;
+    readonly "geonames-dump": typeof fetchGeonamesDumps;
+    readonly "geonames-postal": typeof fetchGeonamesPostal;
+    readonly hrsa: typeof fetchHRSA;
+    readonly "imls-pls": typeof fetchIMLSPLS;
+    readonly nppes: typeof fetchNPPES;
+    readonly openaddresses: typeof fetchOpenAddresses;
+    readonly ourairports: typeof fetchOurAirports;
+    readonly "state-sources": typeof fetchStateSources;
+    readonly "state-hi-schools": typeof fetchStateHISchools;
+    readonly "tiger-full": typeof fetchTigerFull;
+    readonly "wikidata-subvenue": typeof fetchWikidataSubVenue;
+};
+export type FetchSourceID = keyof typeof FETCH_SOURCES;
+//# sourceMappingURL=index.d.ts.map

package/out/tools/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,cAAc,kBAAkB,CAAA;AAChC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,cAAc,gCAAgC,CAAA;AAE9C;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;CAchB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,aAAa,CAAA"}

package/out/tools/fetch/index.js

@@ -0,0 +1,143 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The `mailwoman corpus fetch <source>` family — reproducible bulk-download recovery modules for
+ *   the open-data sources the corpus build pipeline consumes. Each module writes the raw download
+ *   files **plus** a sibling `MANIFEST.json` capturing the origin URL, fetch timestamp, byte count,
+ *   and sha256 so downstream adapters can verify provenance.
+ *
+ *   The corpus build pipeline itself does NOT call these modules — the existing convention is for
+ *   operators to pre-download into an out-root and point adapters at the resulting files. These
+ *   modules exist for **reproducibility** (disk-loss recovery, weekly refresh, fresh-environment
+ *   bootstrap).
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   # Default: writes under ./data/corpus/sources/ relative to the working directory
+ *   mailwoman corpus fetch state-sources
+ *   mailwoman corpus fetch hrsa
+ *
+ *   # Or point at the standard mailwoman data root
+ *   mailwoman corpus fetch state-sources --out-root /data/corpus/sources
+ *   ```
+ *
+ *   Each adapter under `corpus/src/adapters/<adapter>/README.md` documents the specific URL its
+ *   input was pulled from; these modules mirror those URLs in a single executable place.
+ *
+ *   ## Coverage
+ *
+ *   - `ban` — French BAN (Base Adresse Nationale), all départements incl. DOM/TOM. Tier B (Licence
+ *       Ouverte 2.0).
+ *   - `nad` — US DOT National Address Database (~97M address points, ArcGIS FeatureServer). Tier A
+ *       (US PD).
+ *   - `geonames-postal` — GeoNames per-country postal exports (~80 countries). Tier B (CC-BY-4.0,
+ *       attribute "GeoNames"). The only source in this family carrying `(postcode, locality, region)`
+ *       with the names INLINE, which is why it exists: the `parent_id` join route covers exactly five
+ *       countries and the nearest-centroid fallback measured under 50% agreement on four of those five.
+ *       GeoNames does not publish every country — Venezuela 404s.
+ *   - `hrsa` — HRSA Health Center Service Delivery Sites (federal). Tier A (US PD).
+ *   - `imls-pls` — IMLS Public Libraries Survey, outlet-level (~17K library branches, FY 2023).
+ *       Tier A (US PD).
+ *   - `nppes` — NPPES NPI registry, full monthly dissemination (~7M provider venue+address rows).
+ *       Tier A (US PD).
+ *   - `openaddresses` — OpenAddresses country collections (default: Canada / `ca`). Tier B/C mixed
+ *       — per-row filter.
+ *   - `ourairports` — OurAirports global airport CSVs (~83K airports + the country/region/runway
+ *       joins). Tier A (public domain). The VENUE half of the sub-venue arc (#35); it carries no
+ *       interior structure, which comes from `@mailwoman/osm/sdk`'s `extractOSMSubVenues`.
+ *   - `wikidata-subvenue` — the multilingual sub-venue DESIGNATOR vocabulary, pulled as the labels
+ *       and aliases of eight Wikidata concepts (terminal, gate, concourse, campus, …) plus the
+ *       airport-terminal instance labels as attested usage. Tier A (CC0). The only module in this
+ *       family built on `APIClient` — see its docstring for why.
+ *   - `state-sources` — NY/TX/DE/OR notaries, IA contractors, WA health providers, HI lobbyists.
+ *       Tier A (state PD-equivalent).
+ *   - `state-hi-schools` — Hawaii DOE school directory (original XLSX; HIDOE + PCS sheets). Tier A
+ *       (state PD-equivalent).
+ *   - `tiger-full` — US Census TIGER 2024 ADDRFEAT, all US counties. Tier A (US PD).
+ *
+ *   License tiers per `docs/licensing-strategy.md` (or the playpen knowledge base mirror at
+ *   `docs/docs/projects/mailwoman/licensing-strategy.md`). `openaddresses` is a **Tier-mixed**
+ *   source: the downloaded collection includes CC0, CC-BY, OGL, and ODbL/CC-BY-SA rows. The per-row
+ *   `LICENSE` filter in the `openaddresses` adapter is essential — Tier-C (ODbL, CC-BY-SA) rows are
+ *   dropped at ingest by default to protect proprietary-weights training.
+ *
+ *   ### OpenAddresses authentication (as of 2026-05-18)
+ *
+ *   `batch.openaddresses.io` now requires a free registered account for bulk downloads (auth check
+ *   prevents CDN abuse; data remains openly licensed). `fetchOpenAddresses` reads `OA_BATCH_TOKEN`
+ *   from the environment:
+ *
+ *   ```sh
+ *   # One-time: register at https://batch.openaddresses.io/register
+ *   # Log in → Profile → "Create Token" → copy token
+ *   export OA_BATCH_TOKEN=<your-token>
+ *
+ *   # Download Canada (~2 GiB compressed, ~7 GiB uncompressed)
+ *   mailwoman corpus fetch openaddresses --country ca \
+ *     --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
+ *
+ *   # Or any other OA country code
+ *   mailwoman corpus fetch openaddresses --country fr
+ *   ```
+ *
+ *   Without a token the command prints setup instructions and reports the failure.
+ *
+ *   ## Adding a new source
+ *
+ *   1. Pick the right module (or create a sibling one if the source is from a meaningfully
+ *      different family).
+ *   2. Append to the `SOURCES` array: `{ slug, filename, url }`.
+ *   3. Confirm the destination URL via `curl -sI -L <url> | head` before committing — state
+ *      open-data portals occasionally rotate Socrata view IDs.
+ *   4. Run the command against a scratch `--out-root` to verify the download succeeds + the
+ *      MANIFEST is well-formed.
+ *   5. Add the source's adapter (or extend an existing one) under `corpus/src/adapters/`.
+ */
+import { fetchBan } from "#tools/fetch/ban";
+import { fetchGeonamesDumps } from "#tools/fetch/geonames-dump";
+import { fetchGeonamesPostal } from "#tools/fetch/geonames-postal";
+import { fetchHRSA } from "#tools/fetch/hrsa";
+import { fetchIMLSPLS } from "#tools/fetch/imls-pls";
+import { fetchNAD } from "#tools/fetch/nad";
+import { fetchNPPES } from "#tools/fetch/nppes";
+import { fetchOpenAddresses } from "#tools/fetch/openaddresses";
+import { fetchOurAirports } from "#tools/fetch/ourairports";
+import { fetchStateHISchools } from "#tools/fetch/state-hi-schools";
+import { fetchStateSources } from "#tools/fetch/state-sources";
+import { fetchTigerFull } from "#tools/fetch/tiger-full";
+import { fetchWikidataSubVenue } from "#tools/fetch/wikidata-subvenue";
+export * from "#tools/fetch/ban";
+export * from "#tools/fetch/geonames-dump";
+export * from "#tools/fetch/geonames-postal";
+export * from "#tools/fetch/hrsa";
+export * from "#tools/fetch/imls-pls";
+export * from "#tools/fetch/nad";
+export * from "#tools/fetch/nppes";
+export * from "#tools/fetch/openaddresses";
+export * from "#tools/fetch/ourairports";
+export * from "#tools/fetch/state-hi-schools";
+export * from "#tools/fetch/state-sources";
+export * from "#tools/fetch/tiger-full";
+export * from "#tools/fetch/wikidata-subvenue";
+/**
+ * The fetch-source registry: id → module entry point. Each entry point takes its own options interface.
+ */
+export const FETCH_SOURCES = {
+    ban: fetchBan,
+    nad: fetchNAD,
+    "geonames-dump": fetchGeonamesDumps,
+    "geonames-postal": fetchGeonamesPostal,
+    hrsa: fetchHRSA,
+    "imls-pls": fetchIMLSPLS,
+    nppes: fetchNPPES,
+    openaddresses: fetchOpenAddresses,
+    ourairports: fetchOurAirports,
+    "state-sources": fetchStateSources,
+    "state-hi-schools": fetchStateHISchools,
+    "tiger-full": fetchTigerFull,
+    "wikidata-subvenue": fetchWikidataSubVenue,
+};
+//# sourceMappingURL=index.js.map

package/out/tools/fetch/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../lib/tools/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAA;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AAEtE,cAAc,kBAAkB,CAAA;AAChC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,mBAAmB,CAAA;AACjC,cAAc,uBAAuB,CAAA;AACrC,cAAc,kBAAkB,CAAA;AAChC,cAAc,oBAAoB,CAAA;AAClC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,0BAA0B,CAAA;AACxC,cAAc,+BAA+B,CAAA;AAC7C,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AACvC,cAAc,gCAAgC,CAAA;AAE9C;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;IACb,eAAe,EAAE,kBAAkB;IACnC,iBAAiB,EAAE,mBAAmB;IACtC,IAAI,EAAE,SAAS;IACf,UAAU,EAAE,YAAY;IACxB,KAAK,EAAE,UAAU;IACjB,aAAa,EAAE,kBAAkB;IACjC,WAAW,EAAE,gBAAgB;IAC7B,eAAe,EAAE,iBAAiB;IAClC,kBAAkB,EAAE,mBAAmB;IACvC,YAAY,EAAE,cAAc;IAC5B,mBAAmB,EAAE,qBAAqB;CACjC,CAAA"}

package/out/tools/fetch/nad.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the US DOT National Address Database (NAD) — ~97 million structured US address-point
+ *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter (#30).
+ *   US Public Domain (17 U.S.C. § 105).
+ *
+ *   - Bounded per-chunk page concurrency (4× speedup at safe pressure)
+ *   - 5× larger page size (5 000 vs. the old bash fetcher's 2 000) — fewer round-trips per chunk
+ *   - Honest `complete: true` flag: only set when every page in the chunk fetched cleanly
+ *   - Built-in fetch with gzip/brotli decompression (no curl + Python subprocess tax)
+ *   - Per-chunk manifest with sha256 + record count + error count
+ *
+ *   ## Source layout
+ *
+ *   The ArcGIS FeatureServer is the only fully-automated path. As of 2026-05:
+ *
+ *   - **`bulk`** mode requires a pre-signed S3 URL (Akamai blocks scripted curl on the DOT page). Pass
+ *       `--nad-url <presigned>` from a browser visit to
+ *       [https://www.transportation.gov/gis/national-address-database](https://www.transportation.gov/gis/national-address-database).
+ *   - **`featureserver`** mode (default) pages the live FeatureService via OBJECTID ranges, writing
+ *       NDJSON chunks into `<outRoot>/usgov-nad/featureserver/`.
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   mailwoman corpus fetch nad --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
+ *
+ *   # Resume from an OID
+ *   mailwoman corpus fetch nad --start-oid 34400001
+ *
+ *   # Increase concurrency on a fast link
+ *   mailwoman corpus fetch nad --concurrency 8 --page-size 10000
+ *   ```
+ */
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
+export interface FetchNADOptions extends BaseFetchOptions {
+    /**
+     * Fetch strategy. Default `featureserver`.
+     */
+    mode?: "featureserver" | "bulk";
+    /**
+     * Pre-signed S3 URL for bulk mode.
+     */
+    nadURL?: string;
+    /**
+     * Records per output file. Default `100000`.
+     */
+    chunkSize?: number;
+    /**
+     * Records per HTTP request. Default `5000`.
+     */
+    pageSize?: number;
+    /**
+     * Parallel page fetches within a chunk. Default `4`.
+     */
+    concurrency?: number;
+    /**
+     * Start OBJECTID. Default `1`.
+     */
+    startOID?: number;
+    /**
+     * Stop before this OID. Default = total count.
+     */
+    endOID?: number;
+}
+export declare function fetchNAD(options: FetchNADOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=nad.d.ts.map

package/out/tools/fetch/nad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nad.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/nad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAQ3E,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACxD;;OAEG;IACH,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAuPD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAY/G"}

package/out/tools/fetch/nad.js

@@ -0,0 +1,234 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Fetch the US DOT National Address Database (NAD) — ~97 million structured US address-point
+ *   records aggregated from state and local authorities. Source for the `usgov-nad` adapter (#30).
+ *   US Public Domain (17 U.S.C. § 105).
+ *
+ *   - Bounded per-chunk page concurrency (4× speedup at safe pressure)
+ *   - 5× larger page size (5 000 vs. the old bash fetcher's 2 000) — fewer round-trips per chunk
+ *   - Honest `complete: true` flag: only set when every page in the chunk fetched cleanly
+ *   - Built-in fetch with gzip/brotli decompression (no curl + Python subprocess tax)
+ *   - Per-chunk manifest with sha256 + record count + error count
+ *
+ *   ## Source layout
+ *
+ *   The ArcGIS FeatureServer is the only fully-automated path. As of 2026-05:
+ *
+ *   - **`bulk`** mode requires a pre-signed S3 URL (Akamai blocks scripted curl on the DOT page). Pass
+ *       `--nad-url <presigned>` from a browser visit to
+ *       [https://www.transportation.gov/gis/national-address-database](https://www.transportation.gov/gis/national-address-database).
+ *   - **`featureserver`** mode (default) pages the live FeatureService via OBJECTID ranges, writing
+ *       NDJSON chunks into `<outRoot>/usgov-nad/featureserver/`.
+ *
+ *   ## Usage
+ *
+ *   ```sh
+ *   mailwoman corpus fetch nad --out-root $MAILWOMAN_DATA_ROOT/corpus/sources
+ *
+ *   # Resume from an OID
+ *   mailwoman corpus fetch nad --start-oid 34400001
+ *
+ *   # Increase concurrency on a fast link
+ *   mailwoman corpus fetch nad --concurrency 8 --page-size 10000
+ *   ```
+ */
+import { APIClient, pluckResponseData } from "@mailwoman/core/api";
+import { statPath, pathExists } from "@mailwoman/core/fs/readers";
+import { makeDirectories, writeLocalTextFile } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { join } from "path-ts";
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download";
+const SLUG = "usgov-nad";
+const FEATURE_SERVICE_URL = "https://services.arcgis.com/xOi1kZaI0eWDREZv/ArcGIS/rest/services/Address_Points_from_National_Address_Database_view/FeatureServer/0";
+/**
+ * ArcGIS paged reads. Retry is ON: the loop walks OBJECTID ranges to completion, so one throttled page previously ended
+ * a multi-hour national download. No rate budget — pages are requested one at a time and each assembles thousands of
+ * records server-side.
+ */
+const nadClient = new APIClient({
+    displayName: "nad",
+    retry: true,
+    axios: { headers: { "Accept-Encoding": "gzip, br" } },
+});
+async function fetchPage(startOID, endOID, pageSize) {
+    const url = new URL(`${FEATURE_SERVICE_URL}/query`);
+    url.searchParams.set("where", `OBJECTID BETWEEN ${startOID} AND ${endOID}`);
+    url.searchParams.set("outFields", "*");
+    url.searchParams.set("f", "json");
+    url.searchParams.set("resultRecordCount", String(pageSize));
+    const data = await nadClient
+        .fetch({
+        url: url.toString(),
+        timeout: 120_000,
+    })
+        .then(pluckResponseData);
+    if (data.error)
+        throw new Error(`ArcGIS error on OID ${startOID}-${endOID}: ${data.error.message}`);
+    return (data.features ?? []).map((f) => f.attributes);
+}
+async function discoverTotalCount() {
+    const url = new URL(`${FEATURE_SERVICE_URL}/query`);
+    url.searchParams.set("where", "1=1");
+    url.searchParams.set("returnCountOnly", "true");
+    url.searchParams.set("f", "json");
+    const data = await nadClient
+        .fetch({ url: url.toString(), timeout: 30_000 })
+        .then(pluckResponseData);
+    if (typeof data.count !== "number")
+        throw new Error("NAD count query returned no count field");
+    return data.count;
+}
+/**
+ * Fetch a single chunk by paging through its OID range with bounded concurrency. Returns the count of records written
+ * and the count of pages that errored. The caller decides whether to mark the chunk complete based on errors === 0.
+ *
+ * NOTE(phase1): this is a JSON API pager, not a file download — the shared `downloadToFile` doesn't apply here.
+ */
+async function fetchChunk(chunkPath, chunkStart, chunkEnd, pageSize, concurrency, report) {
+    const pageRanges = [];
+    for (let cursor = chunkStart; cursor <= chunkEnd; cursor += pageSize) {
+        pageRanges.push([cursor, Math.min(cursor + pageSize - 1, chunkEnd)]);
+    }
+    // Run bounded-concurrency page fetches. Results indexed by page slot for in-order write.
+    const pageResults = pageRanges.map(() => ({
+        rows: [],
+        error: null,
+    }));
+    let nextSlot = 0;
+    const workers = Array.from({ length: Math.min(concurrency, pageRanges.length) }, async () => {
+        while (true) {
+            const slot = nextSlot++;
+            if (slot >= pageRanges.length)
+                return;
+            const [s, e] = pageRanges[slot];
+            try {
+                pageResults[slot].rows = await fetchPage(s, e, pageSize);
+            }
+            catch (error) {
+                pageResults[slot].error = error;
+                report?.(`    ✗ page ${s}-${e}: ${error.message}`);
+            }
+        }
+    });
+    await Promise.all(workers);
+    // Single-writer phase — write all pages in OID order to keep NDJSON deterministic.
+    const lines = [];
+    let errors = 0;
+    for (const { rows, error } of pageResults) {
+        if (error) {
+            errors++;
+            continue;
+        }
+        for (const row of rows) {
+            lines.push(JSON.stringify(row));
+        }
+    }
+    await writeLocalTextFile(!lines.length ? "" : lines.join("\n") + "\n", chunkPath);
+    return { recordCount: lines.length, errors };
+}
+async function featureserverMode(options, report) {
+    const chunkSize = options.chunkSize ?? 100_000;
+    const pageSize = options.pageSize ?? 5000;
+    const concurrency = options.concurrency ?? 4;
+    const startOID = options.startOID ?? 1;
+    const chunkDir = join(options.outRoot, SLUG, "featureserver");
+    await makeDirectories(chunkDir);
+    report?.(`=== ${SLUG} / featureserver`);
+    report?.(`  Discovering record count ...`);
+    const totalCount = await discoverTotalCount();
+    const endOID = options.endOID ?? totalCount;
+    report?.(`  Total records: ${totalCount.toLocaleString()}`);
+    report?.(`  OID range: ${startOID.toLocaleString()} .. ${endOID.toLocaleString()}`);
+    report?.(`  Chunk size: ${chunkSize}, page size: ${pageSize}, concurrency: ${concurrency}`);
+    let fetched = 0;
+    let skipped = 0;
+    let totalRecords = 0;
+    let totalErrors = 0;
+    const failedCodes = [];
+    for (let cursor = startOID; cursor <= endOID; cursor += chunkSize) {
+        const chunkEnd = Math.min(cursor + chunkSize - 1, endOID);
+        const chunkName = `oids_${cursor}-${chunkEnd}`;
+        const chunkPath = join(chunkDir, `${chunkName}.ndjson`);
+        const manifestPath = join(chunkDir, `${chunkName}.manifest.json`);
+        // Idempotency: skip a chunk only if it's marked complete (the bash version's bug was
+        // marking complete on partial-failure runs; we now only set complete after a clean fetch).
+        if (await pathExists(chunkPath)) {
+            const recorded = await readManifest(manifestPath);
+            if (recorded?.complete) {
+                skipped++;
+                continue;
+            }
+        }
+        report?.(`  Fetching ${chunkName} ...`);
+        const t0 = Date.now();
+        const { recordCount, errors } = await fetchChunk(chunkPath, cursor, chunkEnd, pageSize, concurrency, report);
+        const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
+        const bytes = (await statPath(chunkPath)).size;
+        const sha = await sha256File(chunkPath);
+        const manifest = {
+            source_url: FEATURE_SERVICE_URL,
+            oid_range: [cursor, chunkEnd],
+            downloaded_at: new Date().toISOString(),
+            filename: `${chunkName}.ndjson`,
+            sha256: sha,
+            bytes,
+            record_count: recordCount,
+            page_errors: errors,
+            complete: errors === 0,
+        };
+        await writeManifest(manifestPath, manifest);
+        const status = errors === 0 ? "✓" : `⚠ ${errors} page errors`;
+        report?.(`    ${status}  ${recordCount.toLocaleString()} records in ${elapsed}s  (${(bytes / 1024 / 1024).toFixed(1)} MB)`);
+        fetched++;
+        totalRecords += recordCount;
+        totalErrors += errors;
+        if (errors > 0) {
+            failedCodes.push(chunkName);
+        }
+    }
+    report?.(`=== featureserver summary ===`);
+    report?.(`chunks fetched: ${fetched}  skipped: ${skipped}`);
+    report?.(`total records: ${totalRecords.toLocaleString()}`);
+    report?.(`page errors:   ${totalErrors}`);
+    report?.(`output:        ${chunkDir}`);
+    // `failed` counts page errors (the old exit-1 condition), `failedCodes` names the dirty chunks.
+    return { fetched, skipped, failed: totalErrors, failedCodes };
+}
+async function bulkMode(options, report) {
+    if (!options.nadURL) {
+        throw new Error(`bulk mode requires --nad-url. The DOT page is Akamai-gated; ` +
+            `visit https://www.transportation.gov/gis/national-address-database in a browser, ` +
+            `accept the disclaimer, and re-run with the pre-signed S3 URL.`);
+    }
+    const destDir = join(options.outRoot, SLUG);
+    await makeDirectories(destDir);
+    const filename = new URL(options.nadURL).pathname.split("/").pop() ?? "NAD.zip";
+    const destPath = join(destDir, filename);
+    report?.(`=== ${SLUG} / ${filename}`);
+    report?.(`  URL: ${options.nadURL.slice(0, 100)}${options.nadURL.length > 100 ? "…" : ""}`);
+    const { bytes } = await downloadToFile({ url: options.nadURL, dest: destPath, timeoutMs: 3 * 3600 * 1000, report });
+    const sha = await sha256File(destPath);
+    await writeManifest(join(destDir, "MANIFEST.json"), {
+        source_url: options.nadURL,
+        downloaded_at: new Date().toISOString(),
+        filename,
+        sha256: sha,
+        bytes,
+    });
+    report?.(`  ✓ ${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB  sha256=${sha}`);
+    return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] };
+}
+export async function fetchNAD(options, report) {
+    const mode = options.mode ?? "featureserver";
+    if (mode === "featureserver") {
+        return featureserverMode(options, report);
+    }
+    if (mode === "bulk") {
+        return bulkMode(options, report);
+    }
+    throw new Error(`unknown mode "${String(mode)}" (expected featureserver|bulk)`);
+}
+//# sourceMappingURL=nad.js.map

package/out/tools/fetch/nad.js.map

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

package/out/tools/fetch/nppes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Re-fetch the NPPES (National Plan and Provider Enumeration System) full monthly data
+ *   dissemination file. ~7M provider rows with venue+address data. Source for the `usgov-nppes`
+ *   adapter. US Public Domain.
+ *
+ *   The file is published monthly by CMS. This module discovers the current filename by scraping the
+ *   NPI_Files.html index, then downloads the ZIP and extracts only the main registry CSV
+ *   (npidata_pfile_*.csv). The smaller endpoint/othername/pl files stay zipped — we don't need them.
+ *
+ *   Uses Node's built-in fetch (gzip/brotli) to parse the HTML index and download the ZIP, and
+ *   streaming sha256 instead of sha256sum. The ZIP is unpacked with the `unzip` binary via
+ *   `node:child_process` (no clean Node equivalent for member listing + selective extraction). NOTE:
+ *   the old bash fetcher used `curl --continue-at -` to resume a partial download; native fetch has
+ *   no resume, so a partial run re-downloads from the start.
+ *
+ *   Invoke via `mailwoman corpus fetch nppes --out-root <path>`. Idempotent: if dest CSV exists and
+ *   sha256 matches MANIFEST, skips download.
+ */
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
+export type FetchNPPESOptions = BaseFetchOptions;
+export declare function fetchNPPES(options: FetchNPPESOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=nppes.d.ts.map

package/out/tools/fetch/nppes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nppes.d.ts","sourceRoot":"","sources":["../../../lib/tools/fetch/nppes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,uBAAuB,CAAA;AAO3F,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAA;AAmChD,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAyFnH"}