@mailwoman/formatter 4.8.1

package/out/format.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   This is the canonical home for Mailwoman's address formatting, consolidated from two earlier
+ *   half-implementations: the `core/formatter` stub (which wrapped OpenCage but hardcoded `US`) and
+ *   the corpus synthesis formatter (`corpus/src/format.ts`, the fuller one this is ported from).
+ *
+ *   It bridges Mailwoman's `ComponentTag` schema to OpenCage's `address-formatting` templates
+ *   (vendored via `@fragaria/address-formatter`, MIT) so callers get idiomatic per-country output
+ *   without reinventing template logic. Owning our own templates — so we can express the slots
+ *   OpenCage can't (`unit`, `intersection`, `cedex`, the JP tags) — is a deliberate follow-up; this
+ *   first cut keeps Fragaria as the engine and concentrates the mapping in one place.
+ *
+ *   Known limitations inherited from the OpenCage vocabulary (documented, not blockers):
+ *
+ *   - `unit`: no slot, so units ride the road line (`"Pennsylvania Ave NW Apt 4B"`).
+ *   - `intersection_a` / `intersection_b`: joined as `"<a> & <b>"` into the road field.
+ *   - `cedex` (FR): folded into `postcode` (`"75008 CEDEX 08"`) so the FR template slots it right.
+ *   - JP-specific tags (`prefecture`, `municipality`, …): no mapping yet.
+ */
+import type { ClassificationMap } from "@mailwoman/core/classification";
+import type { ComponentTag } from "@mailwoman/core/types";
+/** A partial map of `ComponentTag` → string value — the canonical formatter input. */
+export type ComponentDict = Partial<Record<ComponentTag, string>>;
+/** Options accepted by `formatAddress`. */
+export interface FormatAddressOptions {
+    /**
+     * Append the country name as a final line (`"USA"`, `"France"`). Default `false`: most rows are
+     * intra-country and the country line is redundant noise.
+     */
+    appendCountry?: boolean;
+    /**
+     * Apply OpenCage's per-country abbreviation rules (`"Avenue"` → `"Ave"`). Default `false` —
+     * callers that want abbreviation usually run it as their own augmentation pass.
+     */
+    abbreviate?: boolean;
+    /**
+     * Replace the template's newlines with this separator. Default `undefined` (keep newlines). Use
+     * `", "` for single-line output, or `" "` to strip internal punctuation.
+     */
+    separator?: string;
+}
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string if `components` is empty after translation. Throws nothing — bad inputs
+ * degrade to the longest meaningful prefix.
+ */
+export declare function formatAddress(components: ComponentDict, country: string, opts?: FormatAddressOptions): string;
+/**
+ * Format a legacy {@linkcode ClassificationMap} (`Map<VisibleClassification, string[]>`, as emitted
+ * by the rule-based pipeline) into an idiomatic address string. Subsumes the former
+ * `core/formatter` stub. Multi-span values are space-joined; unit-like labels are merged.
+ */
+export declare function formatFromClassificationMap(map: ClassificationMap, country: string, opts?: FormatAddressOptions): string;
+/**
+ * Drop any component whose value isn't actually present in the formatted `raw`. OpenCage's
+ * per-country templates legitimately omit some inputs (FR regions absorbed by the postcode; US
+ * state names abbreviated), and downstream alignment requires `components[tag]` to occur in `raw`.
+ * Comparison is case- and whitespace-insensitive; the retained value is the original input.
+ */
+export declare function reconcileComponents(components: ComponentDict, raw: string): ComponentDict;
+/**
+ * Translate a `ComponentTag` dict to the OpenCage vocabulary `@fragaria/address-formatter` expects.
+ * Exported for testing and for callers that pre-build the dict for batch formatting.
+ */
+export declare function toOpenCageComponents(components: ComponentDict, country: string): Record<string, string>;
+//# sourceMappingURL=format.d.ts.map

package/out/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAyB,MAAM,gCAAgC,CAAA;AAC9F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAEzD,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;AAEjE,2CAA2C;AAC3C,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAWjH;AAoBD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAC1C,GAAG,EAAE,iBAAiB,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,oBAAyB,GAC7B,MAAM,CAoBR;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,aAAa,CAWzF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4BvG"}

package/out/format.js

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a `ComponentTag`-keyed dict into a country-localized string — the inverse of the parser.
+ *
+ *   This is the canonical home for Mailwoman's address formatting, consolidated from two earlier
+ *   half-implementations: the `core/formatter` stub (which wrapped OpenCage but hardcoded `US`) and
+ *   the corpus synthesis formatter (`corpus/src/format.ts`, the fuller one this is ported from).
+ *
+ *   It bridges Mailwoman's `ComponentTag` schema to OpenCage's `address-formatting` templates
+ *   (vendored via `@fragaria/address-formatter`, MIT) so callers get idiomatic per-country output
+ *   without reinventing template logic. Owning our own templates — so we can express the slots
+ *   OpenCage can't (`unit`, `intersection`, `cedex`, the JP tags) — is a deliberate follow-up; this
+ *   first cut keeps Fragaria as the engine and concentrates the mapping in one place.
+ *
+ *   Known limitations inherited from the OpenCage vocabulary (documented, not blockers):
+ *
+ *   - `unit`: no slot, so units ride the road line (`"Pennsylvania Ave NW Apt 4B"`).
+ *   - `intersection_a` / `intersection_b`: joined as `"<a> & <b>"` into the road field.
+ *   - `cedex` (FR): folded into `postcode` (`"75008 CEDEX 08"`) so the FR template slots it right.
+ *   - JP-specific tags (`prefecture`, `municipality`, …): no mapping yet.
+ */
+import addressFormatter from "@fragaria/address-formatter";
+/**
+ * Render a component dict into an idiomatic per-country address string.
+ *
+ * Returns an empty string if `components` is empty after translation. Throws nothing — bad inputs
+ * degrade to the longest meaningful prefix.
+ */
+export function formatAddress(components, country, opts = {}) {
+    const ocComponents = toOpenCageComponents(components, country);
+    if (Object.keys(ocComponents).length === 0)
+        return "";
+    const raw = addressFormatter.format(ocComponents, {
+        abbreviate: opts.abbreviate ?? false,
+        appendCountry: opts.appendCountry ?? false,
+    });
+    const trimmed = raw.replace(/\s+$/g, "");
+    return opts.separator !== undefined ? trimmed.replace(/\n+/g, opts.separator) : trimmed;
+}
+/**
+ * Map of legacy rule-classifier {@linkcode VisibleClassification} labels to the canonical
+ * `ComponentTag` schema. The two vocabularies are kept independent on purpose (rule classifiers
+ * emit one, the neural classifier the other); this adapter is the bridge so a `ClassificationMap`
+ * can use the same formatter. `level` / `unit_designator` / `level_designator` are folded into
+ * `unit`.
+ */
+const CLASSIFICATION_TO_TAG = {
+    country: "country",
+    region: "region",
+    locality: "locality",
+    dependency: "dependent_locality",
+    postcode: "postcode",
+    house_number: "house_number",
+    street: "street",
+    venue: "venue",
+};
+/**
+ * Format a legacy {@linkcode ClassificationMap} (`Map<VisibleClassification, string[]>`, as emitted
+ * by the rule-based pipeline) into an idiomatic address string. Subsumes the former
+ * `core/formatter` stub. Multi-span values are space-joined; unit-like labels are merged.
+ */
+export function formatFromClassificationMap(map, country, opts = {}) {
+    const components = {};
+    const unitParts = [];
+    for (const [classification, values] of map) {
+        const value = values.filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+        if (!value)
+            continue;
+        if (classification === "unit" || classification === "level") {
+            unitParts.push(value);
+            continue;
+        }
+        const tag = CLASSIFICATION_TO_TAG[classification];
+        if (tag)
+            components[tag] = value;
+    }
+    if (unitParts.length)
+        components.unit = unitParts.join(" ");
+    return formatAddress(components, country, opts);
+}
+/**
+ * Drop any component whose value isn't actually present in the formatted `raw`. OpenCage's
+ * per-country templates legitimately omit some inputs (FR regions absorbed by the postcode; US
+ * state names abbreviated), and downstream alignment requires `components[tag]` to occur in `raw`.
+ * Comparison is case- and whitespace-insensitive; the retained value is the original input.
+ */
+export function reconcileComponents(components, raw) {
+    const haystack = raw.toLowerCase().replace(/\s+/g, " ");
+    const out = {};
+    for (const [k, v] of Object.entries(components)) {
+        if (!v)
+            continue;
+        const needle = v.toLowerCase().replace(/\s+/g, " ");
+        if (haystack.includes(needle))
+            out[k] = v;
+    }
+    return out;
+}
+/**
+ * Translate a `ComponentTag` dict to the OpenCage vocabulary `@fragaria/address-formatter` expects.
+ * Exported for testing and for callers that pre-build the dict for batch formatting.
+ */
+export function toOpenCageComponents(components, country) {
+    const out = {};
+    const road = composeRoad(components);
+    if (road)
+        out.road = road;
+    if (components.house_number)
+        out.house_number = components.house_number;
+    if (components.venue)
+        out.house = components.venue;
+    if (components.locality)
+        out.city = components.locality;
+    if (components.dependent_locality)
+        out.suburb = components.dependent_locality;
+    if (components.subregion)
+        out.county = components.subregion;
+    if (components.region)
+        out.state = components.region;
+    const postcode = composePostcode(components);
+    if (postcode)
+        out.postcode = postcode;
+    if (components.po_box)
+        out.po_box = components.po_box;
+    if (components.attention)
+        out.attention = components.attention;
+    if (components.country)
+        out.country = components.country;
+    // country_code drives template selection, not output. Only emit it alongside another component —
+    // otherwise the template renders the bare code ("US") as a fallback line, which no caller wants.
+    const cc = country.trim().toLowerCase();
+    if (cc && Object.keys(out).length > 0)
+        out.country_code = cc;
+    return out;
+}
+/**
+ * Build the `road` line from prefix / particle / street / suffix / unit / intersection components:
+ *
+ * ```
+ * [intersection_a & intersection_b]
+ * OR
+ * [street_prefix] [street_prefix_particle] [street] [street_suffix] [unit]
+ * ```
+ */
+function composeRoad(components) {
+    if (components.intersection_a && components.intersection_b) {
+        return `${components.intersection_a} & ${components.intersection_b}`;
+    }
+    const parts = [];
+    if (components.street_prefix)
+        parts.push(components.street_prefix);
+    if (components.street_prefix_particle)
+        parts.push(components.street_prefix_particle);
+    if (components.street)
+        parts.push(components.street);
+    if (components.street_suffix)
+        parts.push(components.street_suffix);
+    if (components.unit)
+        parts.push(components.unit);
+    return parts.join(" ").replace(/\s+/g, " ").trim();
+}
+/**
+ * Fold CEDEX into postcode for FR-style output: `"75008"` + `"CEDEX 08"` → `"75008 CEDEX 08"`. If
+ * only one is present, return it; if neither, return empty.
+ */
+function composePostcode(components) {
+    const base = components.postcode?.trim() ?? "";
+    const cedex = components.cedex?.trim() ?? "";
+    if (base && cedex)
+        return `${base} ${cedex}`.replace(/\s+/g, " ");
+    return base || cedex;
+}
+//# sourceMappingURL=format.js.map

package/out/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../format.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/formatter` — the inverse of the parser.
+ *
+ *   - {@linkcode formatAddress} / {@linkcode formatFromClassificationMap}: components → idiomatic,
+ *       locale-aware address string (for display and corpus synthesis).
+ *   - {@linkcode canonicalKey}: components → a normalized, deterministic match key (for the matcher's
+ *       blocking stage).
+ */
+export * from "./format.js";
+export * from "./key.js";
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}

package/out/index.js

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/formatter` — the inverse of the parser.
+ *
+ *   - {@linkcode formatAddress} / {@linkcode formatFromClassificationMap}: components → idiomatic,
+ *       locale-aware address string (for display and corpus synthesis).
+ *   - {@linkcode canonicalKey}: components → a normalized, deterministic match key (for the matcher's
+ *       blocking stage).
+ */
+export * from "./format.js";
+export * from "./key.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA"}

package/out/key.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all gated on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first cut is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+import type { ComponentDict } from "./format.js";
+/** Options accepted by {@linkcode canonicalKey}. */
+export interface CanonicalKeyOptions {
+    /** Field separator in the emitted key. Default `"|"` — preserves field boundaries for blocking. */
+    separator?: string;
+}
+/**
+ * Normalize a single token for matching: Unicode-decompose and strip combining marks (so `é` →
+ * `e`), lowercase, replace `&`/`+`/`/` with spaces, drop every non-alphanumeric character, and
+ * collapse whitespace. Deterministic and reversible-free — the same input always yields the same
+ * output.
+ */
+export declare function normalizeAddressToken(input: string): string;
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying
+ * field normalized via {@linkcode normalizeAddressToken}, in fixed order, joined by the separator.
+ * Empty / whitespace-only fields are skipped. Returns an empty string if nothing identifying
+ * remains.
+ */
+export declare function canonicalKey(components: ComponentDict, opts?: CanonicalKeyOptions): string;
+//# sourceMappingURL=key.d.ts.map

package/out/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAwBhD,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IACnC,mGAAmG;IACnG,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgB3D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAY9F"}

package/out/key.js

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all gated on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first cut is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+/**
+ * The address-identifying components, in canonical key order. Venue / attention are intentionally
+ * excluded — those carry organization identity, which the record layer keys separately.
+ */
+const KEY_FIELD_ORDER = [
+    "po_box",
+    "house_number",
+    "street_prefix",
+    "street_prefix_particle",
+    "street",
+    "street_suffix",
+    "intersection_a",
+    "intersection_b",
+    "unit",
+    "dependent_locality",
+    "locality",
+    "subregion",
+    "region",
+    "postcode",
+    "country",
+];
+/**
+ * Normalize a single token for matching: Unicode-decompose and strip combining marks (so `é` →
+ * `e`), lowercase, replace `&`/`+`/`/` with spaces, drop every non-alphanumeric character, and
+ * collapse whitespace. Deterministic and reversible-free — the same input always yields the same
+ * output.
+ */
+export function normalizeAddressToken(input) {
+    return (input
+        .normalize("NFKD")
+        // strip combining marks (U+0300–U+036F) left by NFKD decomposition, so "é" → "e"
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        // apostrophes are intra-word (possessives, "O'Brien") — delete so the token stays whole
+        .replace(/['’`]/g, "")
+        // connective punctuation becomes a space rather than vanishing (so "A&B" → "a b", not "ab")
+        .replace(/[&+/]/g, " ")
+        // everything else non-alphanumeric (keep spaces) is noise
+        .replace(/[^a-z0-9\s]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim());
+}
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying
+ * field normalized via {@linkcode normalizeAddressToken}, in fixed order, joined by the separator.
+ * Empty / whitespace-only fields are skipped. Returns an empty string if nothing identifying
+ * remains.
+ */
+export function canonicalKey(components, opts = {}) {
+    const separator = opts.separator ?? "|";
+    const parts = [];
+    for (const tag of KEY_FIELD_ORDER) {
+        const value = components[tag];
+        if (!value)
+            continue;
+        const normalized = normalizeAddressToken(value);
+        if (normalized)
+            parts.push(normalized);
+    }
+    return parts.join(separator);
+}
+//# sourceMappingURL=key.js.map

package/out/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;GAGG;AACH,MAAM,eAAe,GAAG;IACvB,QAAQ;IACR,cAAc;IACd,eAAe;IACf,wBAAwB;IACxB,QAAQ;IACR,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,MAAM;IACN,oBAAoB;IACpB,UAAU;IACV,WAAW;IACX,QAAQ;IACR,UAAU;IACV,SAAS;CACkC,CAAA;AAQ5C;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,CACN,KAAK;SACH,SAAS,CAAC,MAAM,CAAC;QAClB,iFAAiF;SAChF,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,WAAW,EAAE;QACd,wFAAwF;SACvF,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;QACtB,4FAA4F;SAC3F,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;QACvB,0DAA0D;SACzD,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC;SAC5B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE,CACR,CAAA;AACF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,UAAyB,EAAE,OAA4B,EAAE;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAA;IACvC,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;QAC/C,IAAI,UAAU;YAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mailwoman/formatter",
+  "version": "4.8.1",
+  "description": "The inverse of the parser: render Mailwoman `ComponentTag` components into an idiomatic, locale-aware address string — plus a canonical, normalized match key for record linkage. Consolidates the former core/formatter stub and corpus synthesis formatter behind one API.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "formatter"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js",
+    "./format": "./out/format.js",
+    "./key": "./out/key.js"
+  },
+  "dependencies": {
+    "@fragaria/address-formatter": "^6.7.1",
+    "@mailwoman/core": "4.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.2"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}