/**
 * @copyright Sister Software
 * @license AGPL-3.0
 * @author Teffen Ellis, et al.
 *
 *   `usgov-imls-pls`: IMLS Public Libraries Survey outlet CSV consumer.
 *
 *   The Institute of Museum and Library Services publishes an annual Public Libraries Survey with one
 *   row per library outlet (~17K rows). Each row carries the library name, street address, city,
 *   ZIP, county, and geocoordinates.
 *
 *   The adapter consumes the outlet CSV the operator pre-downloads via `fetch-imls-pls.ts`. Column
 *   names match the IMLS PLS outlet file header.
 *
 *   Output: one row per outlet with `venue` (library name), `(house_number, street, locality,
 *   subregion, postcode)`, and lat/lon preserved in `source_id` stability.
 *
 *   License: stamped `"Public Domain"` per IMLS federal government distribution terms.
 */

import { splitStreetLine, stableSourceID } from "@mailwoman/corpus/adapters/utils"
import { lookupStateAbbreviation } from "@mailwoman/corpus/codex/us-fips-state"
import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "@mailwoman/corpus/types"
import { reconcileComponents } from "@mailwoman/formatter"
import { CSVSpliterator } from "spliterator"

/**
 * 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_IMLS_PLS_ADAPTER_ID = "usgov-imls-pls"
/**
 * 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_IMLS_PLS_DEFAULT_LICENSE = "Public Domain"

interface ImlsOutletRow {
	LIBNAME: string
	ADDRESS: string
	CITY: string
	ZIP: string
	STABR: string
	CNTY: string
	FSCSKEY: string
}

export function createUsgovImlsPlsAdapter(): CorpusAdapter {
	return {
		id: USGOV_IMLS_PLS_ADAPTER_ID,
		defaultLicense: USGOV_IMLS_PLS_DEFAULT_LICENSE,
		description: "IMLS Public Libraries Survey — ~17K library outlets with venue+address (public-domain).",

		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
			if (opts.country && opts.country !== "US") {
				throw new Error(`usgov-imls-pls 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<ImlsOutletRow>) {
				if (opts.signal?.aborted) break

				if (opts.limit !== undefined && emitted >= opts.limit) break

				const libName = (record.LIBNAME ?? "").trim()
				const address = (record.ADDRESS ?? "").trim()
				const city = (record.CITY ?? "").trim()
				const zip = (record.ZIP ?? "").trim()
				const stateAbbr = (record.STABR ?? "").trim()
				const county = (record.CNTY ?? "").trim()

				if (!libName || !city || !zip) continue

				const state = lookupStateAbbreviation(stateAbbr)

				if (!state) continue

				const split = splitStreetLine(address)

				if (!split) continue

				const components: CanonicalRow["components"] = {
					venue: libName,
					...(split.house_number ? { house_number: split.house_number } : {}),
					street: split.street,
					locality: city,
					region: state.abbreviation,
					postcode: zip,
					// #552: no subregion — US postal addresses don't surface the county, so emitting
					// subregion creates a phantom component with no raw-span to align to, quarantining
					// ~21% of rows. The county is still available in the source CSV; it just isn't
					// a postal-surface component here.
				}

				const streetPart = [split.house_number, split.street].filter(Boolean).join(" ").trim()

				const raw = [libName, streetPart, [city, [stateAbbr, zip].filter(Boolean).join(" ")].filter(Boolean).join(", ")]
					.filter(Boolean)
					.join(", ")

				const aligned = reconcileComponents(components, raw)

				if (Object.keys(aligned).length <= 2) continue

				const fscsKey = (record.FSCSKEY ?? "").trim()

				const sourceID = fscsKey
					? `${USGOV_IMLS_PLS_ADAPTER_ID}-${fscsKey}`
					: stableSourceID(USGOV_IMLS_PLS_ADAPTER_ID, aligned)

				yield {
					raw,
					components: aligned,
					country: "US",
					locale: "en-US",
					source: USGOV_IMLS_PLS_ADAPTER_ID,
					source_id: sourceID,
					corpus_version: "",
					license: USGOV_IMLS_PLS_DEFAULT_LICENSE,
				}

				emitted++
			}
		},
	}
}

/**
 * The configured adapter instance registered with the corpus builder.
 */
export const usgovImlsPlsAdapter = createUsgovImlsPlsAdapter()