@mailwoman/corpus 9.4.0 → 10.1.0

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

@@ -0,0 +1,185 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reads the US DOT National Address Database from a directory of NDJSON files written by the NAD fetcher.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address/format";
+import { US_STATE_ABBREVIATIONS } from "@mailwoman/codex/us/state";
+import { tryParsingJSON } from "@mailwoman/core/json";
+import { isPresent } from "@mailwoman/core/objects";
+import { resolvePathBuilder } from "path-ts";
+import { TextSpliterator } from "spliterator";
+import { Globerator } from "spliterator/node/fs";
+import { SourceRegister } from "#registers";
+import { AddressRole, SurfaceOrigin } from "#types";
+/**
+ * The adapter id stamped on every emitted row.
+ */
+export const USGOV_NAD_ADAPTER_ID = "usgov-nad";
+/**
+ * The license label on every emitted row, because US federal works are public domain under 17 U.S.C. § 105.
+ */
+export const USGOV_NAD_DEFAULT_LICENSE = "Public Domain";
+/**
+ * The USPS abbreviations a NAD row's `State` must match, taken from codex rather than restated.
+ *
+ * `US_STATE_ABBREVIATIONS` holds the 50 states, the District of Columbia and the five primary territories.
+ * That is the set NAD publishes under, so this adapter keeps no list of its own.
+ *
+ * The two had identical membership when they were reconciled, at 56 entries each.
+ */
+const US_STATES_SET = new Set(US_STATE_ABBREVIATIONS);
+function nonEmpty(...values) {
+    for (const v of values) {
+        const trimmed = (v ?? "").toString().trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * The house number a NAD record states, read from its own four columns.
+ *
+ * NAD publishes `AddNo_Full` already assembled and the parts beside it, so this prefers the
+ * assembled column and falls back to joining `AddNum_Pre`, `Add_Number` and `AddNum_Suf`.
+ * The shared `composeHouseNumber` in `#adapters/street-line` joins exactly two columns with
+ * one separator, so it fits a publisher that splits the number in two rather than in four.
+ */
+function nadHouseNumber(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;
+}
+// Structured street fields take precedence.
+// If they are empty, `StNam_Full` supplies the whole street.
+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;
+}
+// The postal city comes first because it is the name that people write on mail.
+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;
+}
+/**
+ * Creates the NAD adapter.
+ *
+ * The adapter skips records without a US state code, locality, or ZIP code.
+ * It also skips rows whose rendering keeps two or fewer components.
+ */
+export function createUsgovNADAdapter() {
+    return {
+        id: USGOV_NAD_ADAPTER_ID,
+        defaultLicense: USGOV_NAD_DEFAULT_LICENSE,
+        addressRole: AddressRole.Premise,
+        register: SourceRegister.NationalAddressDatabase,
+        surface: SurfaceOrigin.Rendered,
+        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}`);
+            }
+            // The input must be a directory of NDJSON files.
+            const files = await Globerator.files("ndjson", {
+                cwd: opts.inputPath,
+                absolute: false,
+                recursive: false,
+            }).toSorted();
+            let emitted = 0;
+            outer: for (const file of files) {
+                if (opts.signal?.aborted)
+                    break;
+                // The spliterator closes the file when the loop exits early.
+                const lines = TextSpliterator.fromAsync(resolvePathBuilder(opts.inputPath, file));
+                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;
+                    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 = nadHouseNumber(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 rendered = formatAddressRow(components, "US", { singleLine: true });
+                    if (!rendered)
+                        continue;
+                    const { raw, components: aligned } = rendered;
+                    if (Object.keys(aligned).length <= 2)
+                        continue;
+                    const sourceID = record.UUID
+                        ? `${USGOV_NAD_ADAPTER_ID}-${record.UUID}`
+                        : `${USGOV_NAD_ADAPTER_ID}-${record.OBJECTID ?? `${file}:${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 NAD adapter instance that the corpus builder registers.
+ */
+export const usgovNADAdapter = createUsgovNADAdapter();
+//# sourceMappingURL=adapter.js.map

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

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

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

@@ -0,0 +1,29 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reads provider practice-location addresses from the monthly CMS NPPES full-replacement CSV.
+ */
+import { type CorpusAdapter } from "#types";
+/**
+ * The adapter id stamped on every emitted row.
+ */
+export declare const USGOV_NPPES_ADAPTER_ID = "usgov-nppes";
+/**
+ * The license label on every emitted row, because CMS distributes NPPES as a federal public-domain work.
+ */
+export declare const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain";
+/**
+ * Creates the NPPES adapter.
+ *
+ * Each row's `venue` is the organization's legal name or, for an individual provider,
+ * the formatted person name.
+ * The adapter skips records without a city, a postcode, a known state or a parseable street line.
+ */
+export declare function createUsgovNPPESAdapter(): CorpusAdapter;
+/**
+ * The NPPES adapter instance that the corpus builder registers.
+ */
+export declare const usgovNPPESAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../lib/us/adapters/usgov/nppes/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,EAAuD,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAG/G;;GAEG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAA;AACnD;;GAEG;AACH,eAAO,MAAM,2BAA2B,kBAAkB,CAAA;AAgD1D;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,aAAa,CA2FvD;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAA4B,CAAA"}

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

@@ -0,0 +1,140 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Reads provider practice-location addresses from the monthly CMS NPPES full-replacement CSV.
+ */
+import { formatAddressRow } from "@mailwoman/codex/address/format";
+import { stringifyJSON } from "@mailwoman/core/json";
+import { isPresent } from "@mailwoman/core/objects";
+import { formatPersonName } from "@mailwoman/record/name";
+import { CSVSpliterator } from "spliterator";
+import { stableSourceID } from "#adapters/source-id";
+import { splitStreetLine } from "#adapters/street-line";
+import { SourceRegister } from "#registers";
+import { AddressRole, SurfaceOrigin } from "#types";
+import { lookupStateAbbreviation } from "#us/fips-state";
+/**
+ * The adapter id stamped on every emitted row.
+ */
+export const USGOV_NPPES_ADAPTER_ID = "usgov-nppes";
+/**
+ * The license label on every emitted row, because CMS distributes NPPES as a federal public-domain work.
+ */
+export const USGOV_NPPES_DEFAULT_LICENSE = "Public Domain";
+/**
+ * The columns that every emitted row needs, in the publisher's spelling.
+ *
+ * A missing column reads as `undefined` on every record.
+ * The row filter would then drop every row without an error.
+ */
+const REQUIRED_COLUMNS = [
+    "Provider First Line Business Practice Location Address",
+    "Provider Business Practice Location Address City Name",
+    "Provider Business Practice Location Address State Name",
+    "Provider Business Practice Location Address Postal Code",
+];
+/**
+ * Throws when the first parsed record lacks a required practice-location column.
+ *
+ * The check reads the parsed record's keys, so it sees the column names exactly
+ * as the CSV reader produced them.
+ */
+function assertPracticeLocationColumns(record, inputPath) {
+    const present = new Set(Object.keys(record));
+    const missing = REQUIRED_COLUMNS.filter((column) => !present.has(column));
+    if (!missing.length)
+        return;
+    throw new Error(`usgov-nppes adapter: ${inputPath} carries none of ${missing.map((column) => stringifyJSON(column)).join(", ")}. ` +
+        `Every row would be dropped and the run would report zero rows read from a file it read in full. ` +
+        `Check the publisher's own spelling against this adapter's column names.`);
+}
+/**
+ * Creates the NPPES adapter.
+ *
+ * Each row's `venue` is the organization's legal name or, for an individual provider,
+ * the formatted person name.
+ * The adapter skips records without a city, a postcode, a known state or a parseable street line.
+ */
+export function createUsgovNPPESAdapter() {
+    return {
+        id: USGOV_NPPES_ADAPTER_ID,
+        defaultLicense: USGOV_NPPES_DEFAULT_LICENSE,
+        addressRole: AddressRole.Practice,
+        register: SourceRegister.NPPES,
+        surface: SurfaceOrigin.Rendered,
+        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;
+            let checkedHeader = false;
+            for await (const record of rows) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const npi = record.NPI ?? "";
+                const orgName = record["Provider Organization Name (Legal Business Name)"] ?? "";
+                const lastName = record["Provider Last Name (Legal Name)"] ?? "";
+                const firstName = record["Provider First Name"] ?? "";
+                const address1 = record["Provider First Line Business Practice Location Address"] ?? "";
+                const address2 = record["Provider Second Line Business Practice Location Address"] ?? "";
+                const city = record["Provider Business Practice Location Address City Name"] ?? "";
+                const stateRaw = record["Provider Business Practice Location Address State Name"] ?? "";
+                const postcode = record["Provider Business Practice Location Address Postal Code"] ?? "";
+                // The first record's keys reveal a renamed column before the filters below drop every row.
+                if (!checkedHeader) {
+                    checkedHeader = true;
+                    assertPracticeLocationColumns(record, opts.inputPath);
+                }
+                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 NPPES adapter instance that the corpus builder registers.
+ */
+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":"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"}

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

@@ -0,0 +1,47 @@
+/**
+ * @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 includes 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 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 contains
+ *   the canonical postal address (`"123 Main St"`); `street2` contains 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 { 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_SAMHSA_ADAPTER_ID = "usgov-samhsa-treatment-locator";
+/**
+ * License assigned 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_SAMHSA_DEFAULT_LICENSE = "Public Domain";
+export declare function createUsgovSamhsaTreatmentLocatorAdapter(): CorpusAdapter;
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export declare const usgovSamhsaTreatmentLocatorAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

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;AAQH,OAAO,EAAuD,KAAK,aAAa,EAAiB,MAAM,QAAQ,CAAA;AAG/G;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,mCAAmC,CAAA;AACvE;;;GAGG;AACH,eAAO,MAAM,4BAA4B,kBAAkB,CAAA;AAmE3D,wBAAgB,wCAAwC,IAAI,aAAa,CAyExE;AAED;;GAEG;AACH,eAAO,MAAM,kCAAkC,eAA6C,CAAA"}

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

@@ -0,0 +1,153 @@
+/**
+ * @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 includes 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 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 contains
+ *   the canonical postal address (`"123 Main St"`); `street2` contains 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 { stableSourceID } from "#adapters/source-id";
+import { splitStreetLine } from "#adapters/street-line";
+import { SourceRegister } from "#registers";
+import { AddressRole, SurfaceOrigin } from "#types";
+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 assigned 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,
+        addressRole: AddressRole.Facility,
+        register: SourceRegister.SAMHSATreatmentLocator,
+        surface: SurfaceOrigin.Rendered,
+        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 ?? "";
+                const stateAbbr = record.state ?? "";
+                const postcode = record.zip ?? "";
+                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 ?? "";
+                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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,WAAW,EAA8D,aAAa,EAAE,MAAM,QAAQ,CAAA;AAC/G,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AAExD;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,gCAAgC,CAAA;AACvE;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,eAAe,CAAA;AAwB3D;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,OAAe,EAAE,OAA2B;IACtE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;IACzB,MAAM,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAEjC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAEzB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAElB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAElB,OAAO,GAAG,EAAE,KAAK,EAAE,EAAE,CAAA;AACtB,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,YAAY,CAAC,KAAa,EAAE,KAAyB;IAC7D,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IACvB,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IAE/B,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAEzB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAElB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAA;IAElB,OAAO,GAAG,EAAE,MAAM,EAAE,EAAE,CAAA;AACvB,CAAC;AAED,MAAM,UAAU,wCAAwC;IACvD,OAAO;QACN,EAAE,EAAE,uBAAuB;QAC3B,cAAc,EAAE,4BAA4B;QAC5C,WAAW,EAAE,WAAW,CAAC,QAAQ;QACjC,QAAQ,EAAE,cAAc,CAAC,sBAAsB;QAC/C,OAAO,EAAE,aAAa,CAAC,QAAQ;QAC/B,WAAW,EACV,gJAAgJ;QAEjJ,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,wDAAwD,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;YACxF,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,IAAoC,EAAE,CAAC;gBACjE,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,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;gBAC5D,MAAM,MAAM,GAAG,iBAAiB,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAA;gBACtE,MAAM,KAAK,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;gBACrC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAA;gBAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAA;gBACpC,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAA;gBAEjC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ;oBAAE,SAAQ;gBACpD,MAAM,KAAK,GAAG,uBAAuB,CAAC,SAAS,CAAC,CAAA;gBAEhD,IAAI,CAAC,KAAK;oBAAE,SAAQ;gBAEpB,mEAAmE;gBACnE,MAAM,UAAU,GAA+B;oBAC9C,KAAK;oBACL,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,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAA;gBAE9B,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,uBAAuB,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAA;gBAE/G,MAAM;oBACL,GAAG;oBACH,UAAU,EAAE,OAAO;oBACnB,OAAO,EAAE,IAAI;oBACb,MAAM,EAAE,OAAO;oBACf,MAAM,EAAE,uBAAuB;oBAC/B,SAAS,EAAE,QAAQ;oBACnB,cAAc,EAAE,EAAE;oBAClB,OAAO,EAAE,4BAA4B;iBACrC,CAAA;gBAED,OAAO,EAAE,CAAA;YACV,CAAC;QACF,CAAC;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAG,wCAAwC,EAAE,CAAA"}

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

@@ -0,0 +1,50 @@
+/**
+ * @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;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA0D9D,CAAA;AAEF;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAItF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAE1E,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,GAAG,IAAI,CAInG"}