@mailwoman/codex 7.2.0 → 7.3.0

package/us/unit-designator.ts

@@ -0,0 +1,223 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C2 — Secondary Unit Designators.
+ *
+ *   The sibling of {@link ./street-suffix.ts}: where that table standardizes the trailing street
+ *   _type_ (AVENUE → AVE), this one standardizes the _secondary unit_ designator that introduces an
+ *   apartment / suite / floor / room (APARTMENT → APT, SUITE → STE). For each canonical designator
+ *   the value lists recognized variants in USPS order; the first is the approved USPS abbreviation
+ *   (what the post office prints).
+ *
+ *   Used by `@mailwoman/corpus`'s synthesis layer (the `unit-{expand,abbreviate}` augmentations) to
+ *   vary the designator in a `unit` component while preserving the identifier — the data-generation
+ *   counterpart to the runtime `UnitDesignatorClassifier` (which matches the broader libpostal
+ *   `unit_types` lexicon). Designators are LEADING ("Apt 4B"), unlike street suffixes which trail.
+ *
+ *   `US_UNIT_DESIGNATOR_REQUIRES_RANGE` (added for #1100, the secondary-address epic; retrieved from
+ *   Appendix C2 2026-07-13) is Pub-28's own "Requires a Secondary Number" column: APT, BLDG, DEPT,
+ *   FL, HNGR, KEY, LOT, PIER, RM, SLIP, SPC, STOP, STE, TRLR, and UNIT must be followed by an
+ *   identifier ("Apt 4B", never bare "Apt"); BSMT, FRNT, LBBY, LOWR, OFC, PH, REAR, SIDE, and UPPR
+ *   may stand alone. This formalizes, as provenance-tracked reference data, the split that
+ *   `corpus/src/shard-recipes/unit.ts` previously hand-rolled (and only partially covered) as
+ *   in-file `ID_DESIGNATORS`/`STANDALONE_DESIGNATORS` arrays for synthesis weighting. A SEPARATE,
+ *   not-yet-built deliverable of #1100 is the per-locale *level-semantics* table (étage/RDC, EG/OG/UG,
+ *   planta/piso/bajo, piano/terra, 階/F/B1, …) — this module stays US/Pub-28 only.
+ *
+ *   Data is verbatim USPS Pub-28 C2.
+ * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Secondary Unit Designators}
+ */
+
+/**
+ * Canonical USPS secondary unit designator → recognized variants. The first variant is the approved USPS abbreviation.
+ * Keys + values uppercase per the publication. The designators marked by USPS as "requires a secondary number" (APT,
+ * BLDG, FL, …) and the standalone ones (BSMT, LBBY, PH, …) are both included — synthesis treats them uniformly.
+ */
+export const US_UNIT_DESIGNATOR_VARIANTS = {
+	APARTMENT: ["APT", "APRT", "APMT"],
+	BASEMENT: ["BSMT"],
+	BUILDING: ["BLDG", "BLD"],
+	DEPARTMENT: ["DEPT"],
+	FLOOR: ["FL", "FLR"],
+	FRONT: ["FRNT"],
+	HANGAR: ["HNGR"],
+	KEY: ["KEY"],
+	LOBBY: ["LBBY"],
+	LOT: ["LOT"],
+	LOWER: ["LOWR"],
+	OFFICE: ["OFC"],
+	PENTHOUSE: ["PH"],
+	PIER: ["PIER"],
+	REAR: ["REAR"],
+	ROOM: ["RM"],
+	SIDE: ["SIDE"],
+	SLIP: ["SLIP"],
+	SPACE: ["SPC"],
+	STOP: ["STOP"],
+	SUITE: ["STE", "SUIT"],
+	TRAILER: ["TRLR"],
+	UNIT: ["UNIT"],
+	UPPER: ["UPPR"],
+} as const satisfies Record<string, readonly string[]>
+
+/** Canonical USPS secondary unit designator (full word, uppercase per the publication). */
+export type USUnitDesignator = keyof typeof US_UNIT_DESIGNATOR_VARIANTS
+
+/**
+ * Inverse lookup: every variant abbreviation OR full canonical word → its canonical key, built once at module load,
+ * lowercase-keyed for case-insensitive matching (`apt` → `"APARTMENT"`, `ste` → `"SUITE"`, `suite` → `"SUITE"`).
+ */
+export const US_UNIT_DESIGNATOR_LOOKUP: ReadonlyMap<string, USUnitDesignator> = (() => {
+	const out = new Map<string, USUnitDesignator>()
+
+	for (const canonical of Object.keys(US_UNIT_DESIGNATOR_VARIANTS) as USUnitDesignator[]) {
+		out.set(canonical.toLowerCase(), canonical)
+
+		for (const variant of US_UNIT_DESIGNATOR_VARIANTS[canonical]) {
+			// First canonical that claims a variant wins (matches the publication's ordering).
+			if (!out.has(variant.toLowerCase())) {
+				out.set(variant.toLowerCase(), canonical)
+			}
+		}
+	}
+
+	return out
+})()
+
+/** Approved USPS abbreviation per canonical (`APARTMENT → "APT"`, `SUITE → "STE"`). */
+export const US_UNIT_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<USUnitDesignator, string>> = Object.fromEntries(
+	(Object.keys(US_UNIT_DESIGNATOR_VARIANTS) as USUnitDesignator[]).map((k) => [k, US_UNIT_DESIGNATOR_VARIANTS[k][0]])
+) as Readonly<Record<USUnitDesignator, string>>
+
+/**
+ * Canonical designators Appendix C2 marks as "Requires a Secondary Number" — the designator must be followed by an
+ * identifier ("Apt 4B", "Rm 12"), never appearing bare. The remaining designators (BASEMENT, FRONT, LOBBY, LOWER,
+ * OFFICE, PENTHOUSE, REAR, SIDE, UPPER) may stand alone with no trailing identifier. Verbatim from USPS Pub-28 C2; see
+ * the module header for provenance (#1100).
+ */
+export const US_UNIT_DESIGNATOR_REQUIRES_RANGE: Readonly<Record<USUnitDesignator, boolean>> = {
+	APARTMENT: true,
+	BASEMENT: false,
+	BUILDING: true,
+	DEPARTMENT: true,
+	FLOOR: true,
+	FRONT: false,
+	HANGAR: true,
+	KEY: true,
+	LOBBY: false,
+	LOT: true,
+	LOWER: false,
+	OFFICE: false,
+	PENTHOUSE: false,
+	PIER: true,
+	REAR: false,
+	ROOM: true,
+	SIDE: false,
+	SLIP: true,
+	SPACE: true,
+	STOP: true,
+	SUITE: true,
+	TRAILER: true,
+	UNIT: true,
+	UPPER: false,
+} as const satisfies Record<USUnitDesignator, boolean>
+
+/**
+ * If the FIRST whitespace-separated word of `unit` is a known USPS designator variant, return the canonical key and the
+ * matched word. Returns null if the leading word isn't a known designator (e.g. a bare `"4B"` or `"#210"`).
+ * Leading-word-only — designators introduce the unit, unlike street suffixes which trail.
+ */
+export function matchLeadingDesignator(unit: string): { canonical: USUnitDesignator; matched: string } | null {
+	const trimmed = unit.trim()
+
+	if (!trimmed) return null
+	const first = trimmed.split(/\s+/)[0]!
+	const canonical = US_UNIT_DESIGNATOR_LOOKUP.get(first.toLowerCase())
+
+	if (!canonical) return null
+
+	return { canonical, matched: first }
+}
+
+/** Result of {@link matchLeadingDesignatorWithRange}: the leading designator plus its optional secondary range. */
+export interface UnitDesignatorRangeMatch {
+	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	canonical: USUnitDesignator
+	/** The designator's own matched surface form, i.e. "Apt". */
+	matched: string
+	/**
+	 * The secondary range/identifier token immediately following the designator, i.e. "4B" in "Apt 4B". Undefined when
+	 * the designator appears standalone (e.g. bare "Basement"). This module does not validate the range's own shape —
+	 * numeric, letter, or alphanumeric ranges are all USPS-valid.
+	 */
+	range: string | undefined
+	/**
+	 * Whether USPS Pub-28 Appendix C2 marks this designator as requiring a secondary range (see
+	 * {@link US_UNIT_DESIGNATOR_REQUIRES_RANGE}). Informational only — not enforced by this matcher.
+	 */
+	requiresRange: boolean
+}
+
+/**
+ * Like {@link matchLeadingDesignator}, but also captures the secondary range/identifier token immediately following the
+ * designator, if present ("Apt 4B" → designator "APARTMENT", range "4B"; "Basement" → range `undefined`). Mirrors
+ * `street-suffix`/`street-directional`'s designator+adjacent-token matchers.
+ */
+export function matchLeadingDesignatorWithRange(unit: string): UnitDesignatorRangeMatch | null {
+	const trimmed = unit.trim()
+
+	if (!trimmed) return null
+	const parts = trimmed.split(/\s+/)
+	const first = parts[0]!
+	const canonical = US_UNIT_DESIGNATOR_LOOKUP.get(first.toLowerCase())
+
+	if (!canonical) return null
+
+	return {
+		canonical,
+		matched: first,
+		range: parts[1],
+		requiresRange: US_UNIT_DESIGNATOR_REQUIRES_RANGE[canonical],
+	}
+}
+
+/** Result of a successful USPS secondary-unit designator lookup. */
+export interface UnitDesignatorMatch<D extends USUnitDesignator = USUnitDesignator> {
+	/** The matched canonical designator, i.e. "APARTMENT", "SUITE". */
+	designator: D
+	/** The approved USPS abbreviation, i.e. "APT", "STE". */
+	abbreviation: (typeof US_UNIT_DESIGNATOR_VARIANTS)[D][0]
+}
+
+/**
+ * Look up a USPS secondary unit designator (by canonical word, abbreviation, or any variant) and its approved
+ * abbreviation.
+ */
+export function lookupUnitDesignator<D extends USUnitDesignator>(designator: D): UnitDesignatorMatch<D>
+export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null
+export function lookupUnitDesignator(input: string | null | undefined): UnitDesignatorMatch | null {
+	if (!input || typeof input !== "string") return null
+	const designator = US_UNIT_DESIGNATOR_LOOKUP.get(input.trim().toLowerCase())
+
+	if (!designator) return null
+
+	return { designator, abbreviation: US_UNIT_DESIGNATOR_VARIANTS[designator][0] }
+}
+
+/**
+ * True when a token is any USPS secondary unit designator or abbreviation (case-insensitive) — `"Apt"`, `"STE"`,
+ * `"floor"`.
+ */
+export function isUnitDesignatorToken(input: unknown): boolean {
+	return typeof input === "string" && US_UNIT_DESIGNATOR_LOOKUP.has(input.trim().toLowerCase())
+}
+
+/**
+ * Alias of {@link isUnitDesignatorToken} under Pub-28's own term ("secondary unit designator"). Added for #1100 so
+ * secondary-address call sites can spell the predicate after the publication's vocabulary.
+ */
+export function isSecondaryUnitDesignatorToken(input: unknown): boolean {
+	return isUnitDesignatorToken(input)
+}

package/us/zipcode.ts

@@ -0,0 +1,212 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   US ZIP (Zone Improvement Plan) codes: branded string types, the shape patterns, the first-digit →
+ *   state geographic prior, and a state-plus-ZIP plucker.
+ */
+
+import type { Tagged } from "type-fest"
+
+import { isUSStateAbbreviation, type USStateAbbreviation } from "./state.ts"
+
+/**
+ * USPS-recognized ZIP code digits.
+ *
+ * @internal
+ */
+export type ZipCodeDigit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+
+/**
+ * A ZIP (Zone Improvement Plan) Code is a five-digit code assigned by the USPS to a section of a street, a collection
+ * of streets, an establishment, structure, or group of post office boxes, for the delivery of mail.
+ *
+ * - The first 3 digits of the ZIP code represent a specific central mail processing facility, which can be used to
+ *   identify the locality and region of the address, i.e. the city and state.
+ * - The last 2 digits of the ZIP code represent a specific post office or delivery area.
+ *
+ * ```txt
+ *        90210
+ *       / |⎿__(Post Office)
+ *      /   \
+ *  (State)  \
+ *            \
+ *           (City)
+ * ```
+ *
+ * Note that ZIP codes are not areas, but rather a group of deliverable addresses, which can and do change over time.
+ *
+ * @category Delivery
+ * @category Postal
+ * @title ZIP Code
+ * @pattern ^\d{5}$
+ * @see {@linkcode ZipCodePlusFour} for the extended ZIP code format.
+ */
+export type ZipCode = Tagged<string, "ZipCode">
+
+/**
+ * The extended ZIP code format includes the five-digit ZIP code followed by a hyphen and four additional digits. This
+ * extended format is used to provide more precise location information.
+ *
+ * - The first 3 digits of the ZIP code represent a specific central mail processing facility,
+ * - The last 2 digits of the ZIP code represent a specific post office or delivery area.
+ * - The four additional digits represent a specific delivery route within the ZIP code area.
+ *
+ * ```txt
+ *                  90210-1234
+ *                  \_/\ /\__/
+ *                  /   |    \
+ *  (State, City)_ /    |     \_ (Delivery Route)
+ *                      |
+ *                (Post Office)
+ * ```
+ *
+ * Note that ZIP codes are not areas, but rather a group of deliverable addresses, which can and do change over time.
+ *
+ * @category Delivery
+ * @category Postal
+ * @type string
+ * @title ZIP Code+4
+ * @pattern ^\d{5}-\d{4}$
+ * @see {@linkcode ZipCode} for the standard ZIP code format.
+ */
+export type ZipCodePlusFour = Tagged<string, "ZipCodePlusFour">
+
+/**
+ * Type utility to extract the state abbreviation from a ZIP code.
+ *
+ * @internal
+ */
+export type ExtractStateFromZipCode<Zip extends ZipCode | ZipCodePlusFour> =
+	Zip extends `${infer StateCode}${infer _Rest}` ? StateCode : never
+
+/**
+ * Record of US state abbreviations to their corresponding ZIP code prefix (the leading digit). A cheap geographic
+ * prior: a 5-digit code's first digit narrows it to a band of states, which the parser can weigh against the
+ * surrounding city/state tokens.
+ *
+ * @internal
+ * @see {@linkcode ZipCodePrefixAbbreviationMap} for the reverse mapping.
+ */
+export const StateAbbreviationZipCodePrefixRecord = {
+	AL: 3,
+	AK: 9,
+	AZ: 8,
+	AR: 7,
+	CA: 9,
+	CO: 8,
+	CT: 0,
+	DE: 1,
+	DC: 2,
+	FL: 3,
+	GA: 3,
+	HI: 9,
+	ID: 8,
+	IL: 6,
+	IN: 4,
+	IA: 5,
+	KS: 6,
+	KY: 4,
+	LA: 7,
+	ME: 0,
+	MD: 2,
+	MA: 0,
+	MI: 4,
+	MN: 5,
+	MS: 3,
+	MO: 6,
+	MT: 5,
+	NE: 6,
+	NV: 8,
+	NH: 0,
+	NJ: 0,
+	NM: 8,
+	NY: 1,
+	NC: 2,
+	ND: 5,
+	OH: 4,
+	OK: 7,
+	OR: 9,
+	PA: 1,
+	RI: 0,
+	SC: 2,
+	SD: 5,
+	TN: 3,
+	TX: 7,
+	UT: 8,
+	VT: 0,
+	VA: 2,
+	WA: 9,
+	WV: 2,
+	WI: 5,
+	WY: 8,
+	PR: 0,
+	GU: 9,
+	VI: 0,
+	MP: 9,
+	AS: 9,
+} as const satisfies Record<USStateAbbreviation, ZipCodeDigit>
+
+/**
+ * Map of ZIP code prefixes to their corresponding US state abbreviations.
+ */
+const ZipCodePrefixAbbreviationMap = new Map<ZipCodeDigit, USStateAbbreviation[]>()
+
+for (const [state, prefix] of Object.entries(StateAbbreviationZipCodePrefixRecord) as [
+	USStateAbbreviation,
+	ZipCodeDigit,
+][]) {
+	const states = ZipCodePrefixAbbreviationMap.get(prefix) ?? []
+	ZipCodePrefixAbbreviationMap.set(prefix, [...states, state])
+}
+
+export { ZipCodePrefixAbbreviationMap }
+
+/**
+ * Regex patterns for ZIP codes.
+ */
+export const ZipCodePatterns = {
+	/**
+	 * 5-digit, or 9-digit ZIP code or ZIP+4 code.
+	 */
+	Standard: /^\d{5}(?:[-\s]\d{4})?$/,
+
+	/**
+	 * Two-letter state abbreviation followed by a 5-digit ZIP code or ZIP+4 code.
+	 */
+	StateAbbreviationWithZipCode: /^(?:([A-Za-z]{2})[ ,]*)?([0-9]{5}(?:[-\s][0-9]{4})?)$/,
+} as const
+
+/**
+ * Type-predicate to determine if a value is a valid ZIP code.
+ */
+export function isZipCode(input: unknown): input is ZipCode | ZipCodePlusFour {
+	return typeof input === "string" && ZipCodePatterns.Standard.test(input)
+}
+
+export interface PluckedStateZIPCodeResult {
+	stateAbbreviation: USStateAbbreviation | null
+	zipCode: ZipCode | ZipCodePlusFour
+}
+
+/**
+ * Given an address string like `"NY"`, `"CA 94016"`, attempts to match the state abbreviation and postal code, if
+ * applicable.
+ *
+ * @see {@linkcode isUSStateAbbreviation} to validate the state abbreviation.
+ */
+export function pluckStateZIPCode(input: unknown): PluckedStateZIPCodeResult | null {
+	if (!input || typeof input !== "string") return null
+
+	const [, stateAbbreviation, zipCode = null] = input.match(ZipCodePatterns.StateAbbreviationWithZipCode) || []
+
+	if (!zipCode) return null
+
+	const normalizedState = stateAbbreviation?.toUpperCase()
+
+	return {
+		stateAbbreviation: isUSStateAbbreviation(normalizedState) ? normalizedState : null,
+		zipCode: zipCode as ZipCode | ZipCodePlusFour,
+	}
+}