@mailwoman/codex 4.4.0 → 4.5.0

package/out/fr/cedex.js

@@ -0,0 +1,43 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   CEDEX — Courrier d'Entreprise à Distribution EXceptionnelle (La Poste business routing, NF Z
+ *   10-011 §3.4). A CEDEX line replaces the ordinary delivery line for high-volume business
+ *   recipients: `75008 PARIS CEDEX 08` — the word CEDEX after the distribution office name,
+ *   optionally followed by a 1–2 digit office number. The component is the `CEDEX [NN]` phrase
+ *   itself (the schema's `cedex` tag); the preceding postcode/locality keep their own tags.
+ *
+ *   This slice closes the gap PR #516 documented: the shard builder sourced the shape from SCHEMA.mdx
+ *   prose because codex had no cedex home. Now it does — the builder and any future consumer import
+ *   from here (the no-load-bearing-trivia discipline: one provenanced source).
+ */
+/** Matches a CEDEX phrase: the keyword plus an optional 1–2 digit office number. */
+export const CEDEX_PATTERN = /\bCEDEX(?:\s+(\d{1,2}))?\b/i;
+/**
+ * Find the CEDEX phrase in a line, if any. Returns the LAST match — a CEDEX line places the phrase
+ * terminally (NF Z 10-011), and any earlier occurrence in pathological input is more likely a venue
+ * name fragment.
+ */
+export function matchCedex(text) {
+    let match = null;
+    const re = new RegExp(CEDEX_PATTERN.source, "gi");
+    for (const m of text.matchAll(re)) {
+        match = {
+            matched: m[0],
+            start: m.index,
+            end: m.index + m[0].length,
+            ...(m[1] ? { office: m[1] } : {}),
+        };
+    }
+    return match;
+}
+/** True when the string is exactly a CEDEX phrase (the component-value validator). */
+export function isCedex(input) {
+    if (typeof input !== "string")
+        return false;
+    const m = input.trim().match(CEDEX_PATTERN);
+    return m !== null && m[0].length === input.trim().length;
+}
+//# sourceMappingURL=cedex.js.map

package/out/fr/cedex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cedex.js","sourceRoot":"","sources":["../../fr/cedex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,6BAA6B,CAAA;AAY1D;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACtC,IAAI,KAAK,GAAsB,IAAI,CAAA;IACnC,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACjD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACnC,KAAK,GAAG;YACP,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;YACb,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,GAAG,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;YAC1B,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjC,CAAA;IACF,CAAC;IACD,OAAO,KAAK,CAAA;AACb,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,OAAO,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IAC3C,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;IAC3C,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,CAAA;AACzD,CAAC"}

package/out/fr/index.d.ts

@@ -6,6 +6,7 @@
  *   The French address system (La Poste / ISO 3166-2:FR): street types (voie), postal codes (code
  *   postal), and the admin hierarchy of départements and régions.
  */
+export * from "./cedex.js";
 export * from "./code-postal.js";
 export * from "./departement.js";
 export * from "./region.js";

package/out/fr/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../fr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../fr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/out/fr/index.js

@@ -6,6 +6,7 @@
  *   The French address system (La Poste / ISO 3166-2:FR): street types (voie), postal codes (code
  *   postal), and the admin hierarchy of départements and régions.
  */
+export * from "./cedex.js";
 export * from "./code-postal.js";
 export * from "./departement.js";
 export * from "./region.js";

package/out/fr/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../fr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../fr/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}

package/out/index.d.ts

@@ -17,12 +17,14 @@
  *   `candidateSystemsForPostcode` (the inverse of the per-slice postcode patterns) is a top-level
  *   export.
  */
-export { ADDRESS_SYSTEM_CONVENTIONS, type AddressSystemConventions, conventionsForSystem, } from "./address-system-conventions.js";
+export { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem, type AddressSystemConventions, } from "./address-system-conventions.js";
+export * as au from "./au/index.js";
 export * as ca from "./ca/index.js";
 export * as de from "./de/index.js";
 export * as fr from "./fr/index.js";
 export * as gb from "./gb/index.js";
 export * as jp from "./jp/index.js";
+export * as nz from "./nz/index.js";
 export { candidateSystemsForPostcode, type SystemCode } from "./postcode-systems.js";
 export * as us from "./us/index.js";
 //# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,KAAK,wBAAwB,EAC7B,oBAAoB,GACpB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,EACpB,KAAK,wBAAwB,GAC7B,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}

package/out/index.js

@@ -18,11 +18,13 @@
  *   export.
  */
 export { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem, } from "./address-system-conventions.js";
+export * as au from "./au/index.js";
 export * as ca from "./ca/index.js";
 export * as de from "./de/index.js";
 export * as fr from "./fr/index.js";
 export * as gb from "./gb/index.js";
 export * as jp from "./jp/index.js";
+export * as nz from "./nz/index.js";
 export { candidateSystemsForPostcode } from "./postcode-systems.js";
 export * as us from "./us/index.js";
 //# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAE1B,oBAAoB,GACpB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAmB,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACN,0BAA0B,EAC1B,oBAAoB,GAEpB,MAAM,iCAAiC,CAAA;AACxC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA;AACnC,OAAO,EAAE,2BAA2B,EAAmB,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,MAAM,eAAe,CAAA"}

package/out/nz/delivery-service.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   NZ Post delivery-service types — the second half of the Commonwealth po_box vocabulary: `PO Box
+ *   24999`, `Private Bag 106999`, `CMB B99`, plus the identifier-less counter services.
+ *
+ *   Sourcing (accessed 2026-06-11):
+ *
+ *   - NZ Post Address Standards (ADV358, October 2021 edition hosted on nzpost.co.nz) is the
+ *       authoritative document. Verbatim: "The Delivery Service Type is mandatory. It may be PO
+ *       Box, Private Bag, CMB, Response Bag, Counter Delivery or Poste Restante." Its Delivery
+ *       Service Elements table gives the descriptions reproduced in
+ *       {@link NZ_DELIVERY_SERVICE_TYPES}, and the identifier rules: "The Delivery Service
+ *       Identifier must have no leading zeros and no spaces, separators or other punctuation"; "The
+ *       Delivery Service Identifier is not used for Counter Delivery or Poste Restante. It is also
+ *       not used for Private Bags that do not have an identifier allocated by New Zealand Post".
+ *       Examples: `PO Box 24999`, `Private Bag 106999`, `Response Bag 500999`, `CMB B99`, `Counter
+ *       Delivery`, `Poste Restante`. The standard's incorrect-form examples show `P O Box 4 099`
+ *       and `PB 39990` as wrong — `PB` is a common error, not a designator, so it is NOT in this
+ *       table.
+ *   - The live addressing-standards page repeats the format rules: "PO Box and Private Bag numbers are
+ *       space-free (eg. 'PO Box 23226', not 'PO Box 23 226')", "'PO' is space-free … and
+ *       punctuation-free".
+ *
+ *   All six types are CURRENT in the October 2021 ADV358 (including CMB — no legacy flag is needed
+ *   for the NZ slice). "Private Box" — a colloquial NZ synonym for a PO Box that the postal arena's
+ *   gold rows carry — does NOT appear in ADV358 or the live standards pages and is therefore
+ *   excluded here (see the issue #517 sourcing note: a smaller sourced list beats a larger guessed
+ *   one).
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ * @see {@link https://www.nzpost.co.nz/business/shipping-in-nz/addressing-standards NZ Post addressing standards}
+ * @see {@link https://www.nzpost.co.nz/personal/sending-in-nz/how-to-address-mail NZ Post — how to address mail}
+ */
+/** Identifier requirement per ADV358's Delivery Service Elements rules. */
+export type NzIdentifierRule = "required-if-allocated" | "optional" | "not-used";
+/** One Delivery Service Type row from ADV358. */
+export interface NzDeliveryServiceType {
+    /** The Delivery Service Type, verbatim casing per ADV358 ("PO Box", "Private Bag", "CMB"). */
+    type: string;
+    /** The ADV358 description, verbatim. */
+    description: string;
+    /**
+     * Identifier rule: PO Box/Response Bag/CMB identifiers are mandatory if allocated; Private Bag
+     * may legitimately have none ("not used … for Private Bags that do not have an identifier
+     * allocated by New Zealand Post"); Counter Delivery and Poste Restante never carry one.
+     */
+    identifier: NzIdentifierRule;
+}
+/** The six Delivery Service Types, verbatim from ADV358 (see the module header). */
+export declare const NZ_DELIVERY_SERVICE_TYPES: readonly [{
+    readonly type: "PO Box";
+    readonly description: "Post Box, PO Box";
+    readonly identifier: "required-if-allocated";
+}, {
+    readonly type: "Private Bag";
+    readonly description: "Private Bag";
+    readonly identifier: "optional";
+}, {
+    readonly type: "Response Bag";
+    readonly description: "Response Bag (used for competitions)";
+    readonly identifier: "required-if-allocated";
+}, {
+    readonly type: "CMB";
+    readonly description: "Community Mail Box in postal outlet or on a thoroughfare";
+    readonly identifier: "required-if-allocated";
+}, {
+    readonly type: "Counter Delivery";
+    readonly description: "Hold for Counter Delivery collection - domestic mail";
+    readonly identifier: "not-used";
+}, {
+    readonly type: "Poste Restante";
+    readonly description: "Hold for Poste Restante collection - international mail";
+    readonly identifier: "not-used";
+}];
+/** A canonical NZ Delivery Service Type. */
+export type NzDeliveryServiceTypeName = (typeof NZ_DELIVERY_SERVICE_TYPES)[number]["type"];
+/** Result of an NZ delivery-service parse. */
+export interface NzDeliveryServiceMatch {
+    /** The designator phrase as it appeared ("PO Box", "private bag"). */
+    matched: string;
+    /** The canonical Delivery Service Type ("PO Box", "Private Bag", "CMB", …). */
+    type: NzDeliveryServiceTypeName;
+    /** The Delivery Service Identifier when present ("24999", "B99"). */
+    id?: string;
+}
+/**
+ * If `input` is a standalone NZ delivery-service phrase ("PO Box 24999", "Private Bag 106999", "CMB
+ * B99", bare "Private Bag", "Counter Delivery"), return the canonical type and identifier. Null
+ * otherwise — including for "PB 39990" (an error of form per ADV358) and "Private Box" (not a
+ * Delivery Service Type).
+ */
+export declare function matchNzDeliveryService(input: unknown): NzDeliveryServiceMatch | null;
+/** Type-predicate: does the input look like a standalone NZ delivery-service address line? */
+export declare function isNzDeliveryService(input: unknown): boolean;
+/**
+ * Normalize a recognized phrase to the ADV358 form (`"p.o. box 24999"` → `"PO Box 24999"`). Returns
+ * the input unchanged if it isn't a delivery-service phrase.
+ */
+export declare function normalizeNzDeliveryService(input: string): string;
+//# sourceMappingURL=delivery-service.d.ts.map

package/out/nz/delivery-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-service.d.ts","sourceRoot":"","sources":["../../nz/delivery-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,uBAAuB,GAAG,UAAU,GAAG,UAAU,CAAA;AAEhF,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACrC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,CAAA;CAC5B;AAED,oFAAoF;AACpF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;EAmBe,CAAA;AAErD,4CAA4C;AAC5C,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AA6B1F,8CAA8C;AAC9C,MAAM,WAAW,sBAAsB;IACtC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,+EAA+E;IAC/E,IAAI,EAAE,yBAAyB,CAAA;IAC/B,qEAAqE;IACrE,EAAE,CAAC,EAAE,MAAM,CAAA;CACX;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,GAAG,IAAI,CAQpF;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE"}

package/out/nz/delivery-service.js

@@ -0,0 +1,110 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   NZ Post delivery-service types — the second half of the Commonwealth po_box vocabulary: `PO Box
+ *   24999`, `Private Bag 106999`, `CMB B99`, plus the identifier-less counter services.
+ *
+ *   Sourcing (accessed 2026-06-11):
+ *
+ *   - NZ Post Address Standards (ADV358, October 2021 edition hosted on nzpost.co.nz) is the
+ *       authoritative document. Verbatim: "The Delivery Service Type is mandatory. It may be PO
+ *       Box, Private Bag, CMB, Response Bag, Counter Delivery or Poste Restante." Its Delivery
+ *       Service Elements table gives the descriptions reproduced in
+ *       {@link NZ_DELIVERY_SERVICE_TYPES}, and the identifier rules: "The Delivery Service
+ *       Identifier must have no leading zeros and no spaces, separators or other punctuation"; "The
+ *       Delivery Service Identifier is not used for Counter Delivery or Poste Restante. It is also
+ *       not used for Private Bags that do not have an identifier allocated by New Zealand Post".
+ *       Examples: `PO Box 24999`, `Private Bag 106999`, `Response Bag 500999`, `CMB B99`, `Counter
+ *       Delivery`, `Poste Restante`. The standard's incorrect-form examples show `P O Box 4 099`
+ *       and `PB 39990` as wrong — `PB` is a common error, not a designator, so it is NOT in this
+ *       table.
+ *   - The live addressing-standards page repeats the format rules: "PO Box and Private Bag numbers are
+ *       space-free (eg. 'PO Box 23226', not 'PO Box 23 226')", "'PO' is space-free … and
+ *       punctuation-free".
+ *
+ *   All six types are CURRENT in the October 2021 ADV358 (including CMB — no legacy flag is needed
+ *   for the NZ slice). "Private Box" — a colloquial NZ synonym for a PO Box that the postal arena's
+ *   gold rows carry — does NOT appear in ADV358 or the live standards pages and is therefore
+ *   excluded here (see the issue #517 sourcing note: a smaller sourced list beats a larger guessed
+ *   one).
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ * @see {@link https://www.nzpost.co.nz/business/shipping-in-nz/addressing-standards NZ Post addressing standards}
+ * @see {@link https://www.nzpost.co.nz/personal/sending-in-nz/how-to-address-mail NZ Post — how to address mail}
+ */
+/** The six Delivery Service Types, verbatim from ADV358 (see the module header). */
+export const NZ_DELIVERY_SERVICE_TYPES = [
+    { type: "PO Box", description: "Post Box, PO Box", identifier: "required-if-allocated" },
+    { type: "Private Bag", description: "Private Bag", identifier: "optional" },
+    { type: "Response Bag", description: "Response Bag (used for competitions)", identifier: "required-if-allocated" },
+    {
+        type: "CMB",
+        description: "Community Mail Box in postal outlet or on a thoroughfare",
+        identifier: "required-if-allocated",
+    },
+    {
+        type: "Counter Delivery",
+        description: "Hold for Counter Delivery collection - domestic mail",
+        identifier: "not-used",
+    },
+    {
+        type: "Poste Restante",
+        description: "Hold for Poste Restante collection - international mail",
+        identifier: "not-used",
+    },
+];
+/**
+ * Per-type surface patterns (designator phrase only). Recognition is deliberately wider than the
+ * prescriptive standard — mail in the wild writes "P.O. Box" even though ADV358 says `PO` is
+ * punctuation-free — but it does NOT admit forms the standard names as errors of TYPE (`PB`) or
+ * types that don't exist ("Private Box").
+ */
+const TYPE_PATTERNS = [
+    ["PO Box", String.raw `p\.?\s*o\.?\s*box|post\s+box`],
+    ["Private Bag", String.raw `private\s+bag`],
+    ["Response Bag", String.raw `response\s+bag`],
+    ["CMB", String.raw `community\s+mail\s+box|cmb`],
+    ["Counter Delivery", String.raw `counter\s+delivery`],
+    ["Poste Restante", String.raw `poste\s+restante`],
+];
+const IDENTIFIER_RULES = new Map(NZ_DELIVERY_SERVICE_TYPES.map((t) => [t.type, t.identifier]));
+// One anchored regex per type. The identifier shape follows ADV358 (alphanumeric, no spaces or
+// separators — `24999`, `B99`); the identifier-less counter services take no tail at all.
+const MATCHERS = TYPE_PATTERNS.map(([type, src]) => {
+    const rule = IDENTIFIER_RULES.get(type);
+    const tail = rule === "not-used" ? "" : String.raw `(?:\s+([\dA-Za-z]+))${rule === "optional" ? "?" : ""}`;
+    return { type, re: new RegExp(String.raw `^\s*(${src})${tail}\s*$`, "i") };
+});
+/**
+ * If `input` is a standalone NZ delivery-service phrase ("PO Box 24999", "Private Bag 106999", "CMB
+ * B99", bare "Private Bag", "Counter Delivery"), return the canonical type and identifier. Null
+ * otherwise — including for "PB 39990" (an error of form per ADV358) and "Private Box" (not a
+ * Delivery Service Type).
+ */
+export function matchNzDeliveryService(input) {
+    if (typeof input !== "string")
+        return null;
+    for (const { type, re } of MATCHERS) {
+        const m = re.exec(input);
+        if (!m)
+            continue;
+        return { matched: m[1].trim(), type, ...(m[2] ? { id: m[2] } : {}) };
+    }
+    return null;
+}
+/** Type-predicate: does the input look like a standalone NZ delivery-service address line? */
+export function isNzDeliveryService(input) {
+    return matchNzDeliveryService(input) !== null;
+}
+/**
+ * Normalize a recognized phrase to the ADV358 form (`"p.o. box 24999"` → `"PO Box 24999"`). Returns
+ * the input unchanged if it isn't a delivery-service phrase.
+ */
+export function normalizeNzDeliveryService(input) {
+    const m = matchNzDeliveryService(input);
+    if (!m)
+        return input;
+    return m.id ? `${m.type} ${m.id.toUpperCase()}` : m.type;
+}
+//# sourceMappingURL=delivery-service.js.map

package/out/nz/delivery-service.js.map

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

package/out/nz/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The New Zealand address system (NZ Post / ISO 3166-2:NZ; ADV358 Address Standards):
+ *   delivery-service types (PO Box, Private Bag, CMB, Response Bag, Counter Delivery, Poste
+ *   Restante) and the 4-digit postcode. NZ addresses carry no state/region line.
+ */
+export * from "./delivery-service.js";
+export * from "./postcode.js";
+//# sourceMappingURL=index.d.ts.map

package/out/nz/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../nz/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,eAAe,CAAA"}

package/out/nz/index.js

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The New Zealand address system (NZ Post / ISO 3166-2:NZ; ADV358 Address Standards):
+ *   delivery-service types (PO Box, Private Bag, CMB, Response Bag, Counter Delivery, Poste
+ *   Restante) and the 4-digit postcode. NZ addresses carry no state/region line.
+ */
+export * from "./delivery-service.js";
+export * from "./postcode.js";
+//# sourceMappingURL=index.js.map

package/out/nz/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../nz/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,uBAAuB,CAAA;AACrC,cAAc,eAAe,CAAA"}

package/out/nz/postcode.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   New Zealand postcodes: four digits, after the town/city on the last line (`Timaru 7942`).
+ *   Verbatim from NZ Post's Address Standards (ADV358, Oct 2021, accessed 2026-06-11): "Postcode is
+ *   mandatory and is four digits. It follows the city or town." Note NZ has no state/region line —
+ *   "The province, region, district or territory is not to be used."
+ *
+ *   The shape collides with Australia's (also 4 digits) — `candidateSystemsForPostcode` returns both,
+ *   by design (shape test, not membership test).
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ */
+import type { Tagged } from "type-fest";
+/**
+ * A New Zealand postcode: four digits.
+ *
+ * @category Postal
+ * @type string
+ * @title New Zealand postcode
+ * @pattern ^\d{4}$
+ */
+export type NzPostcode = Tagged<string, "NzPostcode">;
+/** The NZ postcode shape: exactly four digits. */
+export declare const NZ_POSTCODE_PATTERN: RegExp;
+/** Normalize a postcode surface form (trim only — NZ has no country-prefix courtesy form). */
+export declare function normalizeNzPostcode(raw: unknown): NzPostcode | null;
+/** Type-predicate for a (normalized) New Zealand postcode. */
+export declare function isNzPostcode(input: unknown): input is NzPostcode;
+//# sourceMappingURL=postcode.d.ts.map

package/out/nz/postcode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode.d.ts","sourceRoot":"","sources":["../../nz/postcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAEvC;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAErD,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,QAAY,CAAA;AAE5C,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAInE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

package/out/nz/postcode.js

@@ -0,0 +1,28 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   New Zealand postcodes: four digits, after the town/city on the last line (`Timaru 7942`).
+ *   Verbatim from NZ Post's Address Standards (ADV358, Oct 2021, accessed 2026-06-11): "Postcode is
+ *   mandatory and is four digits. It follows the city or town." Note NZ has no state/region line —
+ *   "The province, region, district or territory is not to be used."
+ *
+ *   The shape collides with Australia's (also 4 digits) — `candidateSystemsForPostcode` returns both,
+ *   by design (shape test, not membership test).
+ * @see {@link https://www.nzpost.co.nz/sites/nz/files/2021-10/adv358-address-standards.pdf NZ Post Address Standards (ADV358, Oct 2021)}
+ */
+/** The NZ postcode shape: exactly four digits. */
+export const NZ_POSTCODE_PATTERN = /^\d{4}$/;
+/** Normalize a postcode surface form (trim only — NZ has no country-prefix courtesy form). */
+export function normalizeNzPostcode(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const s = raw.trim();
+    return NZ_POSTCODE_PATTERN.test(s) ? s : null;
+}
+/** Type-predicate for a (normalized) New Zealand postcode. */
+export function isNzPostcode(input) {
+    return typeof input === "string" && NZ_POSTCODE_PATTERN.test(input);
+}
+//# sourceMappingURL=postcode.js.map

package/out/nz/postcode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postcode.js","sourceRoot":"","sources":["../../nz/postcode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH,kDAAkD;AAClD,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAA;AAE5C,8FAA8F;AAC9F,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC/C,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACxC,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,EAAE,CAAA;IACpB,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAgB,CAAC,CAAC,CAAC,IAAI,CAAA;AAC9D,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACpE,CAAC"}

package/out/postcode-systems.d.ts

@@ -21,7 +21,7 @@
  *   for".
  */
 /** A codex address-system code — the subpath under `@mailwoman/codex/<system>`. */
-export type SystemCode = "us" | "de" | "fr" | "ca" | "gb" | "jp";
+export type SystemCode = "us" | "de" | "fr" | "ca" | "gb" | "jp" | "au" | "nz";
 /**
  * Every address system whose own postcode shape accepts `postcode`. Empty when no system recognizes
  * the shape (e.g. a bare `27`, or a 7-digit run). O(number of systems) — a handful of cheap regex

package/out/postcode-systems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postcode-systems.d.ts","sourceRoot":"","sources":["../postcode-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AASH,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAiBhE;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAO1E"}
+{"version":3,"file":"postcode-systems.d.ts","sourceRoot":"","sources":["../postcode-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAmB9E;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CAO1E"}

package/out/postcode-systems.js

@@ -20,11 +20,13 @@
  *   call; this function answers the coarser, model-free "which systems is this shape even eligible
  *   for".
  */
+import { normalizeAuPostcode } from "./au/index.js";
 import { normalizeCaPostalCode } from "./ca/index.js";
 import { normalizePLZ } from "./de/index.js";
 import { normalizeCodePostal } from "./fr/index.js";
 import { normalizeUkPostcode } from "./gb/index.js";
 import { normalizeJpPostalCode } from "./jp/index.js";
+import { normalizeNzPostcode } from "./nz/index.js";
 import { isZipCode } from "./us/index.js";
 /**
  * Per-system membership test: each entry returns true when the string is accepted by that system's
@@ -39,6 +41,8 @@ const SYSTEM_ACCEPTS = [
     ["ca", (s) => normalizeCaPostalCode(s) !== null],
     ["gb", (s) => normalizeUkPostcode(s) !== null],
     ["jp", (s) => normalizeJpPostalCode(s) !== null],
+    ["au", (s) => normalizeAuPostcode(s) !== null],
+    ["nz", (s) => normalizeNzPostcode(s) !== null],
 ];
 /**
  * Every address system whose own postcode shape accepts `postcode`. Empty when no system recognizes

package/out/postcode-systems.js.map

@@ -1 +1 @@
-{"version":3,"file":"postcode-systems.js","sourceRoot":"","sources":["../postcode-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAKzC;;;;;GAKG;AACH,MAAM,cAAc,GAAiE;IACpF,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACvC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAChD,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAChD,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAgB;IAC3D,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACpE,MAAM,GAAG,GAAiB,EAAE,CAAA;IAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,cAAc,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC"}
+{"version":3,"file":"postcode-systems.js","sourceRoot":"","sources":["../postcode-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAKzC;;;;;GAKG;AACH,MAAM,cAAc,GAAiE;IACpF,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACvC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAChD,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAChD,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC9C,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC9C,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,QAAgB;IAC3D,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACpE,MAAM,GAAG,GAAiB,EAAE,CAAA;IAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,cAAc,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC"}

package/out/us/floor-designator.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C2 — Floor-class Secondary Unit Designators.
+ *
+ *   The sibling of {@link ./unit-designator.ts}: where the unit table covers the full secondary-unit
+ *   vocabulary (APT, STE, RM, …), this module extracts the floor-class subset — designators that
+ *   name a FLOOR or LEVEL of the building rather than a specific addressable unit on that floor.
+ *   USPS Pub 28 Appendix C2 identifies these designators as requiring a secondary number: "FL" (the
+ *   approved abbreviation for FLOOR). The publication gives `FLOOR` as the canonical designator
+ *   with approved abbreviation `FL` and variant `FLR`; `BASEMENT` (`BSMT`), `PENTHOUSE` (`PH`), and
+ *   `LOBBY` (`LBBY`) are the standalone-or-numbered floor-adjacent types also listed in Appendix
+ *   C2.
+ *
+ *   Appendix C2 explicitly marks FLOOR, BASEMENT as requiring a secondary number (alongside APT,
+ *   BLDG, etc.) while PENTHOUSE and LOBBY may stand alone. PH and LBBY are kept here (not just in
+ *   {@link ./unit-designator.ts}) because the span proposer treats them as level-class hints —
+ *   "LOBBY" and "PH" name a specific floor-analog, not a numbered unit, and the prior map routes
+ *   `LEVEL_PHRASE` → `unit` (the schema carries no separate `level` tag).
+ *
+ *   This table drives the `levelDesignators` set in the span-proposer lexicon. The full
+ *   secondary-unit designators (APT, STE, RM, …) remain in {@link ./unit-designator.ts}.
+ *
+ *   Data is verbatim USPS Pub 28 Appendix C2.
+ * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Publication 28 — Appendix C2: Secondary Unit Designators}
+ */
+/**
+ * One USPS Pub 28 C2 floor-class designator row.
+ *
+ * `requiresNumber` mirrors the Appendix C2 classification: FLOOR and BASEMENT must be followed by a
+ * secondary number; PENTHOUSE and LOBBY may stand alone.
+ */
+export interface UsFloorDesignator {
+    /** Full canonical designator (uppercase per the publication). */
+    name: string;
+    /** Approved USPS abbreviation (what the post office prints on standardized mail). */
+    abbreviation: string;
+    /** Additional recognized surface variants from Appendix C2. */
+    variants: readonly string[];
+    /**
+     * True when Appendix C2 marks this designator as "Requires a Secondary Number" (FLOOR, BASEMENT).
+     * False for standalone types (PENTHOUSE, LOBBY) that name a specific floor-analog without an
+     * identifier.
+     */
+    requiresNumber: boolean;
+}
+/**
+ * USPS Pub 28 C2 floor-class secondary unit designators. Verbatim from the publication; see the
+ * module header for the per-row provenance. Ordered with the most-common numbered form first.
+ */
+export declare const US_FLOOR_DESIGNATORS: readonly [{
+    readonly name: "FLOOR";
+    readonly abbreviation: "FL";
+    readonly variants: readonly ["FLR"];
+    readonly requiresNumber: true;
+}, {
+    readonly name: "BASEMENT";
+    readonly abbreviation: "BSMT";
+    readonly variants: readonly [];
+    readonly requiresNumber: true;
+}, {
+    readonly name: "PENTHOUSE";
+    readonly abbreviation: "PH";
+    readonly variants: readonly [];
+    readonly requiresNumber: false;
+}, {
+    readonly name: "LOBBY";
+    readonly abbreviation: "LBBY";
+    readonly variants: readonly [];
+    readonly requiresNumber: false;
+}];
+/** A canonical USPS floor-class designator name. */
+export type UsFloorDesignatorName = (typeof US_FLOOR_DESIGNATORS)[number]["name"];
+/**
+ * Inverse lookup: every surface form (canonical name, approved abbreviation, or Appendix C2
+ * variant) → its canonical designator name. Lowercase-keyed for case-insensitive matching: `"fl"` →
+ * `"FLOOR"`, `"bsmt"` → `"BASEMENT"`, `"ph"` → `"PENTHOUSE"`.
+ */
+export declare const US_FLOOR_DESIGNATOR_LOOKUP: ReadonlyMap<string, UsFloorDesignatorName>;
+/**
+ * All lowercase surface tokens for the floor-class designators — the set the span proposer
+ * populates `levelDesignators` with when wiring the US codex slice. Includes canonical names,
+ * approved abbreviations, and Appendix C2 variants.
+ */
+export declare const US_FLOOR_DESIGNATOR_TOKENS: ReadonlySet<string>;
+/** Approved USPS abbreviation per canonical floor designator name. */
+export declare const US_FLOOR_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<UsFloorDesignatorName, string>>;
+/**
+ * Look up a USPS floor-class designator (by canonical name, abbreviation, or any Appendix C2
+ * variant) and return the canonical name + approved abbreviation. Returns null if the token isn't a
+ * recognized floor-class designator.
+ */
+export declare function lookupFloorDesignator(input: string | null | undefined): {
+    designator: UsFloorDesignatorName;
+    abbreviation: string;
+} | null;
+/**
+ * True when a token is a recognized USPS floor-class secondary unit designator (case-insensitive) —
+ * `"Floor"`, `"FL"`, `"flr"`, `"bsmt"`, `"ph"`, `"lbby"`.
+ */
+export declare function isFloorDesignatorToken(input: unknown): boolean;
+//# sourceMappingURL=floor-designator.d.ts.map

package/out/us/floor-designator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floor-designator.d.ts","sourceRoot":"","sources":["../../us/floor-designator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IACjC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,YAAY,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B;;;;OAIG;IACH,cAAc,EAAE,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;EAKgB,CAAA;AAEjD,oDAAoD;AACpD,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,CAU9E,CAAA;AAEJ;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAA8C,CAAA;AAEzG,sEAAsE;AACtE,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAE3C,CAAA;AAEpD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG;IACxE,UAAU,EAAE,qBAAqB,CAAA;IACjC,YAAY,EAAE,MAAM,CAAA;CACpB,GAAG,IAAI,CAKP;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D"}