@mailwoman/corpus 9.1.0 → 9.3.0

package/out/adapters/usgov-irs-bmf/adapter.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-irs-bmf`: IRS Exempt Organizations Business Master File (EO BMF) CSV consumer.
+ *
+ *   The EO BMF is the IRS's authoritative registry of US tax-exempt organizations (charities,
+ *   churches, foundations, ...), published as per-region CSVs at
+ *   `https://www.irs.gov/charities-non-profits/exempt-organizations-business-master-file-extract-eo-bmf`
+ *   (`eo1.csv`..`eo4.csv`, `eo_pr.csv`, `eo_xx.csv`). Each row carries an organization NAME plus
+ *   its mailing address. It complements `usgov-nppes` with a DIFFERENT venue population
+ *   (non-profits vs healthcare providers) and, notably, a high share of PO-box addresses — useful
+ *   `po_box`-tag signal (a tag with historically low recall).
+ *
+ *   Output: one row per record with a usable city + postcode. NAME → `venue`; the street line becomes
+ *   `po_box` when it's a PO-box, else `house_number` + `street`; CITY/STATE/ZIP fill the locality
+ *   line. STATE is already a USPS abbreviation in the source. License: `"Public Domain"` (US
+ *   federal).
+ */
+import type { CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export declare const USGOV_IRS_BMF_ADAPTER_ID = "usgov-irs-bmf";
+/**
+ * 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 declare const USGOV_IRS_BMF_DEFAULT_LICENSE = "Public Domain";
+export declare function createUSGovIRSBMFAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const USGovIRSBMFAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/usgov-irs-bmf/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/usgov-irs-bmf/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAA;AACvD;;;GAGG;AACH,eAAO,MAAM,6BAA6B,kBAAkB,CAAA;AA+B5D,wBAAgB,wBAAwB,IAAI,aAAa,CA6ExD;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,eAA6B,CAAA"}

package/out/adapters/usgov-irs-bmf/adapter.js

@@ -0,0 +1,120 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-irs-bmf`: IRS Exempt Organizations Business Master File (EO BMF) CSV consumer.
+ *
+ *   The EO BMF is the IRS's authoritative registry of US tax-exempt organizations (charities,
+ *   churches, foundations, ...), published as per-region CSVs at
+ *   `https://www.irs.gov/charities-non-profits/exempt-organizations-business-master-file-extract-eo-bmf`
+ *   (`eo1.csv`..`eo4.csv`, `eo_pr.csv`, `eo_xx.csv`). Each row carries an organization NAME plus
+ *   its mailing address. It complements `usgov-nppes` with a DIFFERENT venue population
+ *   (non-profits vs healthcare providers) and, notably, a high share of PO-box addresses — useful
+ *   `po_box`-tag signal (a tag with historically low recall).
+ *
+ *   Output: one row per record with a usable city + postcode. NAME → `venue`; the street line becomes
+ *   `po_box` when it's a PO-box, else `house_number` + `street`; CITY/STATE/ZIP fill the locality
+ *   line. STATE is already a USPS abbreviation in the source. License: `"Public Domain"` (US
+ *   federal).
+ */
+import { isPresent } from "@mailwoman/core/objects";
+import { reconcileComponents } from "@mailwoman/formatter";
+import { CSVSpliterator } from "spliterator";
+import { composeRaw, splitStreetLine, stableSourceID } from "#adapters/utils";
+/**
+ * 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_IRS_BMF_ADAPTER_ID = "usgov-irs-bmf";
+/**
+ * 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_IRS_BMF_DEFAULT_LICENSE = "Public Domain";
+/**
+ * PO box in its many written forms: "PO BOX 12", "P.O. BOX 12", "P O BOX 12", "POB 12", "BOX 12".
+ */
+const PO_BOX = /^\s*(?:P\.?\s?O\.?\s*BOX|POB|BOX)\s+\w/i;
+/**
+ * Classify the street line into a `po_box` or a `{house_number?, street}` split.
+ *
+ * BMF mixes street addresses and PO boxes in one `STREET` column, so the PO-box shapes have to be claimed BEFORE the
+ * shared house-number split runs — otherwise `splitStreetLine` would hand back `"PO Box 1234"` as a plain street, which
+ * is correct for every other US adapter and wrong here.
+ */
+function splitStreetLineOrPOBox(street) {
+    const trimmed = street.trim();
+    if (PO_BOX.test(trimmed))
+        return { po_box: trimmed };
+    return splitStreetLine(trimmed);
+}
+export function createUSGovIRSBMFAdapter() {
+    return {
+        id: USGOV_IRS_BMF_ADAPTER_ID,
+        defaultLicense: USGOV_IRS_BMF_DEFAULT_LICENSE,
+        description: "IRS Exempt Organizations Business Master File — US non-profit venue+address (public-domain), with strong PO-box coverage.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-irs-bmf adapter: only US supported, got country=${opts.country}`);
+            }
+            const rows = CSVSpliterator.fromAsync(opts.inputPath, {
+                mode: "object",
+                normalizeKeys: false,
+                enableQuoteHandling: true,
+            });
+            let emitted = 0;
+            for await (const record of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const ein = (record.EIN ?? "").trim();
+                const venue = (record.NAME ?? "").trim() || undefined;
+                const street = (record.STREET ?? "").trim();
+                const city = (record.CITY ?? "").trim();
+                const state = (record.STATE ?? "").trim();
+                const zipRaw = (record.ZIP ?? "").trim();
+                if (!city || !zipRaw)
+                    continue;
+                const postcode = zipRaw.split("-")[0].trim(); // 5-digit; drop the optional +4
+                const split = splitStreetLineOrPOBox(street);
+                if (!split)
+                    continue;
+                const streetPart = "po_box" in split ? split.po_box : [split.house_number, split.street].filter(isPresent).join(" ");
+                const components = {
+                    ...(venue ? { venue } : {}),
+                    ...("po_box" in split
+                        ? { po_box: split.po_box }
+                        : { ...(split.house_number ? { house_number: split.house_number } : {}), street: split.street }),
+                    locality: city,
+                    ...(state ? { region: state } : {}),
+                    postcode,
+                };
+                const raw = composeRaw({ venue, streetLine: streetPart, locality: city, region: state, postcode });
+                if (!raw)
+                    continue;
+                const aligned = reconcileComponents(components, raw);
+                if (Object.keys(aligned).length <= 2)
+                    continue;
+                const sourceID = ein ? `${USGOV_IRS_BMF_ADAPTER_ID}-${ein}` : stableSourceID(USGOV_IRS_BMF_ADAPTER_ID, aligned);
+                yield {
+                    raw,
+                    components: aligned,
+                    country: "US",
+                    locale: "en-US",
+                    source: USGOV_IRS_BMF_ADAPTER_ID,
+                    source_id: sourceID,
+                    corpus_version: "",
+                    license: USGOV_IRS_BMF_DEFAULT_LICENSE,
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const USGovIRSBMFAdapter = createUSGovIRSBMFAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/usgov-irs-bmf/adapter.js.map

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

package/out/adapters/usgov-nad/adapter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-nad`: US DOT National Address Database — ~97M structured address-point records.
+ *
+ *   The single largest US address source available — federal aggregation of state + local 911-grade
+ *   address points (every addressable location). Compared to TIGER ADDRFEAT (~20M segment-level, no
+ *   city/locality) and NPPES (~7M provider-centric venues), NAD covers the entire residential +
+ *   commercial address space with full structured components.
+ *
+ *   The adapter consumes NDJSON slices produced by `fetch-nad.ts`'s featureserver mode (operator
+ *   pre-downloads via `mailwoman corpus fetch nad`). Each slice is per-OID-range
+ *   `oids_<start>-<end>.ndjson` with a sibling `.manifest.json`. Adapter iterates every `.ndjson`
+ *   in the input directory, skipping the `quarantined-bash-bug/` subdir (legacy of the bash-
+ *   fetcher's silent-page-failure bug).
+ *
+ *   Field mapping (NAD v9 → CanonicalRow components):
+ *
+ *   - House_number: `AddNo_Full` (pre-composed); falls back to AddNum_Pre + Add_Number + AddNum_Suf
+ *   - Street: `StNam_Full` (pre-composed); falls back to St_PreDir + St_PreTyp + St_Name + St_PosTyp
+ *
+ *       - St_PosDir + St_PosMod composition
+ *   - Locality: `Post_City` > `Inc_Muni` > `Census_Plc` > `Uninc_Comm` (first non-empty)
+ *   - Region: `State` (2-char USPS code, including territories: PR, GU, VI, AS, MP)
+ *   - Postcode: `Zip_Code` + `Plus_4` (joined as `XXXXX-NNNN` when both present)
+ *   - Venue: `LandmkName` (typically a park, school, hospital, named facility — when present)
+ *
+ *   License: stamped `"Public Domain"` per 17 U.S.C. § 105 (US federal works).
+ */
+import type { CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export declare const USGOV_NAD_ADAPTER_ID = "usgov-nad";
+/**
+ * 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 declare const USGOV_NAD_DEFAULT_LICENSE = "Public Domain";
+export declare function createUsgovNADAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const usgovNADAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/usgov-nad/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/usgov-nad/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAUH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAC/C;;;GAGG;AACH,eAAO,MAAM,yBAAyB,kBAAkB,CAAA;AA8KxD,wBAAgB,qBAAqB,IAAI,aAAa,CAuGrD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,eAA0B,CAAA"}

package/out/adapters/usgov-nad/adapter.js

@@ -0,0 +1,249 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `usgov-nad`: US DOT National Address Database — ~97M structured address-point records.
+ *
+ *   The single largest US address source available — federal aggregation of state + local 911-grade
+ *   address points (every addressable location). Compared to TIGER ADDRFEAT (~20M segment-level, no
+ *   city/locality) and NPPES (~7M provider-centric venues), NAD covers the entire residential +
+ *   commercial address space with full structured components.
+ *
+ *   The adapter consumes NDJSON slices produced by `fetch-nad.ts`'s featureserver mode (operator
+ *   pre-downloads via `mailwoman corpus fetch nad`). Each slice is per-OID-range
+ *   `oids_<start>-<end>.ndjson` with a sibling `.manifest.json`. Adapter iterates every `.ndjson`
+ *   in the input directory, skipping the `quarantined-bash-bug/` subdir (legacy of the bash-
+ *   fetcher's silent-page-failure bug).
+ *
+ *   Field mapping (NAD v9 → CanonicalRow components):
+ *
+ *   - House_number: `AddNo_Full` (pre-composed); falls back to AddNum_Pre + Add_Number + AddNum_Suf
+ *   - Street: `StNam_Full` (pre-composed); falls back to St_PreDir + St_PreTyp + St_Name + St_PosTyp
+ *
+ *       - St_PosDir + St_PosMod composition
+ *   - Locality: `Post_City` > `Inc_Muni` > `Census_Plc` > `Uninc_Comm` (first non-empty)
+ *   - Region: `State` (2-char USPS code, including territories: PR, GU, VI, AS, MP)
+ *   - Postcode: `Zip_Code` + `Plus_4` (joined as `XXXXX-NNNN` when both present)
+ *   - Venue: `LandmkName` (typically a park, school, hospital, named facility — when present)
+ *
+ *   License: stamped `"Public Domain"` per 17 U.S.C. § 105 (US federal works).
+ */
+import { readDirectory } from "@mailwoman/core/fs/readers";
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { isPresent } from "@mailwoman/core/objects";
+import { reconcileComponents } from "@mailwoman/formatter";
+import { join } from "path-ts";
+import { TextSpliterator } from "spliterator";
+import { composeRaw } from "#adapters/utils";
+/**
+ * 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_NAD_ADAPTER_ID = "usgov-nad";
+/**
+ * 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_NAD_DEFAULT_LICENSE = "Public Domain";
+const US_STATES_SET = new Set([
+    "AL",
+    "AK",
+    "AZ",
+    "AR",
+    "CA",
+    "CO",
+    "CT",
+    "DE",
+    "DC",
+    "FL",
+    "GA",
+    "HI",
+    "ID",
+    "IL",
+    "IN",
+    "IA",
+    "KS",
+    "KY",
+    "LA",
+    "ME",
+    "MD",
+    "MA",
+    "MI",
+    "MN",
+    "MS",
+    "MO",
+    "MT",
+    "NE",
+    "NV",
+    "NH",
+    "NJ",
+    "NM",
+    "NY",
+    "NC",
+    "ND",
+    "OH",
+    "OK",
+    "OR",
+    "PA",
+    "RI",
+    "SC",
+    "SD",
+    "TN",
+    "TX",
+    "UT",
+    "VT",
+    "VA",
+    "WA",
+    "WV",
+    "WI",
+    "WY",
+    // Territories that ship in NAD
+    "PR",
+    "GU",
+    "VI",
+    "AS",
+    "MP",
+]);
+function nonEmpty(...values) {
+    for (const v of values) {
+        const trimmed = (v ?? "").toString().trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+function composeHouseNumber(r) {
+    const full = (r.AddNo_Full ?? "").toString().trim();
+    if (full)
+        return full;
+    const num = r.Add_Number == null ? "" : String(r.Add_Number).trim();
+    if (!num)
+        return undefined;
+    const pre = (r.AddNum_Pre ?? "").toString().trim();
+    const suf = (r.AddNum_Suf ?? "").toString().trim();
+    return [pre, num, suf].filter(isPresent).join(" ").trim() || undefined;
+}
+function decomposeNADStreet(r) {
+    const name = (r.St_Name ?? "").toString().trim();
+    if (name) {
+        const preDir = (r.St_PreDir ?? "").toString().trim();
+        const preTyp = (r.St_PreTyp ?? "").toString().trim();
+        const preSep = (r.St_PreSep ?? "").toString().trim();
+        const posTyp = (r.St_PosTyp ?? "").toString().trim();
+        const posDir = (r.St_PosDir ?? "").toString().trim();
+        const prefix = [preDir, preTyp, preSep].filter(isPresent).join(" ") || undefined;
+        const suffix = [posTyp, posDir].filter(isPresent).join(" ") || undefined;
+        const full = [prefix, name, suffix].filter(isPresent).join(" ");
+        return { prefix, street: name, suffix, full };
+    }
+    const full = (r.StNam_Full ?? "").toString().trim();
+    if (full)
+        return { full, street: full };
+    return undefined;
+}
+function composeLocality(r) {
+    return nonEmpty(r.Post_City, r.Inc_Muni, r.Census_Plc, r.Uninc_Comm);
+}
+function composePostcode(r) {
+    const zip = (r.Zip_Code ?? "").toString().trim();
+    if (!zip)
+        return undefined;
+    const plus4 = (r.Plus_4 ?? "").toString().trim();
+    return plus4 ? `${zip}-${plus4}` : zip;
+}
+export function createUsgovNADAdapter() {
+    return {
+        id: USGOV_NAD_ADAPTER_ID,
+        defaultLicense: USGOV_NAD_DEFAULT_LICENSE,
+        description: "US DOT National Address Database — ~97M structured US address points (911-grade). Single largest US source.",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "US") {
+                throw new Error(`usgov-nad adapter: only US supported, got country=${opts.country}`);
+            }
+            // inputPath is a directory of NDJSON slices (per fetch-nad.ts featureserver output).
+            // Single-file inputs (e.g. a bulk-extracted CSV) are not currently supported — the
+            // featureserver slice pattern is the primary distribution.
+            const entries = await readDirectory(opts.inputPath);
+            const slices = entries.filter((n) => n.endsWith(".ndjson")).toSorted();
+            let emitted = 0;
+            outer: for (const slice of slices) {
+                if (opts.signal?.aborted)
+                    break;
+                // TextSpliterator streams string lines; the per-line tryParsingJSON below keeps the reader
+                // tolerant of malformed rows (skip silently), so TextSpliterator + a non-throwing parse —
+                // not JSONSpliterator, which would throw. The path string lets the lib own + dispose each
+                // slice's file handle, including on the `break outer` early exit.
+                const lines = TextSpliterator.fromAsync(join(opts.inputPath, slice));
+                for await (const line of lines) {
+                    if (opts.signal?.aborted)
+                        break outer;
+                    if (opts.limit !== undefined && emitted >= opts.limit)
+                        break outer;
+                    if (!line)
+                        continue;
+                    const record = tryParsingJSON(line);
+                    if (record === null)
+                        continue; // malformed line — skip silently
+                    const state = (record.State ?? "").toString().trim().toUpperCase();
+                    if (!US_STATES_SET.has(state))
+                        continue;
+                    const locality = composeLocality(record);
+                    if (!locality)
+                        continue;
+                    const postcode = composePostcode(record);
+                    if (!postcode)
+                        continue;
+                    const decomposed = decomposeNADStreet(record);
+                    const houseNumber = composeHouseNumber(record);
+                    const venue = nonEmpty(record.LandmkName);
+                    const unit = nonEmpty(record.Unit, record.Building, record.Floor, record.Room);
+                    const components = {
+                        ...(venue ? { venue } : {}),
+                        ...(houseNumber ? { house_number: houseNumber } : {}),
+                        ...(decomposed?.prefix ? { street_prefix: decomposed.prefix } : {}),
+                        ...(decomposed?.street ? { street: decomposed.street } : {}),
+                        ...(decomposed?.suffix ? { street_suffix: decomposed.suffix } : {}),
+                        ...(unit ? { unit } : {}),
+                        locality,
+                        region: state,
+                        postcode,
+                    };
+                    const raw = composeRaw({
+                        venue,
+                        houseNumber,
+                        street: decomposed?.full,
+                        unit,
+                        locality,
+                        region: state,
+                        postcode,
+                    });
+                    if (!raw)
+                        continue;
+                    const aligned = reconcileComponents(components, raw);
+                    if (Object.keys(aligned).length <= 2)
+                        continue;
+                    const sourceID = record.UUID
+                        ? `${USGOV_NAD_ADAPTER_ID}-${record.UUID}`
+                        : `${USGOV_NAD_ADAPTER_ID}-${record.OBJECTID ?? `${slice}:${emitted}`}`;
+                    yield {
+                        raw,
+                        components: aligned,
+                        country: "US",
+                        locale: "en-US",
+                        source: USGOV_NAD_ADAPTER_ID,
+                        source_id: sourceID,
+                        corpus_version: "",
+                        license: USGOV_NAD_DEFAULT_LICENSE,
+                    };
+                    emitted++;
+                }
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const usgovNADAdapter = createUsgovNADAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/usgov-nad/adapter.js.map

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

package/out/adapters/usgov-nppes/adapter.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @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 type { CorpusAdapter } from "#types";
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export declare 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 declare const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain";
+export declare function createUsgovNPPESAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const usgovNPPESAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/usgov-nppes/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/usgov-nppes/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AAEzE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAA;AACnD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,kBAAkB,CAAA;AAe1D,wBAAgB,uBAAuB,IAAI,aAAa,CA0FvD;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA4B,CAAA"}

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

@@ -0,0 +1,118 @@
+/**
+ * @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 { isPresent } from "@mailwoman/core/objects";
+import { reconcileComponents } from "@mailwoman/formatter";
+import { CSVSpliterator } from "spliterator";
+import { composeRaw, splitStreetLine, stableSourceID } from "#adapters/utils";
+import { lookupStateAbbreviation } from "#codex/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, {
+                mode: "object",
+                normalizeKeys: false,
+                enableQuoteHandling: true,
+            });
+            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 || [firstName, lastName].filter(isPresent).join(" ") || undefined;
+                const components = {
+                    ...(venue ? { venue } : {}),
+                    ...(split.house_number ? { house_number: split.house_number } : {}),
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode,
+                };
+                const raw = composeRaw({
+                    venue,
+                    houseNumber: split.house_number,
+                    street: split.street,
+                    locality: city,
+                    region: state.abbreviation,
+                    postcode,
+                });
+                if (!raw)
+                    continue;
+                const aligned = reconcileComponents(components, raw);
+                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/adapters/usgov-nppes/adapter.js.map

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