@mailwoman/corpus 9.4.0 → 10.0.0

package/out/us/adapters/usgov/nppes/adapter.js

@@ -0,0 +1,110 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-nppes`: CMS National Plan and Provider Enumeration System (NPI registry) CSV consumer.
+ *
+ *   NPPES is the authoritative US healthcare provider registry, published monthly by CMS. Each row
+ *   carries a provider's business practice location address together with their legal business name
+ *   or individual name. At ~7M rows it is the single largest venue+address signal source
+ *   available.
+ *
+ *   The adapter consumes the monthly full-replacement CSV (operator pre-downloads via
+ *   `fetch-nppes.ts`). Column names match the canonical NPPES "Full Replacement Monthly NPI File"
+ *   header published at `https://download.cms.gov/nppes/NPI_Files.html`.
+ *
+ *   Output: one row per CSV record where the practice location address is populated. Organization
+ *   rows carry `venue` from the legal business name; individual rows compose `attention` from
+ *   last+first name. Address quad goes on `(house_number, street, locality, region, postcode)`.
+ *
+ *   License: stamped `"Public Domain"` per CMS's federal government distribution terms.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address-format";
+import { isPresent } from "@mailwoman/core/objects";
+import { formatPersonName } from "@mailwoman/record/name";
+import { CSVSpliterator } from "spliterator";
+import { splitStreetLine, stableSourceID } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#us/fips-state";
+/**
+ * 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 USGOV_NPPES_ADAPTER_ID = "usgov-nppes";
+/**
+ * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain";
+export function createUsgovNPPESAdapter() {
+    return {
+        id: USGOV_NPPES_ADAPTER_ID,
+        defaultLicense: USGOV_NPPES_DEFAULT_LICENSE,
+        description: "CMS National Plan and Provider Enumeration System — 7M provider practice locations (public-domain). Venue+address co-occurrence at scale.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-nppes adapter: only US supported, got country=${opts.country}`);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                normalizeKeys: false,
+            });
+            let emitted = 0;
+            for await (const record of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const npi = (record.NPI ?? "").trim();
+                const orgName = (record["Provider Organization Name (Legal Business Name)"] ?? "").trim();
+                const lastName = (record["Provider Last Name (Legal Name)"] ?? "").trim();
+                const firstName = (record["Provider First Name"] ?? "").trim();
+                const address1 = (record["Provider First Line Business Practice Location Address"] ?? "").trim();
+                const address2 = (record["Provider Second Line Business Practice Location Address"] ?? "").trim();
+                const city = (record["Provider Business Practice Location Address City Name"] ?? "").trim();
+                const stateRaw = (record["Provider Business Practice Location Address State Name"] ?? "").trim();
+                const postcode = (record["Provider Business Practice Location Address Postcode"] ?? "").trim();
+                if (!city || !postcode)
+                    continue;
+                const state = lookupStateAbbreviation(stateRaw);
+                if (!state)
+                    continue;
+                const fullStreet = [address1, address2].filter(isPresent).join(" ");
+                const split = splitStreetLine(fullStreet);
+                if (!split)
+                    continue;
+                const venue = orgName || formatPersonName({ given: firstName, family: lastName }, "short") || undefined;
+                const components = {
+                    ...(venue ? { venue } : {}),
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode,
+                };
+                const rendered = formatAddressRow(components, "US", { singleLine: true });
+                if (!rendered)
+                    continue;
+                const { raw, components: aligned } = rendered;
+                if (Object.keys(aligned).length <= 2)
+                    continue;
+                const sourceID = npi ? `${USGOV_NPPES_ADAPTER_ID}-${npi}` : stableSourceID(USGOV_NPPES_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: USGOV_NPPES_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: USGOV_NPPES_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const usgovNPPESAdapter = createUsgovNPPESAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/us/adapters/usgov/nppes/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../../../lib/us/adapters/usgov/nppes/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAExD;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAA;AACnD;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,eAAe,CAAA;AAe1D,MAAM,UAAU,uBAAuB;IACtC,OAAO;QACN,EAAE,EAAE,sBAAsB;QAC1B,cAAc,EAAE,2BAA2B;QAC3C,WAAW,EACV,2IAA2I;QAE5I,KAAK,CAAC,CAAC,IAAI,CAAC,IAAoB;YAC/B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,uDAAuD,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YACvF,CAAC;YAED,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE;gBACrD,aAAa,EAAE,KAAK;aACpB,CAAC,CAAA;YAEF,IAAI,OAAO,GAAG,CAAC,CAAA;YAEf,IAAI,KAAK,EAAE,MAAM,MAAM,IAAI,IAA+B,EAAE,CAAC;gBAC5D,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;oBAAE,MAAK;gBAE/B,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,IAAI,CAAC,KAAK;oBAAE,MAAK;gBAE5D,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBACrC,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,kDAAkD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBACzF,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,iCAAiC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBACzE,MAAM,SAAS,GAAG,CAAC,MAAM,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBAE9D,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,wDAAwD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBAChG,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,yDAAyD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBACjG,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,uDAAuD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBAC3F,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,wDAAwD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBAChG,MAAM,QAAQ,GAAG,CAAC,MAAM,CAAC,sDAAsD,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;gBAE9F,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;oBAAE,SAAQ;gBAEhC,MAAM,KAAK,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAA;gBAE/C,IAAI,CAAC,KAAK;oBAAE,SAAQ;gBAEpB,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBACnE,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC,CAAA;gBAEzC,IAAI,CAAC,KAAK;oBAAE,SAAQ;gBAEpB,MAAM,KAAK,GAAG,OAAO,IAAI,gBAAgB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,OAAO,CAAC,IAAI,SAAS,CAAA;gBAEvG,MAAM,UAAU,GAA+B;oBAC9C,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC3B,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnE,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,QAAQ,EAAE,IAAI;oBACd,MAAM,EAAE,KAAK,CAAC,YAAY;oBAC1B,QAAQ;iBACR,CAAA;gBAED,MAAM,QAAQ,GAAG,gBAAgB,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;gBAEzE,IAAI,CAAC,QAAQ;oBAAE,SAAQ;gBAEvB,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAA;gBAE7C,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,IAAI,CAAC;oBAAE,SAAQ;gBAE9C,MAAM,QAAQ,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,sBAAsB,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAA;gBAE3G,MAAM;oBACL,GAAG;oBACH,UAAU,EAAE,OAAO;oBACnB,OAAO,EAAE,IAAI;oBACb,MAAM,EAAE,OAAO;oBACf,MAAM,EAAE,sBAAsB;oBAC9B,SAAS,EAAE,QAAQ;oBACnB,cAAc,EAAE,EAAE;oBAClB,OAAO,EAAE,2BAA2B;iBACpC,CAAA;gBAED,OAAO,EAAE,CAAA;YACV,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,uBAAuB,EAAE,CAAA"}

package/out/us/adapters/usgov/samhsa-treatment-locator/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../lib/us/adapters/usgov/samhsa-treatment-locator/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAGzE;;;GAGG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAA;AACvE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,kBAAkB,CAAA;AA4D3D,wBAAgB,wCAAwC,IAAI,aAAa,CAsExE;AAED;;GAEG;AACH,eAAO,MAAM,kCAAkC,eAA6C,CAAA"}

package/out/us/adapters/usgov/samhsa-treatment-locator/adapter.js

@@ -0,0 +1,143 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-samhsa-treatment-locator`: SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   consumer.
+ *
+ *   SAMHSA's Treatment Locator (`findtreatment.gov`) is the federal directory of substance-use and
+ *   mental-health treatment facilities. The published CSV carries the facility name, an optional
+ *   secondary name (typically the organizational parent), and the postal address quad split into
+ *   primary + secondary street lines. Phase 1.6 §1.2 (#22) selects this source for the same reason
+ *   it selects HRSA: facility names are hand-typed venue strings and the addresses pass through
+ *   enough human + system hands to accumulate the suite-designator + sub-tenant chaos ("Suite C,
+ *   behind main building") that pure gazetteer data does not.
+ *
+ *   SAMHSA's two-line address shape is the key adapter-specific concern. `street1` typically carries
+ *   the canonical postal address (`"123 Main St"`); `street2` carries the suite / unit / "second
+ *   floor" surface form. The adapter joins them with `", "` into a single `street` component (Phase
+ *   1 keeps `unit` as a deferred slot since the OpenCage template doesn't have a clean rendering
+ *   for it). Operators wanting a different join policy can subclass the factory.
+ *
+ *   Column names below match the canonical SAMHSA Behavioral Health Treatment Services Locator CSV
+ *   export header. Operators substituting a closely-related extract should rename columns to match;
+ *   the README has the mapping cheatsheet.
+ *
+ *   License: stamped `"Public Domain"` per the SAMHSA Open Data Foundry's federal-government
+ *   distribution terms.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address-format";
+import { CSVSpliterator } from "spliterator";
+import { splitStreetLine, stableSourceID } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#us/fips-state";
+/**
+ * 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 USGOV_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator";
+/**
+ * License carried by this source (Public Domain), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export const USGOV_SAMHSA_DEFAULT_LICENSE = "Public Domain";
+/**
+ * Join the SAMHSA two-line street: primary street + optional secondary line (suite / unit / floor / "behind main
+ * building") on `", "`. The combined value is the `street` component surface form. Phase 1 does not break this out into
+ * the `unit` component — see the file-level comment.
+ */
+function joinTwoLineStreet(street1, street2) {
+    const s1 = street1.trim();
+    const s2 = (street2 ?? "").trim();
+    if (!s1 && !s2)
+        return "";
+    if (!s2)
+        return s1;
+    if (!s1)
+        return s2;
+    return `${s1}, ${s2}`;
+}
+/**
+ * Combine `name1` + optional `name2` into a single venue surface form. SAMHSA conventions:
+ *
+ * - `name1` is the program / clinic name ("Mountain Plains Counseling Services").
+ * - `name2` is the parent organization ("Catholic Charities of Wyoming"), if any.
+ *
+ * Both render together as `"<name1> - <name2>"` when both are present — geocoder users typically type either form, so
+ * the model benefits from the joined surface.
+ */
+function composeVenue(name1, name2) {
+    const n1 = name1.trim();
+    const n2 = (name2 ?? "").trim();
+    if (!n1 && !n2)
+        return "";
+    if (!n2)
+        return n1;
+    if (!n1)
+        return n2;
+    return `${n1} - ${n2}`;
+}
+export function createUsgovSamhsaTreatmentLocatorAdapter() {
+    return {
+        id: USGOV_SAMHSA_ADAPTER_ID,
+        defaultLicense: USGOV_SAMHSA_DEFAULT_LICENSE,
+        description: "SAMHSA Behavioral Health Treatment Services Locator (public-domain). Adversarial source: venue + two-line address co-occurrence, hand-entered.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-samhsa adapter: only US supported, got country=${opts.country}`);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                normalizeKeys: false,
+            });
+            let emitted = 0;
+            for await (const record of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const venue = composeVenue(record.name1 ?? "", record.name2);
+                const street = joinTwoLineStreet(record.street1 ?? "", record.street2);
+                const split = splitStreetLine(street);
+                const city = (record.city ?? "").trim();
+                const stateAbbr = (record.state ?? "").trim();
+                const postcode = (record.zip ?? "").trim();
+                if (!venue || !split || !city || !postcode)
+                    continue;
+                const state = lookupStateAbbreviation(stateAbbr);
+                if (!state)
+                    continue;
+                // venue first — same kryptonite-defending insertion order as HRSA.
+                const components = {
+                    venue,
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode,
+                };
+                const rendered = formatAddressRow(components, "US", { singleLine: true });
+                if (!rendered)
+                    continue;
+                const { raw, components: aligned } = rendered;
+                const frID = (record.frid ?? "").trim();
+                const sourceID = frID ? `${USGOV_SAMHSA_ADAPTER_ID}-${frID}` : stableSourceID(USGOV_SAMHSA_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: USGOV_SAMHSA_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: USGOV_SAMHSA_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const usgovSamhsaTreatmentLocatorAdapter = createUsgovSamhsaTreatmentLocatorAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/us/adapters/usgov/samhsa-treatment-locator/adapter.js.map

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

package/out/us/fips-state.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US Census FIPS state codes → two-letter abbreviation + full display name.
+ *
+ *   Covers all 50 states + DC + the five primary territories (PR, GU, VI, MP, AS).
+ *
+ *   The data is public-domain US Census reference (FIPS PUB 5-2, withdrawn but still the canonical
+ *   numeric ID used by every TIGER product). It is reproduced here so the TIGER adapter can resolve
+ *   `statefp` columns (e.g. `"50"`) into a `region` component (e.g. `"VT"`) without an extra DB
+ *   join.
+ */
+/**
+ * Per-state record: two-letter postal abbreviation + full canonical display name.
+ */
+export interface USStateInfo {
+    abbreviation: string;
+    name: string;
+}
+/**
+ * FIPS state-or-territory code → `{ abbreviation, name }`. Includes all 50 states, DC, and the five primary territories
+ * (PR, GU, VI, MP, AS). Codes are two-digit zero-padded strings to match TIGER column `statefp`.
+ */
+export declare const US_FIPS_STATE: Readonly<Record<string, USStateInfo>>;
+/**
+ * Lookup helper. Returns null when the FIPS code isn't recognized.
+ */
+export declare function lookupFipsState(statefp: string | null | undefined): USStateInfo | null;
+/**
+ * Inverted view: two-letter postal abbreviation → `USStateInfo`. Built once at module load. Used by adapters whose
+ * source data ships the abbreviation rather than the FIPS code (FCC BDC, most federal CSVs).
+ */
+export declare const US_STATE_BY_ABBREVIATION: Readonly<Record<string, USStateInfo>>;
+/**
+ * Lookup helper for adapters carrying 2-char USPS abbreviations (`"CA"`, `"VT"`). Case-folded; null for any value
+ * outside the 50 states + DC + the five primary territories.
+ */
+export declare function lookupStateAbbreviation(abbreviation: string | null | undefined): USStateInfo | null;
+//# sourceMappingURL=fips-state.d.ts.map

package/out/us/fips-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fips-state.d.ts","sourceRoot":"","sources":["../../lib/us/fips-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;CACZ;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA0D9D,CAAA;AAEF;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAItF;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAE1E,CAAA;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAInG"}

package/out/us/fips-state.js

@@ -0,0 +1,100 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US Census FIPS state codes → two-letter abbreviation + full display name.
+ *
+ *   Covers all 50 states + DC + the five primary territories (PR, GU, VI, MP, AS).
+ *
+ *   The data is public-domain US Census reference (FIPS PUB 5-2, withdrawn but still the canonical
+ *   numeric ID used by every TIGER product). It is reproduced here so the TIGER adapter can resolve
+ *   `statefp` columns (e.g. `"50"`) into a `region` component (e.g. `"VT"`) without an extra DB
+ *   join.
+ */
+/**
+ * FIPS state-or-territory code → `{ abbreviation, name }`. Includes all 50 states, DC, and the five primary territories
+ * (PR, GU, VI, MP, AS). Codes are two-digit zero-padded strings to match TIGER column `statefp`.
+ */
+export const US_FIPS_STATE = Object.freeze({
+    "01": { abbreviation: "AL", name: "Alabama" },
+    "02": { abbreviation: "AK", name: "Alaska" },
+    "04": { abbreviation: "AZ", name: "Arizona" },
+    "05": { abbreviation: "AR", name: "Arkansas" },
+    "06": { abbreviation: "CA", name: "California" },
+    "08": { abbreviation: "CO", name: "Colorado" },
+    "09": { abbreviation: "CT", name: "Connecticut" },
+    "10": { abbreviation: "DE", name: "Delaware" },
+    "11": { abbreviation: "DC", name: "District of Columbia" },
+    "12": { abbreviation: "FL", name: "Florida" },
+    "13": { abbreviation: "GA", name: "Georgia" },
+    "15": { abbreviation: "HI", name: "Hawaii" },
+    "16": { abbreviation: "ID", name: "Idaho" },
+    "17": { abbreviation: "IL", name: "Illinois" },
+    "18": { abbreviation: "IN", name: "Indiana" },
+    "19": { abbreviation: "IA", name: "Iowa" },
+    "20": { abbreviation: "KS", name: "Kansas" },
+    "21": { abbreviation: "KY", name: "Kentucky" },
+    "22": { abbreviation: "LA", name: "Louisiana" },
+    "23": { abbreviation: "ME", name: "Maine" },
+    "24": { abbreviation: "MD", name: "Maryland" },
+    "25": { abbreviation: "MA", name: "Massachusetts" },
+    "26": { abbreviation: "MI", name: "Michigan" },
+    "27": { abbreviation: "MN", name: "Minnesota" },
+    "28": { abbreviation: "MS", name: "Mississippi" },
+    "29": { abbreviation: "MO", name: "Missouri" },
+    "30": { abbreviation: "MT", name: "Montana" },
+    "31": { abbreviation: "NE", name: "Nebraska" },
+    "32": { abbreviation: "NV", name: "Nevada" },
+    "33": { abbreviation: "NH", name: "New Hampshire" },
+    "34": { abbreviation: "NJ", name: "New Jersey" },
+    "35": { abbreviation: "NM", name: "New Mexico" },
+    "36": { abbreviation: "NY", name: "New York" },
+    "37": { abbreviation: "NC", name: "North Carolina" },
+    "38": { abbreviation: "ND", name: "North Dakota" },
+    "39": { abbreviation: "OH", name: "Ohio" },
+    "40": { abbreviation: "OK", name: "Oklahoma" },
+    "41": { abbreviation: "OR", name: "Oregon" },
+    "42": { abbreviation: "PA", name: "Pennsylvania" },
+    "44": { abbreviation: "RI", name: "Rhode Island" },
+    "45": { abbreviation: "SC", name: "South Carolina" },
+    "46": { abbreviation: "SD", name: "South Dakota" },
+    "47": { abbreviation: "TN", name: "Tennessee" },
+    "48": { abbreviation: "TX", name: "Texas" },
+    "49": { abbreviation: "UT", name: "Utah" },
+    "50": { abbreviation: "VT", name: "Vermont" },
+    "51": { abbreviation: "VA", name: "Virginia" },
+    "53": { abbreviation: "WA", name: "Washington" },
+    "54": { abbreviation: "WV", name: "West Virginia" },
+    "55": { abbreviation: "WI", name: "Wisconsin" },
+    "56": { abbreviation: "WY", name: "Wyoming" },
+    // Territories
+    "60": { abbreviation: "AS", name: "American Samoa" },
+    "66": { abbreviation: "GU", name: "Guam" },
+    "69": { abbreviation: "MP", name: "Northern Mariana Islands" },
+    "72": { abbreviation: "PR", name: "Puerto Rico" },
+    "78": { abbreviation: "VI", name: "Virgin Islands" },
+});
+/**
+ * Lookup helper. Returns null when the FIPS code isn't recognized.
+ */
+export function lookupFipsState(statefp) {
+    if (!statefp)
+        return null;
+    return US_FIPS_STATE[statefp] ?? null;
+}
+/**
+ * Inverted view: two-letter postal abbreviation → `USStateInfo`. Built once at module load. Used by adapters whose
+ * source data ships the abbreviation rather than the FIPS code (FCC BDC, most federal CSVs).
+ */
+export const US_STATE_BY_ABBREVIATION = Object.freeze(Object.fromEntries(Object.values(US_FIPS_STATE).map((info) => [info.abbreviation, info])));
+/**
+ * Lookup helper for adapters carrying 2-char USPS abbreviations (`"CA"`, `"VT"`). Case-folded; null for any value
+ * outside the 50 states + DC + the five primary territories.
+ */
+export function lookupStateAbbreviation(abbreviation) {
+    if (!abbreviation)
+        return null;
+    return US_STATE_BY_ABBREVIATION[abbreviation.toUpperCase()] ?? null;
+}
+//# sourceMappingURL=fips-state.js.map

package/out/us/fips-state.js.map

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

package/out/us/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 "#tools/fetch/download/index";
+export type FetchHRSAOptions = BaseFetchOptions;
+export declare function fetchHRSA(options: FetchHRSAOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=hrsa.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hrsa.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,6BAA6B,CAAA;AAOjG,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAE/C,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CA8BjH"}

package/out/us/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 { makeDirectories } from "@mailwoman/core/fs/writers";
+import { sha256File } from "@mailwoman/core/hash";
+import { join } from "path-ts";
+import { downloadToFile, writeManifest } from "#tools/fetch/download/index";
+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);
+    await makeDirectories(destDir);
+    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/us/tools/fetch/hrsa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hrsa.js","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/hrsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAG9B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAE3E,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAC9B,MAAM,QAAQ,GAAG,wDAAwD,CAAA;AACzE,MAAM,UAAU,GAAG,+CAA+C,QAAQ,EAAE,CAAA;AAI5E,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAyB,EAAE,MAA+B;IACzF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IAC3C,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IAEpC,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,QAAQ,EAAE,CAAC,CAAA;IAErC,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;IAEF,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;IAED,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/us/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 "#tools/fetch/download/index";
+export type FetchIMLSPLSOptions = BaseFetchOptions;
+export declare function fetchIMLSPLS(options: FetchIMLSPLSOptions, report?: (line: string) => void): Promise<FetchSummary>;
+//# sourceMappingURL=imls-pls.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"imls-pls.d.ts","sourceRoot":"","sources":["../../../../lib/us/tools/fetch/imls-pls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAkB,MAAM,6BAA6B,CAAA;AAcjG,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAA;AAElD,wBAAsB,YAAY,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CAiGvB"}

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

@@ -0,0 +1,108 @@
+/**
+ * @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.
+ */
+/* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
+   procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
+import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters";
+import { statPath, pathExists } from "@mailwoman/core/fs/readers";
+import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers";
+import { extractZipEntry, listZipEntries } from "@mailwoman/core/fs/zip";
+import { sha256File } from "@mailwoman/core/hash";
+import { basename, join } from "path-ts";
+import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download/index";
+/**
+ * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
+ * than data.
+ */
+/**
+ * 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";
+export async function fetchIMLSPLS(options, report) {
+    const destDir = join(options.outRoot, SLUG);
+    await makeDirectories(destDir);
+    const zipDest = join(destDir, basename(ZIP_URL));
+    const manifestPath = join(destDir, "MANIFEST.json");
+    report?.(`=== ${SLUG}`);
+    // MARK: Idempotency check
+    const recorded = await readManifest(manifestPath);
+    if (recorded?.sha256 && recorded.filename) {
+        const recordedPath = join(destDir, recorded.filename);
+        if ((await pathExists(recordedPath)) && (await sha256File(recordedPath)) === recorded.sha256) {
+            report?.("  ✓ Already current (sha256 matches MANIFEST) — skipping download.");
+            return { fetched: 0, skipped: 1, failed: 0, failedCodes: [] };
+        }
+    }
+    // MARK: 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: ${ByteFormatter.formatIEC(zipSize)}`);
+    if (zipSize < BYTES_PER_KIB) {
+        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)).map((entry) => entry.name);
+    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}`);
+    const csvDest = join(destDir, basename(csvName));
+    await extractZipEntry(zipDest, csvName, csvDest);
+    const csvSize = (await statPath(csvDest)).size;
+    const csvSha = await sha256File(csvDest);
+    // MARK: Remove ZIP (small, but keep destDir clean)
+    await removePathIfPresent(zipDest);
+    report?.("  Removed ZIP (CSV kept)");
+    // MARK: 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