@mailwoman/corpus 9.1.0 → 9.3.0

package/lib/adapters/state-hi-schools/adapter.ts

@@ -0,0 +1,170 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-hi-schools`: Hawaii DOE public + charter school workbook consumer.
+ *
+ *   The Hawaii State Department of Education publishes a directory of all HIDOE schools and public
+ *   charter schools (PCS) as an XLSX workbook (`SchoolList.xlsx`) with two sheets: `HIDOE` (~258
+ *   rows) and `PCS` (~38 rows). Total ~296 rows statewide. Each row carries a school name,
+ *   single-line street address, city, ZIP, a numeric `code`, and HI-specific administrative columns
+ *   (complex, complex_area, district, island, charter).
+ *
+ *   The adapter consumes the original XLSX retained by the fetcher and reads both worksheets directly.
+ *   Legacy flat CSV artifacts remain accepted so existing source caches do not need conversion.
+ *
+ *   Address parsing notes: Hawaii's residential numbering is hyphenated on Oahu (`47-470 Hui Aeko
+ *   Place`), Kauai (`2-4035 Kaumualii Hwy`), and elsewhere. The shared HOUSE_NUMBER_PREFIX regex
+ *   covers this via its optional `(?:-\d+)?` group.
+ *
+ *   The `island` and `district` columns are HIDOE administrative labels (Honolulu, Central, Leeward,
+ *   Windward, Hilo, Hawaii, Maui, Kauai) — they are NOT US counties and intentionally are not
+ *   surfaced as `subregion`.
+ *
+ *   Output: one row per school with `venue` (school name), `(house_number?, street, locality,
+ *   region=HI, postcode)`, and a stable `source_id` derived from the school `code`.
+ *
+ *   License: stamped `"Public Domain"` per Hawaii state government open-data terms.
+ */
+
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
+import { CSVSpliterator, XLSXSpliterator } from "spliterator"
+
+import { type HiSchoolRow, schoolCellText, STATE_HI_SCHOOL_SHEETS } from "#adapters/state-hi-schools/workbook"
+import { splitStreetLine, stableSourceID } from "#adapters/utils"
+import { lookupStateAbbreviation } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, 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 const STATE_HI_SCHOOLS_ADAPTER_ID = "state-hi-schools"
+/**
+ * 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 STATE_HI_SCHOOLS_DEFAULT_LICENSE = "Public Domain"
+
+const HI_STATE_ABBR = "HI"
+
+function normalizeZip(raw: HiSchoolRow["zip"]): string {
+	const trimmed = schoolCellText(raw)
+
+	if (!trimmed) return ""
+
+	// XLSX → CSV conversion may emit numeric ZIPs without leading zeros. HI ZIPs all begin
+	// with 96, so a 4-digit value indicates a leading-zero stripped during numeric coercion
+	// (defensive — has not been observed in the published file as of 2026-05).
+	if (/^\d{4}$/.test(trimmed)) return `0${trimmed}`
+
+	return trimmed
+}
+
+async function* readSchoolRows(inputPath: string): AsyncGenerator<HiSchoolRow> {
+	if (inputPath.toLowerCase().endsWith(".xlsx")) {
+		for (const sheet of STATE_HI_SCHOOL_SHEETS) {
+			yield* XLSXSpliterator.fromAsync<HiSchoolRow>(inputPath, {
+				sheet,
+				mode: "object",
+				normalizeKeys: false,
+			})
+		}
+
+		return
+	}
+
+	yield* CSVSpliterator.fromAsync<HiSchoolRow>(inputPath, {
+		mode: "object",
+		normalizeKeys: false,
+		enableQuoteHandling: true,
+	})
+}
+
+export function createStateHiSchoolsAdapter(): CorpusAdapter {
+	return {
+		id: STATE_HI_SCHOOLS_ADAPTER_ID,
+		defaultLicense: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
+		description: "Hawaii DOE School Directory — ~300 K-12 public + charter schools with venue+address (public-domain).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`state-hi-schools adapter: only US supported, got country=${opts.country}`)
+			}
+
+			const state = lookupStateAbbreviation(HI_STATE_ABBR)
+
+			if (!state) {
+				throw new Error(`state-hi-schools adapter: HI not found in state codex (corpus bug)`)
+			}
+
+			let emitted = 0
+
+			for await (const record of readSchoolRows(opts.inputPath)) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const name = schoolCellText(record.name)
+				const address = schoolCellText(record.address)
+				const city = schoolCellText(record.city)
+				const zip = normalizeZip(record.zip)
+
+				if (!name || !address || !city || !zip) continue
+
+				const split = splitStreetLine(address)
+
+				if (!split) continue
+
+				const components: CanonicalRow["components"] = {
+					venue: name,
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					postcode: zip,
+				}
+
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
+
+				const raw = [
+					name,
+					streetPart,
+					[city, [HI_STATE_ABBR, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
+					.join(", ")
+
+				const aligned = reconcileComponents(components, raw)
+
+				if (Object.keys(aligned).length <= 2) continue
+
+				const code = schoolCellText(record.code)
+
+				const sourceID = code
+					? `${STATE_HI_SCHOOLS_ADAPTER_ID}-${code}`
+					: stableSourceID(STATE_HI_SCHOOLS_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: STATE_HI_SCHOOLS_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: STATE_HI_SCHOOLS_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateHiSchoolsAdapter = createStateHiSchoolsAdapter()

package/lib/adapters/state-hi-schools/workbook.ts

@@ -0,0 +1,35 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+import type { XLSXCellValue } from "spliterator"
+
+/**
+ * The two worksheets that together form the public-school directory.
+ */
+export const STATE_HI_SCHOOL_SHEETS = ["HIDOE", "PCS"] as const
+
+/**
+ * Columns required to construct a corpus row. Fetch validation uses the same contract as the adapter.
+ */
+export const STATE_HI_SCHOOL_REQUIRED_COLUMNS = ["code", "name", "address", "city", "zip"] as const
+
+/**
+ * Workbook row fields consumed by the adapter. XLSX cells are typed; the legacy CSV path supplies strings.
+ */
+export interface HiSchoolRow {
+	code: XLSXCellValue | undefined
+	name: XLSXCellValue | undefined
+	address: XLSXCellValue | undefined
+	city: XLSXCellValue | undefined
+	zip: XLSXCellValue | undefined
+}
+
+/**
+ * Convert a typed workbook cell or legacy CSV field to the trimmed text used by the corpus row.
+ */
+export function schoolCellText(value: XLSXCellValue | undefined): string {
+	return value === null || value === undefined ? "" : String(value).trim()
+}

package/lib/adapters/state-ia-contractors/adapter.ts

@@ -0,0 +1,144 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-ia-contractors`: Iowa Active Construction Contractor Registrations CSV consumer.
+ *
+ *   Iowa Workforce Development publishes a public registry of active construction contractors. Each
+ *   row carries a business name, street address, city/state/zip, and contact info.
+ *
+ *   The adapter consumes the CSV the operator pre-downloads via `fetch-state-sources.ts`.
+ *
+ *   Output: one row per contractor with `venue` (business name) and address quad `(house_number,
+ *   street, locality, region, postcode)`.
+ *
+ *   License: stamped `"Public Domain"` per Iowa state government open-data terms.
+ */
+
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
+import { CSVSpliterator } from "spliterator"
+
+import { splitStreetLine, stableSourceID } from "#adapters/utils"
+import { lookupStateAbbreviation } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, 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 const STATE_IA_CONTRACTORS_ADAPTER_ID = "state-ia-contractors"
+/**
+ * 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 STATE_IA_CONTRACTORS_DEFAULT_LICENSE = "Public Domain"
+
+interface IaContractorRow {
+	"Registration #": string
+	"Business Name": string
+	"Address 1": string
+	"Address 2": string
+	City: string
+	State: string
+	"Zip Code": string
+	"First Name": string
+	"Last Name": string
+}
+
+export function createStateIaContractorsAdapter(): CorpusAdapter {
+	return {
+		id: STATE_IA_CONTRACTORS_ADAPTER_ID,
+		defaultLicense: STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
+		description:
+			"Iowa Active Construction Contractor Registrations — business name + full street address (public-domain).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`state-ia-contractors 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 as AsyncIterable<IaContractorRow>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const businessName = (record["Business Name"] ?? "").trim()
+				const address1 = (record["Address 1"] ?? "").trim()
+				const address2 = (record["Address 2"] ?? "").trim()
+				const city = (record.City ?? "").trim()
+				const stateAbbr = (record.State ?? "").trim()
+				const zip = (record["Zip Code"] ?? "").trim()
+
+				if (!city || !zip) continue
+
+				const state = lookupStateAbbreviation(stateAbbr)
+
+				if (!state) continue
+
+				const fullAddress = [address1, address2].filter(isPresent).join(" ")
+				const split = splitStreetLine(fullAddress)
+
+				if (!split) continue
+
+				const venue = businessName || undefined
+
+				const components: CanonicalRow["components"] = {
+					...(venue ? { venue } : {}),
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					postcode: zip,
+				}
+
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
+
+				const raw = [
+					venue,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
+					.join(", ")
+
+				const aligned = reconcileComponents(components, raw)
+
+				if (Object.keys(aligned).length <= 2) continue
+
+				const regNum = (record["Registration #"] ?? "").trim()
+
+				const sourceID = regNum
+					? `${STATE_IA_CONTRACTORS_ADAPTER_ID}-${regNum}`
+					: stableSourceID(STATE_IA_CONTRACTORS_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: STATE_IA_CONTRACTORS_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateIaContractorsAdapter = createStateIaContractorsAdapter()

package/lib/adapters/state-ny-notaries/adapter.ts

@@ -0,0 +1,141 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-ny-notaries`: New York Commissioned Notaries CSV consumer.
+ *
+ *   The New York Department of State publishes a registry of commissioned notaries public. Each row
+ *   optionally carries a business name and business address (~1-5% fill rate).
+ *
+ *   The adapter consumes the CSV the operator pre-downloads via `fetch-state-sources.ts`. Column
+ *   names match the data.ny.gov export header (note: some columns have leading spaces).
+ *
+ *   License: stamped `"Public Domain"` per New York state government open-data terms.
+ */
+
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
+import { CSVSpliterator } from "spliterator"
+
+import { splitStreetLine, stableSourceID } from "#adapters/utils"
+import { lookupStateAbbreviation } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, 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 const STATE_NY_NOTARIES_ADAPTER_ID = "state-ny-notaries"
+/**
+ * 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 STATE_NY_NOTARIES_DEFAULT_LICENSE = "Public Domain"
+
+export function createStateNyNotariesAdapter(): CorpusAdapter {
+	return {
+		id: STATE_NY_NOTARIES_ADAPTER_ID,
+		defaultLicense: STATE_NY_NOTARIES_DEFAULT_LICENSE,
+		description: "New York Commissioned Notaries — name + optional business address (public-domain).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`state-ny-notaries 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 rawRecord of rows as AsyncIterable<Record<string, string>>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				// NY CSV has columns with leading spaces, so we normalize by trimming keys.
+				const record: Record<string, string> = {}
+
+				for (const key of Object.keys(rawRecord)) {
+					record[key.trim()] = rawRecord[key] ?? ""
+				}
+
+				const holderName = (record["Commission Holder Name"] ?? "").trim()
+				const businessName = (record["Business Name (if available)"] ?? "").trim()
+				const address1 = (record["Business Address 1 (if available)"] ?? "").trim()
+				const address2 = (record["Business Address 2 (if available)"] ?? "").trim()
+				const city = (record["Business City (if available)"] ?? "").trim()
+				const stateAbbr = (record["Business State (if available)"] ?? "").trim()
+				const zip = (record["Business Zip (if available)"] ?? "").trim()
+				const county = (record["Commissioned County"] ?? "").trim()
+
+				if (!city || !stateAbbr || !zip) continue
+
+				if (!address1 && !address2) continue
+
+				const state = lookupStateAbbreviation(stateAbbr)
+
+				if (!state) continue
+
+				const fullAddress = [address1, address2].filter(isPresent).join(" ")
+				const split = splitStreetLine(fullAddress)
+
+				if (!split) continue
+
+				const venue = businessName || holderName || undefined
+
+				const components: CanonicalRow["components"] = {
+					...(venue ? { venue } : {}),
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					postcode: zip,
+					...(county ? { subregion: county } : {}),
+				}
+
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
+
+				const raw = [
+					venue,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
+					.join(", ")
+
+				const aligned = reconcileComponents(components, raw)
+
+				if (Object.keys(aligned).length <= 2) continue
+
+				const commNum = (record["Commission Number (UID)"] ?? "").trim()
+
+				const sourceID = commNum
+					? `${STATE_NY_NOTARIES_ADAPTER_ID}-${commNum}`
+					: stableSourceID(STATE_NY_NOTARIES_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: STATE_NY_NOTARIES_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: STATE_NY_NOTARIES_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateNyNotariesAdapter = createStateNyNotariesAdapter()

package/lib/adapters/state-tx-notaries/adapter.ts

@@ -0,0 +1,157 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `state-tx-notaries`: Texas Notary Public Commissions CSV consumer.
+ *
+ *   The Texas Secretary of State publishes a registry of commissioned notaries public. Each row
+ *   optionally carries a mailing address in free-form text (often multi-line with embedded
+ *   city/state/zip). Address fill rate is ~5-10%.
+ *
+ *   The adapter parses the embedded `Address` field for city/state/zip using a trailing `"CITY, ST
+ *   ZIP"` pattern.
+ *
+ *   License: stamped `"Public Domain"` per Texas state government open-data terms.
+ */
+
+import { isPresent } from "@mailwoman/core/objects"
+import { reconcileComponents } from "@mailwoman/formatter"
+import { CSVSpliterator } from "spliterator"
+
+import { splitStreetLine, stableSourceID } from "#adapters/utils"
+import { lookupStateAbbreviation } from "#codex/us-fips-state"
+import type { AdapterOptions, CanonicalRow, 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 const STATE_TX_NOTARIES_ADAPTER_ID = "state-tx-notaries"
+/**
+ * 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 STATE_TX_NOTARIES_DEFAULT_LICENSE = "Public Domain"
+
+/**
+ * Match trailing "CITY, ST ZIP" or "CITY, ST" at the end of an address line.
+ */
+const CITY_STATE_ZIP_SUFFIX = /[,]?\s*([^,]+),\s*([A-Z]{2})\s*(\d{5}(?:-\d{4})?)?\s*$/i
+
+interface TxNotaryRow {
+	"Notary ID": string
+	"First Name": string
+	"Last Name": string
+	Address: string
+}
+
+export function createStateTxNotariesAdapter(): CorpusAdapter {
+	return {
+		id: STATE_TX_NOTARIES_ADAPTER_ID,
+		defaultLicense: STATE_TX_NOTARIES_DEFAULT_LICENSE,
+		description:
+			"Texas Notary Public Commissions — name + mailing address with embedded city/state/zip (public-domain).",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (opts.country && opts.country !== "US") {
+				throw new Error(`state-tx-notaries 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 as AsyncIterable<TxNotaryRow>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const rawAddress = (record.Address ?? "").trim()
+
+				if (!rawAddress) continue
+
+				const firstName = (record["First Name"] ?? "").trim()
+				const lastName = (record["Last Name"] ?? "").trim()
+				const notaryID = (record["Notary ID"] ?? "").trim()
+
+				// Parse embedded city/state/zip from the trailing portion of the address.
+				// Addresses look like: "1215 MCMILLAN DR\nCEDAR HILL, TX 75104"
+				const addrSingleLine = rawAddress.replaceAll("\n", ", ")
+				const cszMatch = CITY_STATE_ZIP_SUFFIX.exec(addrSingleLine)
+
+				if (!cszMatch) continue
+
+				const city = (cszMatch[1] ?? "").trim()
+				const stateAbbr = (cszMatch[2] ?? "").trim()
+				const zip = (cszMatch[3] ?? "").trim()
+
+				if (!city || !stateAbbr) continue
+
+				const state = lookupStateAbbreviation(stateAbbr)
+
+				if (!state) continue
+
+				// Extract the street portion (everything before the city/state/zip)
+				const streetPortion = addrSingleLine.slice(0, cszMatch.index).replace(/,\s*$/, "").trim()
+
+				if (!streetPortion) continue
+
+				const split = splitStreetLine(streetPortion)
+
+				if (!split) continue
+
+				const venue = [firstName, lastName].filter(isPresent).join(" ") || undefined
+
+				const components: CanonicalRow["components"] = {
+					...(venue ? { venue } : {}),
+					...(split.house_number ? { house_number: split.house_number } : {}),
+					street: split.street,
+					locality: city,
+					region: state.abbreviation,
+					...(zip ? { postcode: zip } : {}),
+				}
+
+				const streetPart = [split.house_number, split.street].filter(isPresent).join(" ").trim()
+
+				const raw = [
+					venue,
+					streetPart,
+					[city, [stateAbbr, zip].filter(isPresent).join(" ")].filter(isPresent).join(", "),
+				]
+					.filter(isPresent)
+					.join(", ")
+
+				const aligned = reconcileComponents(components, raw)
+
+				if (Object.keys(aligned).length <= 2) continue
+
+				const sourceID = notaryID
+					? `${STATE_TX_NOTARIES_ADAPTER_ID}-${notaryID}`
+					: stableSourceID(STATE_TX_NOTARIES_ADAPTER_ID, aligned)
+
+				yield {
+					raw,
+					components: aligned,
+					country: "US",
+					locale: "en-US",
+					source: STATE_TX_NOTARIES_ADAPTER_ID,
+					source_id: sourceID,
+					corpus_version: "",
+					license: STATE_TX_NOTARIES_DEFAULT_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const stateTxNotariesAdapter = createStateTxNotariesAdapter()