@mailwoman/corpus 9.3.0 → 10.0.0

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

@@ -1,170 +0,0 @@
-/**
- * @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-ia-contractors/adapter.ts

@@ -1,144 +0,0 @@
-/**
- * @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

@@ -1,141 +0,0 @@
-/**
- * @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

@@ -1,157 +0,0 @@
-/**
- * @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()