@mailwoman/corpus 5.9.0 → 5.10.1

package/out/src/tools/fetch/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../../../src/tools/fetch/download.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACtD,OAAO,EAAE,UAAU,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAgB1D,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC/C,OAAO,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,IAAI,MAAM,IAAI,GAAG,CAAC,CAAA;AAC1D,CAAC;AAeD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAwB;IAC5D,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,EAAE,OAAO,GAAG,CAAC,EAAE,YAAY,GAAG,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACtG,IAAI,SAAkB,CAAA;IAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACrD,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YACjB,MAAM,EAAE,CAAC,SAAS,OAAO,IAAI,OAAO,UAAU,YAAY,QAAQ,GAAG,EAAE,CAAC,CAAA;YACxE,MAAM,KAAK,CAAC,YAAY,CAAC,CAAA;QAC1B,CAAC;QAED,IAAI,GAAa,CAAA;QAEjB,IAAI,CAAC;YACJ,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;QAC5E,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,iEAAiE;YACjE,SAAS,GAAG,KAAK,CAAA;YACjB,SAAQ;QACT,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,MAAM,GAAG,EAAE,CAAC,CAAA;YAExE,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,MAAM,KAAK,CAAA;YAC/C,SAAS,GAAG,KAAK,CAAA;YACjB,SAAQ;QACT,CAAC;QAED,IAAI,CAAC;YACJ,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAA;YACnD,MAAM,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YAE7B,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE,CAAA;QACpC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,8DAA8D;YAC9D,SAAS,GAAG,KAAK,CAAA;QAClB,CAAC;IACF,CAAC;IAED,MAAM,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAA;AAC5E,CAAC;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,IAAY;IACjD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAElC,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAM,CAAA;IACrD,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,IAAI,CAAA;IACZ,CAAC;AACF,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAI,IAAY,EAAE,GAAyB;IACnF,MAAM,OAAO,GAAG,IAAI,GAAG,EAAa,CAAA;IACpC,MAAM,MAAM,GAAG,MAAM,YAAY,CAAM,IAAI,CAAC,CAAA;IAE5C,KAAK,MAAM,KAAK,IAAI,MAAM,IAAI,EAAE,EAAE,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAA;IAC/B,CAAC;IAED,OAAO,OAAO,CAAA;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY,EAAE,QAAiB;IAClE,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;AAChE,CAAC"}

package/out/src/tools/fetch/hrsa.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Re-fetch the HRSA Health Center Service Delivery Sites CSV. Source for the `usgov-hrsa-fqhc`
+ *   adapter. US Public Domain.
+ *
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum, and
+ *   writes the same sibling `MANIFEST.json` (origin URL + fetch timestamp + byte count + sha256) so
+ *   downstream adapters can verify provenance.
+ *
+ *   Invoke via `mailwoman corpus fetch hrsa --out-root <path>`.
+ */
+import type { BaseFetchOptions, FetchSummary } from "./download.ts";
+export type FetchHRSAOptions = BaseFetchOptions;
+export declare function fetchHRSA(options: FetchHRSAOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=hrsa.d.ts.map

package/out/src/tools/fetch/hrsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hrsa.d.ts","sourceRoot":"","sources":["../../../../src/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAOnE,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAU/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CA2BjH"}

package/out/src/tools/fetch/hrsa.js

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Re-fetch the HRSA Health Center Service Delivery Sites CSV. Source for the `usgov-hrsa-fqhc`
+ *   adapter. US Public Domain.
+ *
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum, and
+ *   writes the same sibling `MANIFEST.json` (origin URL + fetch timestamp + byte count + sha256) so
+ *   downstream adapters can verify provenance.
+ *
+ *   Invoke via `mailwoman corpus fetch hrsa --out-root <path>`.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sha256File } from "@mailwoman/core/utils";
+import { downloadToFile, writeManifest } from "./download.js";
+const SLUG = "usgov-hrsa-fqhc";
+const FILENAME = "Health_Center_Service_Delivery_and_LookAlike_Sites.csv";
+const SOURCE_URL = `https://data.hrsa.gov/DataDownload/DD_Files/${FILENAME}`;
+export async function fetchHRSA(options, report) {
+    const destDir = join(options.outRoot, SLUG);
+    mkdirSync(destDir, { recursive: true });
+    const dest = join(destDir, FILENAME);
+    report?.(`=== ${SLUG} / ${FILENAME}`);
+    const { bytes } = await downloadToFile({
+        url: SOURCE_URL,
+        dest,
+        timeoutMs: 600_000,
+        headers: { "Accept-Encoding": "gzip, br" },
+        report,
+    });
+    const sha = await sha256File(dest);
+    const manifest = {
+        source_url: SOURCE_URL,
+        downloaded_at: new Date().toISOString(),
+        filename: FILENAME,
+        sha256: sha,
+        bytes,
+    };
+    await writeManifest(join(destDir, "MANIFEST.json"), manifest);
+    report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`);
+    return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] };
+}
+//# sourceMappingURL=hrsa.js.map

package/out/src/tools/fetch/hrsa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hrsa.js","sourceRoot":"","sources":["../../../../src/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGlD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7D,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAC9B,MAAM,QAAQ,GAAG,wDAAwD,CAAA;AACzE,MAAM,UAAU,GAAG,+CAA+C,QAAQ,EAAE,CAAA;AAY5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB,EAAE,MAA+B;IACzF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC3C,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACvC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAEpC,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,QAAQ,EAAE,CAAC,CAAA;IACrC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC;QACtC,GAAG,EAAE,UAAU;QACf,IAAI;QACJ,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,EAAE,iBAAiB,EAAE,UAAU,EAAE;QAC1C,MAAM;KACN,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAA;IAElC,MAAM,QAAQ,GAAmB;QAChC,UAAU,EAAE,UAAU;QACtB,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,GAAG;QACX,KAAK;KACL,CAAA;IACD,MAAM,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;IAE7D,MAAM,EAAE,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,GAAG,EAAE,CAAC,CAAA;IAErE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,CAAA;AAC9D,CAAC"}

package/out/src/tools/fetch/imls-pls.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Re-fetch the IMLS Public Libraries Survey (PLS) outlet-level data. Each US public library branch
+ *   (outlet) is one row, ~17K rows with address fields. Source for the `usgov-imls-pls` adapter. US
+ *   Public Domain (federal statistical survey).
+ *
+ *   The FY 2023 release is the most current as of 2026-05. IMLS ships a single ZIP containing CSV,
+ *   SAS, and SPSS variants. We extract the outlet-level CSV (pls_fy*_outlet*.csv or similar) and
+ *   discard the rest. The administrative-entity (system-level) CSV is intentionally skipped — it has
+ *   no per-branch address detail.
+ *
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. The
+ *   ZIP is unpacked with the `unzip` binary via `node:child_process` (no clean Node equivalent for
+ *   member listing + selective extraction).
+ *
+ *   Invoke via `mailwoman corpus fetch imls-pls --out-root <path>`. Idempotent: if dest CSV exists
+ *   and sha matches MANIFEST, skips download.
+ */
+import type { BaseFetchOptions, FetchSummary } from "./download.ts";
+export type FetchIMLSPLSOptions = BaseFetchOptions;
+export declare function fetchIMLSPLS(options: FetchIMLSPLSOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=imls-pls.d.ts.map

package/out/src/tools/fetch/imls-pls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imls-pls.d.ts","sourceRoot":"","sources":["../../../../src/tools/fetch/imls-pls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAUH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAUnE,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAA;AAoBlD,wBAAsB,YAAY,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CAkGvB"}

package/out/src/tools/fetch/imls-pls.js

@@ -0,0 +1,120 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Re-fetch the IMLS Public Libraries Survey (PLS) outlet-level data. Each US public library branch
+ *   (outlet) is one row, ~17K rows with address fields. Source for the `usgov-imls-pls` adapter. US
+ *   Public Domain (federal statistical survey).
+ *
+ *   The FY 2023 release is the most current as of 2026-05. IMLS ships a single ZIP containing CSV,
+ *   SAS, and SPSS variants. We extract the outlet-level CSV (pls_fy*_outlet*.csv or similar) and
+ *   discard the rest. The administrative-entity (system-level) CSV is intentionally skipped — it has
+ *   no per-branch address detail.
+ *
+ *   Uses Node's built-in fetch (gzip/brotli) and streaming sha256 instead of curl + sha256sum. The
+ *   ZIP is unpacked with the `unzip` binary via `node:child_process` (no clean Node equivalent for
+ *   member listing + selective extraction).
+ *
+ *   Invoke via `mailwoman corpus fetch imls-pls --out-root <path>`. Idempotent: if dest CSV exists
+ *   and sha matches MANIFEST, skips download.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, statSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { sha256File } from "@mailwoman/core/utils";
+import { downloadToFile, readManifest, writeManifest } from "./download.js";
+const execFileAsync = promisify(execFile);
+// The PLS FY 2023 bulk CSV ZIP (most recent as of 2026-05).
+// If IMLS publishes a newer year, update this URL.
+const ZIP_URL = "https://www.imls.gov/sites/default/files/2025-08/pls_fy2023_csv.zip";
+const SLUG = "usgov-imls-pls";
+/** Return the filenames listed inside a ZIP (the trailing column of each `unzip -l` row). */
+async function listZipEntries(zipPath) {
+    const listing = await execFileAsync("unzip", ["-l", zipPath]);
+    return listing.stdout
+        .split("\n")
+        .map((line) => line.trim().split(/\s+/).pop() ?? "")
+        .filter((name) => name.length > 0);
+}
+export async function fetchIMLSPLS(options, report) {
+    const destDir = join(options.outRoot, SLUG);
+    mkdirSync(destDir, { recursive: true });
+    const zipDest = join(destDir, basename(ZIP_URL));
+    const manifestPath = join(destDir, "MANIFEST.json");
+    report?.(`=== ${SLUG}`);
+    // ------------------------------------------------------------------
+    // Idempotency check: if outlet CSV already exists and sha matches, skip.
+    // ------------------------------------------------------------------
+    const recorded = await readManifest(manifestPath);
+    if (recorded?.sha256 && recorded.filename) {
+        const recordedPath = join(destDir, recorded.filename);
+        if (existsSync(recordedPath) && (await sha256File(recordedPath)) === recorded.sha256) {
+            report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.");
+            return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] };
+        }
+    }
+    // ------------------------------------------------------------------
+    // Download ZIP
+    // ------------------------------------------------------------------
+    report?.(`  Downloading ${ZIP_URL} ...`);
+    const { bytes: zipSize } = await downloadToFile({
+        url: ZIP_URL,
+        dest: zipDest,
+        timeoutMs: 600_000,
+        headers: { "Accept-Encoding": "gzip, br" },
+        report,
+    });
+    report?.(`  Downloaded: ${(zipSize / 1024 / 1024).toFixed(1)} MB`);
+    if (zipSize < 1024) {
+        report?.(`  ✗ Response too small (${zipSize} bytes) — probable error page`);
+        return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] };
+    }
+    // ------------------------------------------------------------------
+    // Discover the outlet-level CSV inside the ZIP.
+    // Outlet files match: pls_fy*outlet*.csv (case-insensitive)
+    // Administrative-entity files match: pls_fy*ae*.csv — we skip those.
+    // ------------------------------------------------------------------
+    report?.("  Inspecting ZIP contents ...");
+    const entries = await listZipEntries(zipDest);
+    let csvName = entries.find((name) => /pls_fy.*outlet.*\.csv/i.test(name));
+    // Fallback: if IMLS renames the file, grab any CSV that is NOT the ae file.
+    if (!csvName) {
+        csvName = entries.find((name) => /\.csv$/i.test(name) && !/system|state|_ae\b|_se\b/i.test(name));
+    }
+    if (!csvName) {
+        report?.("  Available files in ZIP:");
+        for (const name of entries) {
+            report?.(`    ${name}`);
+        }
+        report?.("  ✗ Could not identify outlet CSV — inspect above listing and update this module");
+        return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] };
+    }
+    report?.(`  Extracting outlet CSV: ${csvName}`);
+    await execFileAsync("unzip", ["-o", "-j", zipDest, csvName, "-d", destDir]);
+    const csvDest = join(destDir, basename(csvName));
+    const csvSize = statSync(csvDest).size;
+    const csvSha = await sha256File(csvDest);
+    // ------------------------------------------------------------------
+    // Remove ZIP (small, but keep destDir clean)
+    // ------------------------------------------------------------------
+    await rm(zipDest, { force: true });
+    report?.("  Removed ZIP (CSV kept)");
+    // ------------------------------------------------------------------
+    // Write MANIFEST
+    // ------------------------------------------------------------------
+    const manifest = {
+        source_url: ZIP_URL,
+        downloaded_at: new Date().toISOString(),
+        filename: basename(csvName),
+        sha256: csvSha,
+        bytes: csvSize,
+    };
+    await writeManifest(manifestPath, manifest);
+    report?.(`  ✓ ${(csvSize / 1024 / 1024).toFixed(1)} MB  sha256=${csvSha}`);
+    report?.(`  MANIFEST written to ${manifestPath}`);
+    return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] };
+}
+//# sourceMappingURL=imls-pls.js.map

package/out/src/tools/fetch/imls-pls.js.map

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

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

@@ -0,0 +1,118 @@
+/**
+ * @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).
+ *   - `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.
+ *   - `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 (XLSX → CSV via openpyxl). 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 gate
+ *   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 /mnt/playpen/mailwoman-data/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 "./ban.ts";
+import { fetchHRSA } from "./hrsa.ts";
+import { fetchIMLSPLS } from "./imls-pls.ts";
+import { fetchNAD } from "./nad.ts";
+import { fetchNPPES } from "./nppes.ts";
+import { fetchOpenAddresses } from "./openaddresses.ts";
+import { fetchStateHISchools } from "./state-hi-schools.ts";
+import { fetchStateSources } from "./state-sources.ts";
+import { fetchTigerFull } from "./tiger-full.ts";
+export * from "./ban.ts";
+export * from "./hrsa.ts";
+export * from "./imls-pls.ts";
+export * from "./nad.ts";
+export * from "./nppes.ts";
+export * from "./openaddresses.ts";
+export * from "./state-hi-schools.ts";
+export * from "./state-sources.ts";
+export * from "./tiger-full.ts";
+/** 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 hrsa: typeof fetchHRSA;
+    readonly "imls-pls": typeof fetchIMLSPLS;
+    readonly nppes: typeof fetchNPPES;
+    readonly openaddresses: typeof fetchOpenAddresses;
+    readonly "state-sources": typeof fetchStateSources;
+    readonly "state-hi-schools": typeof fetchStateHISchools;
+    readonly "tiger-full": typeof fetchTigerFull;
+};
+export type FetchSourceID = keyof typeof FETCH_SOURCES;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAE/B,4GAA4G;AAC5G,eAAO,MAAM,aAAa;;;;;;;;;;CAUhB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,aAAa,CAAA"}

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

@@ -0,0 +1,117 @@
+/**
+ * @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).
+ *   - `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.
+ *   - `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 (XLSX → CSV via openpyxl). 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 gate
+ *   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 /mnt/playpen/mailwoman-data/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 "./ban.js";
+import { fetchHRSA } from "./hrsa.js";
+import { fetchIMLSPLS } from "./imls-pls.js";
+import { fetchNAD } from "./nad.js";
+import { fetchNPPES } from "./nppes.js";
+import { fetchOpenAddresses } from "./openaddresses.js";
+import { fetchStateHISchools } from "./state-hi-schools.js";
+import { fetchStateSources } from "./state-sources.js";
+import { fetchTigerFull } from "./tiger-full.js";
+export * from "./ban.js";
+export * from "./hrsa.js";
+export * from "./imls-pls.js";
+export * from "./nad.js";
+export * from "./nppes.js";
+export * from "./openaddresses.js";
+export * from "./state-hi-schools.js";
+export * from "./state-sources.js";
+export * from "./tiger-full.js";
+/** The fetch-source registry: id → module entry point. Each entry point takes its own options interface. */
+export const FETCH_SOURCES = {
+    ban: fetchBan,
+    nad: fetchNAD,
+    hrsa: fetchHRSA,
+    "imls-pls": fetchIMLSPLS,
+    nppes: fetchNPPES,
+    openaddresses: fetchOpenAddresses,
+    "state-sources": fetchStateSources,
+    "state-hi-schools": fetchStateHISchools,
+    "tiger-full": fetchTigerFull,
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/tools/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,cAAc,UAAU,CAAA;AACxB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,oBAAoB,CAAA;AAClC,cAAc,uBAAuB,CAAA;AACrC,cAAc,oBAAoB,CAAA;AAClC,cAAc,iBAAiB,CAAA;AAE/B,4GAA4G;AAC5G,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,GAAG,EAAE,QAAQ;IACb,GAAG,EAAE,QAAQ;IACb,IAAI,EAAE,SAAS;IACf,UAAU,EAAE,YAAY;IACxB,KAAK,EAAE,UAAU;IACjB,aAAa,EAAE,kBAAkB;IACjC,eAAe,EAAE,iBAAiB;IAClC,kBAAkB,EAAE,mBAAmB;IACvC,YAAY,EAAE,cAAc;CACnB,CAAA"}

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

@@ -0,0 +1,56 @@
+/**
+ * @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 /mnt/playpen/mailwoman-data/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 "./download.ts";
+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/src/tools/fetch/nad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nad.d.ts","sourceRoot":"","sources":["../../../../src/tools/fetch/nad.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAOnE,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACxD,+CAA+C;IAC/C,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAA;IAC/B,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAiOD,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAY/G"}