@mailwoman/record 7.2.0 → 7.3.0

package/address.ts

@@ -0,0 +1,116 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical address record — the matcher's unit of address identity, and the canonical record
+ *   the organization and contact records build on.
+ *
+ *   It is plain data: parser components + the formatter's match key + an optional resolved geocode,
+ *   composed into one object. No ORM, no decorators, no schema-generation machinery — if we need a
+ *   database we reach for Kysely at the call site, not a model layer here.
+ *
+ *   The geocode fields mirror mailwoman's `GeocodeResult` (tier + calibrated uncertainty + hierarchy)
+ *   on purpose: that is the location signal the Fellegi-Sunter scorer weights its distance evidence
+ *   by — two records sharing a `address_point` coordinate is strong agreement; sharing an
+ *   `interpolated` centroid is weak; a PO-box / multi-unit coordinate is barely location agreement
+ *   at all (the NAACCR precedent, see the geocode-first record-matching concept doc).
+ */
+
+import { type ComponentDict, type FormatAddressOptions, canonicalKey, formatAddress } from "@mailwoman/formatter"
+
+/** A geographic coordinate (WGS84 decimal degrees). */
+export interface GeoCoordinate {
+	latitude: number
+	longitude: number
+}
+
+/**
+ * The resolution tier that produced a coordinate, mirroring mailwoman's geocoder (`address_point` > `interpolated` >
+ * `street` > `admin`). Kept as a local plain union so this package stays decoupled from the heavy geocoder runtime; a
+ * `GeocodeResult.resolution_tier` maps in directly. (`street` = a street centroid for a street-only query, #1042 —
+ * coarser than a house-number estimate, finer than an admin centroid.)
+ */
+export type ResolutionTier = "address_point" | "interpolated" | "street" | "admin"
+
+/** One resolved admin-hierarchy ancestor (most specific first), for spelling-invariant blocking. */
+export interface HierarchyNode {
+	tag: string
+	value: string
+	placeID?: string
+}
+
+/** A resolved geocode attached to an address record — the location signal the matcher scores on. */
+export interface AddressGeocode {
+	coordinate: GeoCoordinate
+	tier: ResolutionTier
+	/** Calibrated uncertainty radius in meters; `null` for the admin tier (no sub-locality estimate). */
+	uncertaintyMeters: number | null
+	/** Resolved admin hierarchy, locality → country (most specific first). */
+	hierarchy?: HierarchyNode[]
+	/** A delivery point, not a building — weakens location agreement even at a precise coordinate. */
+	poBox?: boolean
+	/** A multi-unit building where many records share one coordinate — weakens unit-level agreement. */
+	multiUnit?: boolean
+}
+
+/**
+ * The canonical address record. Composes the parser's components, the formatter's match key, an optional human-readable
+ * form, and an optional resolved geocode. Plain data — no behavior.
+ */
+export interface PostalAddress {
+	/** Parsed address components (`ComponentTag`-keyed). */
+	components: ComponentDict
+	/** Normalized, deterministic match key for blocking (from `@mailwoman/formatter`). */
+	canonicalKey: string
+	/** Optional human-readable single-line form, for display. */
+	formatted?: string
+	/** Resolved location, when geocoded. */
+	geocode?: AddressGeocode
+	/** The original free-text input, when known (provenance). */
+	raw?: string
+}
+
+/** Options for {@linkcode toPostalAddress}. */
+export interface ToPostalAddressOptions {
+	/** Country (ISO-2 or name) for formatting. Defaults to the `country` component, else unset. */
+	country?: string
+	/** The original free-text input to retain as provenance. */
+	raw?: string
+	/** Also compute a human-readable `formatted` string. Default `true`. */
+	format?: boolean
+	/** Formatting options forwarded to the formatter. Defaults to single-line (`", "`). */
+	formatOptions?: FormatAddressOptions
+}
+
+/**
+ * Build a canonical {@linkcode PostalAddress} from parsed components: fills the match key (always) and a human-readable
+ * form (unless disabled). Attach a geocode separately with {@linkcode withGeocode} once the address is resolved.
+ */
+export function toPostalAddress(components: ComponentDict, opts: ToPostalAddressOptions = {}): PostalAddress {
+	const country = opts.country ?? components.country ?? ""
+
+	const record: PostalAddress = {
+		components,
+		canonicalKey: canonicalKey(components),
+	}
+
+	if (opts.raw !== undefined) {
+		record.raw = opts.raw
+	}
+
+	if (opts.format !== false) {
+		const formatted = formatAddress(components, country, opts.formatOptions ?? { separator: ", " })
+
+		if (formatted) {
+			record.formatted = formatted
+		}
+	}
+
+	return record
+}
+
+/** Attach (or replace) a resolved geocode on an address record, returning a new record. */
+export function withGeocode(record: PostalAddress, geocode: AddressGeocode): PostalAddress {
+	return { ...record, geocode }
+}

package/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/record` — the canonicalize layer for the geocode-first matcher.
+ *
+ *   Address-first: {@linkcode PostalAddress} is the canonical record. The per-field normalizers
+ *   ({@linkcode parsePersonName}, {@linkcode canonicalizeOrganizationName}) build on the same
+ *   plain-data pattern. Contact records and the comparator/Fellegi-Sunter layer land in the
+ *   matcher.
+ */
+
+export * from "./address.ts"
+export * from "./name.ts"
+export * from "./organization.ts"

package/name.ts

@@ -0,0 +1,303 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Person-name parsing — split a full name into components for the matcher to canonicalize and
+ *   compare.
+ *
+ *   A rule-based positional parser, the portable recipe from `python-nameparser`: split on a comma to
+ *   detect `Last, First` inversion, then classify tokens by position against configurable title /
+ *   suffix / particle lists. We deliberately store the surname **particle** (`van`, `de la`, `von`)
+ *   separately from the bare surname (the `theiconic/name-parser` pattern) so the matcher can
+ *   compare `Vega` independent of `de la` — sources that drop or vary the particle still match.
+ *
+ *   Scope + honesty (per the name-canonicalization research pass):
+ *
+ *   - Western / romanized names only. Cultural given-family ORDER variation (East-Asian family-first)
+ *       and transliteration are not handled here — a documented follow-up.
+ *   - Nickname → canonical-root mapping is intentionally NOT done at parse time: it is lossy and
+ *       gendered (Bobbie → Robert _or_ Roberta), so equivalence belongs in the matcher as a fuzzy
+ *       agreement level, not a destructive rewrite. We only _extract_ a parenthetical/quoted
+ *       nickname.
+ *   - A CRF parser (probablepeople) is the gold-standard reference but too heavy to port; this
+ *       positional parser covers the documented hard cases (inversion, particles, generational +
+ *       professional suffixes) without a model.
+ */
+
+/** A parsed person name. All fields optional — the parser fills what it can identify. */
+export interface PersonName {
+	/** Title / salutation that preceded the name (`Dr`, `Mr`, `Capt`). */
+	prefix?: string
+	/** First / given name. */
+	given?: string
+	/** Middle name(s) or initial. */
+	middle?: string
+	/** Surname, _without_ any particle (`Vega`, not `de la Vega`). */
+	family?: string
+	/** Surname particle, stored separately (`de la`, `van der`, `von`). */
+	familyParticle?: string
+	/** Generational or professional suffix (`Jr`, `III`, `PhD`, `MD`). */
+	suffix?: string
+	/** A parenthetical or quoted nickname (`"Gob"` in `George "Gob" Bluth`). */
+	nickname?: string
+}
+
+/** Titles / salutations that lead a name. Matched case-insensitively, trailing `.` ignored. */
+const TITLES = new Set([
+	"airman",
+	"br",
+	"brig",
+	"brigadier",
+	"capt",
+	"captain",
+	"cmdr",
+	"col",
+	"colonel",
+	"commander",
+	"commissioner",
+	"cpl",
+	"cpt",
+	"dep",
+	"deputy",
+	"doctor",
+	"dr",
+	"father",
+	"fr",
+	"gen",
+	"general",
+	"hon",
+	"honorable",
+	"judge",
+	"lt",
+	"ltcol",
+	"ltgen",
+	"maj",
+	"major",
+	"master",
+	"miss",
+	"mr",
+	"mrs",
+	"ms",
+	"mx",
+	"pastor",
+	"pfc",
+	"pres",
+	"president",
+	"private",
+	"prof",
+	"professor",
+	"pvt",
+	"rabbi",
+	"rep",
+	"representative",
+	"rev",
+	"reverend",
+	"sen",
+	"senator",
+	"sgt",
+	"sir",
+	"sister",
+])
+
+/** Generational + professional suffixes that trail a name. */
+const SUFFIXES = new Set([
+	// generational
+	"jr",
+	"sr",
+	"i",
+	"ii",
+	"iii",
+	"iv",
+	"v",
+	"vi",
+	"vii",
+	"viii",
+	// professional / honorific
+	"phd",
+	"md",
+	"do",
+	"dds",
+	"dmd",
+	"dvm",
+	"esq",
+	"esquire",
+	"jd",
+	"llm",
+	"cpa",
+	"rn",
+	"lpn",
+	"pa",
+	"pe",
+	"od",
+	"dc",
+	"dpm",
+	"psyd",
+	"edd",
+	"mba",
+	"mfa",
+	"msw",
+	"pharmd",
+])
+
+/**
+ * Surname particles. Consecutive particles fold together (`de` + `la` → `de la`), and the next non-particle token
+ * begins the bare surname.
+ */
+const PARTICLES = new Set([
+	"al",
+	"bin",
+	"da",
+	"das",
+	"de",
+	"del",
+	"della",
+	"den",
+	"der",
+	"di",
+	"do",
+	"dos",
+	"du",
+	"el",
+	"ibn",
+	"la",
+	"le",
+	"lo",
+	"mac",
+	"mc",
+	"san",
+	"santa",
+	"st",
+	"ter",
+	"van",
+	"vande",
+	"vanden",
+	"vander",
+	"vere",
+	"von",
+	"zu",
+	"zur",
+])
+
+const isPresent = (s: string | undefined | null): s is string => typeof s === "string" && s.trim().length > 0
+const norm = (token: string): string => token.replace(/\.$/, "").toLowerCase()
+const countChar = (s: string, c: string): number => s.split(c).length - 1
+
+/**
+ * Parse a full name into components. Returns `null` for empty input. Best-effort and non-throwing — ambiguous input
+ * degrades gracefully rather than erroring.
+ */
+export function parsePersonName(input: string | null | undefined): PersonName | null {
+	if (!isPresent(input)) return null
+
+	const result: PersonName = {}
+
+	// 1. Extract a parenthetical "(Jim)" or quoted "Jim" nickname, then strip it out.
+	let working = input
+		.replace(/\s*\(([^)]+)\)\s*/g, (_m, n: string) => {
+			if (!result.nickname) {
+				result.nickname = n.trim()
+			}
+
+			return " "
+		})
+		.replace(/\s*"([^"]+)"\s*/g, (_m, n: string) => {
+			if (!result.nickname) {
+				result.nickname = n.trim()
+			}
+
+			return " "
+		})
+		.replace(/\s+/g, " ")
+		.trim()
+
+	// 2. Resolve a single comma: "Last, First" inversion, unless the tail is a known suffix
+	//    ("John Smith, Jr."), in which case keep order and treat the tail as a suffix.
+	if (countChar(working, ",") === 1) {
+		const [head, tail] = working.split(",").map((p) => p.trim())
+
+		if (tail && tail.split(/\s+/).every((t) => SUFFIXES.has(norm(t)))) {
+			result.suffix = tail
+			working = head!
+		} else if (head && tail) {
+			working = `${tail} ${head}`
+		}
+	}
+
+	const tokens = working.split(/\s+/).filter(Boolean)
+
+	if (tokens.length === 0) return Object.keys(result).length ? result : null
+
+	// 3. Leading titles → prefix.
+	const prefixParts: string[] = []
+
+	while (tokens.length > 1 && TITLES.has(norm(tokens[0]!))) {
+		prefixParts.push(tokens.shift()!)
+	}
+
+	if (prefixParts.length) {
+		result.prefix = prefixParts.join(" ")
+	}
+
+	// 4. Trailing suffixes → suffix (a single name token must remain).
+	const suffixParts: string[] = []
+
+	while (tokens.length > 1 && SUFFIXES.has(norm(tokens[tokens.length - 1]!))) {
+		suffixParts.unshift(tokens.pop()!)
+	}
+
+	if (suffixParts.length) {
+		result.suffix = isPresent(result.suffix) ? `${suffixParts.join(" ")} ${result.suffix}` : suffixParts.join(" ")
+	}
+
+	if (tokens.length === 0) return result
+
+	// 5. Locate the surname particle run; everything from it onward is the (particled) surname.
+	let particleStart = -1
+
+	for (let i = 0; i < tokens.length; i++) {
+		// A particle only starts a surname if a bare-surname token follows it.
+		if (PARTICLES.has(norm(tokens[i]!)) && i < tokens.length - 1) {
+			particleStart = i
+			break
+		}
+	}
+
+	if (particleStart >= 0) {
+		let i = particleStart
+		const particleParts: string[] = []
+
+		while (i < tokens.length - 1 && PARTICLES.has(norm(tokens[i]!))) {
+			particleParts.push(tokens[i]!)
+			i++
+		}
+		result.familyParticle = particleParts.join(" ")
+		result.family = tokens.slice(i).join(" ")
+		const before = tokens.slice(0, particleStart)
+
+		if (before.length) {
+			result.given = before[0]
+		}
+
+		if (before.length > 1) {
+			result.middle = before.slice(1).join(" ")
+		}
+
+		return result
+	}
+
+	// 6. No particle: last token is the surname, first is given, the rest is middle.
+	if (tokens.length === 1) {
+		result.given = tokens[0]
+
+		return result
+	}
+	result.given = tokens[0]
+	result.family = tokens[tokens.length - 1]
+
+	if (tokens.length > 2) {
+		result.middle = tokens.slice(1, -1).join(" ")
+	}
+
+	return result
+}

package/organization.ts

@@ -0,0 +1,267 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Organization-name canonicalization — reduce a company name to a stable, comparable key.
+ *
+ *   Winkler's record-linkage recipe: words of little distinguishing power (the legal designation —
+ *   `Corporation`, `Limited`, `LLC`) are normalized away before matching, so `Acme Corp` and `Acme
+ *   Corporation, LLC` collapse to the same key. We also split off a `doing business as` clause and
+ *   normalize connectives (`&` → `and`), punctuation, accents, and a leading `The`.
+ *
+ *   **The collision problem (#668).** A legal-form token in one jurisdiction is a meaningful word in
+ *   another domain. `PT` is Indonesia's `Perseroan Terbatas` (its LLC) — and US-healthcare
+ *   shorthand for _Physical Therapy_. `SCA` / `SCS` are French/Belgian/Luxembourg commandite forms
+ *   — and, in a clinic's name, _Sudden Cardiac Arrest_ / _Spinal Cord Stimulator_. A single
+ *   universal strip-list can't be right for both: strip `PT` and you corrupt `Lakeside PT`; keep it
+ *   and you leave the legal form on an Indonesian company. So the strip-set is computed on **two
+ *   axes**:
+ *
+ *   - **jurisdiction** (ISO 3166-1 alpha-2, e.g. from the resolved address country) — _adds_ the legal
+ *       forms valid in that country. Collision-prone forms (`pt`, `sca`, `scs`) live here, gated
+ *       behind a known jurisdiction, NOT in the universal base.
+ *   - **domain** (an ingest-config tag, e.g. `healthcare`) — _protects_ domain-meaningful tokens from
+ *       ever being stripped, even when a jurisdiction pack would add them. Domain protection wins.
+ *
+ *   `effective = (base ∪ jurisdiction-pack) − domain-protect-pack`. With no options the set is the
+ *   universal base and behavior is byte-for-byte unchanged — the new axes are strictly opt-in.
+ *
+ *   Evidence honesty (per the name-canonicalization research pass): the PERSON-name side is well
+ *   sourced; the ORGANIZATION side is a known evidence gap. This is a solid _canonicalization_
+ *   baseline (the strip-designations principle is Winkler-grounded; the designation list draws on
+ *   the ISO 20275 Entity Legal Forms register and `cleanco`). The jurisdiction/domain packs below
+ *   are grounded seeds, not exhaustive — extend them per ISO 20275 as locales are added. The harder
+ *   org-_matching_ problems — acronym ↔ expansion (`IBM` ↔ `International Business Machines`),
+ *   DBA/alias resolution beyond the simple clause, subsidiary/parent, and TF-IDF n-gram token
+ *   matching — are deferred to a follow-up (a dedicated org-matching research pass + the matcher
+ *   epic).
+ */
+
+/** A canonicalized organization name. */
+export interface OrganizationName {
+	/** The original input, verbatim. */
+	raw: string
+	/** Normalized, designation-stripped key for blocking and comparison. */
+	canonical: string
+	/** Legal designations that were stripped (`llc`, `inc`, `gmbh`), in encounter order. */
+	designations: string[]
+	/** The `doing business as` / trade-name clause, canonicalized, when one was present. */
+	dba?: string
+}
+
+/**
+ * A domain pack name. Each protects the abbreviations that are meaningful in that domain from being stripped as legal
+ * forms (see {@link DOMAIN_PROTECTED}). `general` protects nothing — the explicit "no domain" choice. Add a pack here
+ * (and to {@link DOMAIN_PROTECTED}) per ingest domain.
+ */
+export type DesignationDomain = "general" | "healthcare"
+
+/**
+ * Context for {@link canonicalizeOrganizationName}. Omit both fields for the universal base behavior.
+ */
+export interface CanonicalizeOptions {
+	/**
+	 * ISO 3166-1 alpha-2 country code of the org's jurisdiction (typically the resolved address country). Adds that
+	 * country's legal forms — including collision-prone ones gated out of the base — to the strip-set. Case-insensitive;
+	 * unknown codes add nothing.
+	 */
+	jurisdiction?: string
+	/**
+	 * Ingest domain. Protects domain-meaningful abbreviations (e.g. `healthcare` protects `pt` / `sca` / `scs`) from
+	 * being stripped, overriding any jurisdiction pack that would add them.
+	 */
+	domain?: DesignationDomain
+}
+
+/**
+ * Universal legal-entity designations — the forms that are safe to strip regardless of jurisdiction or domain because
+ * they don't collide with common domain abbreviations. Normalized to lowercase with punctuation removed (so `L.L.C.` →
+ * `llc`). Drawn from the ISO 20275 register + `cleanco`'s common set. Stripped as whole tokens wherever they occur.
+ * Deliberately excludes name-meaningful words (`group`, `holdings`, `partners`, `associates`) AND the collision-prone
+ * forms (`pt`, `sca`, `scs`) — those last live in {@link JURISDICTION_DESIGNATIONS}, gated behind a known
+ * jurisdiction.
+ */
+const BASE_DESIGNATIONS = new Set([
+	"inc",
+	"incorporated",
+	"corp",
+	"corporation",
+	"co",
+	"company",
+	"llc",
+	"lllp",
+	"llp",
+	"pllc",
+	"lp",
+	"ltd",
+	"limited",
+	"plc",
+	"pc",
+	"pa",
+	"ag",
+	"sa",
+	"sas",
+	"sarl",
+	"sl",
+	"gmbh",
+	"mbh",
+	"ug",
+	"bv",
+	"nv",
+	"oy",
+	"oyj",
+	"ab",
+	"as",
+	"asa",
+	"spa",
+	"srl",
+	"kg",
+	"kgaa",
+	"kk",
+	"pty",
+	"proprietary",
+	"bhd",
+	"sdn",
+	"cc",
+	"cv",
+	"ulc",
+	"aps",
+	"kft",
+	"zrt",
+	"doo",
+	"ood",
+	"ead",
+	// Belgian forms — safe to add to the base (no domain collision).
+	"bvba",
+	"sprl",
+])
+
+/**
+ * Jurisdiction-gated legal forms (ISO 3166-1 alpha-2 → forms), added only when the jurisdiction is known. This is where
+ * the collision-prone tokens live: `pt` (Indonesia), `sca` / `scs` (French/Belgian/Luxembourg commandite forms).
+ * Stripping these is correct ONLY when we know the org's country — never in the universal base. Grounded seeds, not
+ * exhaustive; extend per ISO 20275.
+ */
+const JURISDICTION_DESIGNATIONS: Record<string, readonly string[]> = {
+	ID: ["pt", "tbk", "ud"], // Perseroan Terbatas / Terbuka (listed) / Usaha Dagang
+	FR: ["sca", "scs", "sci", "eurl", "sasu", "snc"],
+	BE: ["sca", "scs"],
+	LU: ["sca", "scs"],
+	ES: ["scs"], // Sociedad en Comandita Simple
+	IT: ["sapa", "snc"], // S.a.p.a. (commandite par actions) / società in nome collettivo
+}
+
+/**
+ * Domain protect-sets (domain → tokens never stripped). Overrides any jurisdiction pack: a token here stays in the name
+ * even if the org's jurisdiction would treat it as a legal form. `healthcare` guards the clinical abbreviations that
+ * collide with gated legal forms — `pt` (Physical Therapy), `sca` (Sudden Cardiac Arrest), `scs` (Spinal Cord
+ * Stimulator) — plus a couple of always-clinical ones for future-proofing.
+ */
+const DOMAIN_PROTECTED: Record<DesignationDomain, readonly string[]> = {
+	general: [],
+	healthcare: ["pt", "sca", "scs", "ot", "dpt"],
+}
+
+/**
+ * Compute the effective designation strip-set for the given context: `(base ∪ jurisdiction-pack) −
+ * domain-protect-pack`. Returns the shared base set unchanged when no context is given (the byte-stable default), so
+ * the common path allocates nothing.
+ */
+function resolveDesignations(options?: CanonicalizeOptions): ReadonlySet<string> {
+	const jurisdiction = options?.jurisdiction?.trim().toUpperCase()
+	const jurisdictionPack = jurisdiction ? JURISDICTION_DESIGNATIONS[jurisdiction] : undefined
+	const protectPack = options?.domain ? DOMAIN_PROTECTED[options.domain] : undefined
+
+	if (!jurisdictionPack && !protectPack?.length) return BASE_DESIGNATIONS
+
+	const set = new Set(BASE_DESIGNATIONS)
+
+	if (jurisdictionPack) {
+		for (const token of jurisdictionPack) {
+			set.add(token)
+		}
+	}
+
+	if (protectPack) {
+		for (const token of protectPack) {
+			set.delete(token)
+		}
+	}
+
+	return set
+}
+
+/** Splits a `doing business as` / trade-name clause from a legal name. */
+const DBA_PATTERN = /\s+(?:d\/b\/a|dba|doing business as|t\/a|trading as|a\/k\/a|aka|fka|f\/k\/a)\s+/i
+
+/**
+ * Canonicalize one name fragment: lowercase, strip accents, connectives → `and`, drop punctuation, remove a leading
+ * `the`, strip legal designations, collapse whitespace. Returns the key plus the designations it removed.
+ */
+function canonicalizeFragment(
+	fragment: string,
+	designationSet: ReadonlySet<string>
+): { canonical: string; designations: string[] } {
+	const normalized = fragment
+		.normalize("NFKD")
+		.replace(/[̀-ͯ]/g, "")
+		.toLowerCase()
+		// connective punctuation joins words rather than vanishing: "AT&T" → "at and t"
+		.replace(/&/g, " and ")
+		.replace(/\+/g, " and ")
+		// periods + apostrophes are intra-token, so remove (not space): "S.A." → "sa", "Macy's" → "macys"
+		.replace(/[.'’]/g, "")
+		.replace(/[^a-z0-9\s]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim()
+		.replace(/^the\s+/, "")
+
+	const designations: string[] = []
+	const kept: string[] = []
+
+	for (const token of normalized.split(" ")) {
+		if (!token) continue
+
+		if (designationSet.has(token)) {
+			designations.push(token)
+		} else {
+			kept.push(token)
+		}
+	}
+
+	return { canonical: kept.join(" "), designations }
+}
+
+/**
+ * Canonicalize an organization name: split off any `doing business as` clause, then reduce the legal name to a
+ * designation-stripped key. Returns `null` for empty input.
+ *
+ * Pass {@link CanonicalizeOptions} to resolve the jurisdiction × domain collision (#668): a `jurisdiction` adds that
+ * country's legal forms, a `domain` protects its meaningful abbreviations. With no options the universal base set is
+ * used and the result is byte-for-byte the legacy behavior.
+ */
+export function canonicalizeOrganizationName(
+	input: string | null | undefined,
+	options?: CanonicalizeOptions
+): OrganizationName | null {
+	if (typeof input !== "string" || !input.trim()) return null
+
+	const raw = input
+	const designationSet = resolveDesignations(options)
+	const [legalPart, ...dbaParts] = input.split(DBA_PATTERN)
+
+	const { canonical, designations } = canonicalizeFragment(legalPart ?? "", designationSet)
+
+	const result: OrganizationName = { raw, canonical, designations }
+
+	if (dbaParts.length) {
+		const dba = canonicalizeFragment(dbaParts.join(" "), designationSet).canonical
+
+		if (dba) {
+			result.dba = dba
+		}
+	}
+
+	return result
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/record",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "Lean, plain-TypeScript record schema + per-field normalizers for the geocode-first matcher. Address-first: the canonical PostalAddress record composes parser components, the formatter's match key, and a resolved geocode; organization + contact records build on the same canonical record.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -12,37 +12,60 @@
     "out/**/*.js",
     "out/**/*.js.map",
     "out/**/*.d.ts",
-    "out/**/*.d.ts.map"
+    "out/**/*.d.ts.map",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     },
     "./address": {
-      "node": "./address.ts",
-      "default": "./out/address.js",
-      "types": "./out/address.d.ts"
+      "types": "./out/address.d.ts",
+      "default": "./out/address.js"
     },
     "./name": {
-      "node": "./name.ts",
-      "default": "./out/name.js",
-      "types": "./out/name.d.ts"
+      "types": "./out/name.d.ts",
+      "default": "./out/name.js"
     },
     "./organization": {
-      "node": "./organization.ts",
-      "default": "./out/organization.js",
-      "types": "./out/organization.d.ts"
+      "types": "./out/organization.d.ts",
+      "default": "./out/organization.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      },
+      "./address": {
+        "types": "./out/address.d.ts",
+        "default": "./out/address.js"
+      },
+      "./name": {
+        "types": "./out/name.d.ts",
+        "default": "./out/name.js"
+      },
+      "./organization": {
+        "types": "./out/organization.d.ts",
+        "default": "./out/organization.js"
+      }
+    }
   },
   "dependencies": {
-    "@mailwoman/formatter": "7.2.0"
+    "@mailwoman/formatter": "7.3.0"
   },
   "devDependencies": {
     "@types/node": ">=26.1.1"