universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/places/facilities.json

@@ -0,0 +1,11 @@
+[
+  { "country": "CH", "code": "801050", "town": "Zürich", "name": "Zürich-Mülligen", "latitude": 47.3959, "longitude": 8.4695, "source": "https://www.openstreetmap.org/way/24055904" },
+  { "country": "CH", "code": "801053", "town": "Zürich", "name": "Zürich-Mülligen", "latitude": 47.3959, "longitude": 8.4695, "source": "https://www.openstreetmap.org/way/24055904" },
+  { "country": "CH", "code": "800473", "town": "Zürich", "name": "Zürich Sihlpost", "latitude": 47.3773, "longitude": 8.5353, "source": "https://www.openstreetmap.org/way/36927540" },
+  { "country": "CH", "code": "892000", "town": "Urdorf", "name": "Urdorf", "latitude": 47.3676, "longitude": 8.4276, "source": "https://www.openstreetmap.org/way/38934280" },
+  { "country": "CH", "code": "852000", "town": "Frauenfeld", "name": "Frauenfeld", "latitude": 47.5716, "longitude": 8.9173, "source": "https://www.openstreetmap.org/way/46882390" },
+  { "country": "CH", "code": "462000", "town": "Härkingen", "name": "Härkingen", "latitude": 47.3163, "longitude": 7.8084, "source": "https://www.openstreetmap.org/node/11139998177" },
+  { "country": "CH", "code": "462150", "town": "Härkingen", "name": "Härkingen", "latitude": 47.3192, "longitude": 7.8155, "source": "https://www.openstreetmap.org/node/11139998178" },
+  { "country": "CH", "code": "131000", "town": "Daillens", "name": "Daillens", "latitude": 46.6327, "longitude": 6.541, "source": "https://www.openstreetmap.org/way/112072584" },
+  { "country": "CH", "code": "659100", "town": "Cadenazzo", "name": "Cadenazzo", "latitude": 46.1552, "longitude": 8.9417, "source": "https://www.openstreetmap.org/way/1121092808" }
+]

package/dist/places/index.d.ts

@@ -0,0 +1,42 @@
+/** Where a scan happened, as precisely as its free-text location allows. */
+export interface EventPlace {
+    latitude: number;
+    longitude: number;
+    precision: 'city' | 'country';
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    name: string;
+    /** The facility name, when distinct from the town. */
+    site?: string;
+}
+/** Where a carrier itself puts a scan's facility (`point` on a stored scan). */
+export interface EventPoint {
+    latitude: number;
+    longitude: number;
+}
+export interface PlaceHints {
+    /** Countries the parcel is likely in, strongest first: neighbouring scans, destination, carrier. */
+    countries?: readonly string[];
+}
+/** Loads the gazetteer ahead of the first request that needs it. */
+export declare function preloadPlaces(): void;
+/**
+ * Turns one carrier location ("ZUERICH, CH", "Härkingen 4622", "Agence DPD de
+ * La Crau (283)", "Germany") into a place, or null when the text names no
+ * place we can be confident about. A wrong dot is worse than no dot.
+ */
+export declare function locatePlace(location: string | null | undefined, hints?: PlaceHints): EventPlace | null;
+/**
+ * Places for a parcel's scans, oldest first. A scan that names no country
+ * borrows one from the scans around it, then the destination and the
+ * carrier's home countries, so "Buchs" after "Zürich" stays in Switzerland.
+ * A carrier's own point for a scan, or for another scan with the same text,
+ * moves it from the town's centre to the facility, if the two are within
+ * 30 km of each other.
+ */
+export declare function placesForEvents(locations: readonly (string | null | undefined)[], { destinationCountry, carrierCountries, points }?: {
+    destinationCountry?: string | null;
+    carrierCountries?: readonly string[];
+    /** The carrier's own point for each scan, where it gave one. */
+    points?: readonly (EventPoint | null | undefined)[];
+}): (EventPlace | null)[];

package/dist/places/index.js

@@ -0,0 +1,307 @@
+import { readFileSync } from 'node:fs';
+import { brotliDecompressSync } from 'node:zlib';
+import { ambiguousAddressCodes, trackingPlace } from './trackingLocation.js';
+import facilityList from './facilities.json' with { type: 'json' };
+import { nameKey, nameKeys } from './names.mjs';
+const DATA = new URL('./places.tsv.br', import.meta.url);
+// Words for facilities and services rather than places ("Agence DPD de La Crau", "PAKETZENTRUM").
+const FACILITY_WORDS = new Set(`
+  agence agency air airport area branch bureau cedex cidex center centre centro centrum clasificacion colis
+  customs delivery depot deposito destination distribution distribuicao dogana douane export facility filiale
+  gateway hub import international intl livraison local location logistics logistik mail oddzial office oficina
+  operations operativo origin paketzentrum briefzentrum verteilzentrum sortierzentrum zustellbasis zustellstelle
+  parcel parcels plateforme platform point postal postfiliale postfach poste pz bz return service services site
+  smistamento sort sorting station terminal tratamento tri unidade ufficio warehouse zentrum zoll zollamt
+  dhl ups fedex gls dpd tnt usps colissimo chronopost postnl bpost evri hermes cainiao yanwen parcelforce
+  planzer quickpac amazon express post home house address recipient sender neighbourhood neighborhood unknown
+`.trim().split(/\s+/));
+const LEADING_WORDS = new Set(['de', 'du', 'des', 'di', 'da', 'del', 'della', 'von', 'of']);
+// Carriers print provinces the way the post does; GeoNames numbers them.
+const ADMIN_CODES = {
+    CA: { AB: '01', BC: '02', MB: '03', NB: '04', NL: '05', NS: '07', ON: '08', PE: '09', QC: '10', SK: '11', YT: '12', NT: '13', NU: '14' },
+    AU: { ACT: '01', NSW: '02', NT: '03', QLD: '04', SA: '05', TAS: '06', VIC: '07', WA: '08' },
+    BR: {
+        AC: '01', AL: '02', AP: '03', AM: '04', BA: '05', CE: '06', DF: '07', ES: '08', MS: '11', MA: '13', MT: '14', MG: '15',
+        PA: '16', PB: '17', PR: '18', PI: '20', RJ: '21', RN: '22', RS: '23', RO: '24', RR: '25', SC: '26', SP: '27', SE: '28',
+        GO: '29', PE: '30', TO: '31',
+    },
+};
+// A place nothing else confirms has to be a known town, not a hamlet with the same name.
+const UNCONFIRMED_MIN_THOUSANDS = 15;
+// A carrier's own point for a scan has to agree with the town its text names.
+const POINT_MAX_KM = 30;
+// Swiss Post scans end in the site's six-digit number: "Zürich Briefzentrum 801050".
+const FACILITIES = new Map(facilityList.map((facility) => [`${facility.country}:${facility.code}`, facility]));
+let loaded = null;
+function gazetteer() {
+    if (loaded)
+        return loaded;
+    // Parsed straight from bytes: substrings of one decompressed string would keep all 10 MB of it alive.
+    const bytes = brotliDecompressSync(readFileSync(DATA));
+    const rows = [];
+    for (let start = 0; start < bytes.length;) {
+        let end = bytes.indexOf(10, start);
+        if (end < 0)
+            end = bytes.length;
+        const fields = [];
+        for (let field = start; field <= end;) {
+            let stop = bytes.indexOf(9, field);
+            if (stop < 0 || stop > end)
+                stop = end;
+            fields.push(bytes.toString('utf8', field, stop));
+            field = stop + 1;
+        }
+        rows.push(fields);
+        start = end + 1;
+    }
+    const count = rows.filter((fields) => fields[0] === 'P').length;
+    const data = {
+        names: [], codes: [],
+        country: new Uint16Array(count), admin1: new Uint16Array(count), admin2: new Uint16Array(count),
+        latitude: new Float32Array(count), longitude: new Float32Array(count), population: new Uint32Array(count),
+        keys: new Map(), postcodes: new Map(), countries: new Map(),
+    };
+    const codeIndex = new Map();
+    const code = (value) => {
+        let index = codeIndex.get(value);
+        if (index === undefined) {
+            index = data.codes.push(value) - 1;
+            codeIndex.set(value, index);
+        }
+        return index;
+    };
+    const add = (key, entry) => {
+        const existing = data.keys.get(key);
+        if (existing === undefined)
+            data.keys.set(key, entry);
+        else if (typeof existing === 'number') {
+            if (existing !== entry)
+                data.keys.set(key, [existing, entry]);
+        }
+        else if (!existing.includes(entry))
+            existing.push(entry);
+    };
+    let index = 0;
+    for (const fields of rows) {
+        if (fields[0] === 'P') {
+            const [, name, ascii, country, admin1, admin2, latitude, longitude, population, alternates] = fields;
+            data.names.push(name);
+            data.country[index] = code(country);
+            data.admin1[index] = code(admin1);
+            data.admin2[index] = code(admin2);
+            data.latitude[index] = Number(latitude);
+            data.longitude[index] = Number(longitude);
+            data.population[index] = Number(population);
+            for (const key of [...nameKeys(name), ...(ascii ? nameKeys(ascii) : [])])
+                add(key, index);
+            for (const key of alternates ? alternates.split(',') : [])
+                add(key, ~index);
+            index += 1;
+        }
+        else if (fields[0] === 'Z') {
+            const [, country, postcode, latitude, longitude] = fields;
+            data.postcodes.set(`${country}:${postcode}`, { latitude: Number(latitude), longitude: Number(longitude) });
+        }
+        else if (fields[0] === 'C') {
+            const [, country, name, longitude, latitude] = fields;
+            data.countries.set(country, { name, latitude: Number(latitude), longitude: Number(longitude) });
+        }
+    }
+    loaded = data;
+    return data;
+}
+/** Loads the gazetteer ahead of the first request that needs it. */
+export function preloadPlaces() {
+    gazetteer();
+}
+function distanceKm(latitude1, longitude1, latitude2, longitude2) {
+    const radians = Math.PI / 180;
+    const a = Math.sin((latitude2 - latitude1) * radians / 2) ** 2
+        + Math.cos(latitude1 * radians) * Math.cos(latitude2 * radians) * Math.sin((longitude2 - longitude1) * radians / 2) ** 2;
+    return 12742 * Math.asin(Math.sqrt(a));
+}
+function tokens(text) {
+    return [...text.matchAll(/[\p{L}\p{N}]+/gu)].flatMap((match) => {
+        // "BARCELONA2": a depot number glued to the town.
+        const word = /\p{L}/u.test(match[0]) ? match[0].replace(/\d+$/u, '') : match[0];
+        const key = nameKey(word);
+        return key ? [{ key, start: match.index, end: match.index + word.length }] : [];
+    });
+}
+/** Phrases worth looking up, most specific first: "zurich mulligen", then "zurich". */
+function phrases(field) {
+    const all = tokens(field).filter((token) => !/^\d+$/.test(token.key));
+    const found = [];
+    const add = (list, rank) => {
+        if (!list.length)
+            return;
+        const key = list.map((token) => token.key).join(' ');
+        if (key.length >= 3 && !found.some((phrase) => phrase.key === key)) {
+            found.push({ key, text: field.slice(list[0].start, list.at(-1).end), rank });
+        }
+    };
+    add(all, 0);
+    let words = all.filter((token) => !FACILITY_WORDS.has(token.key));
+    while (words.length && LEADING_WORDS.has(words[0].key))
+        words = words.slice(1);
+    for (let count = words.length; count > 0; count -= 1)
+        add(words.slice(0, count), words.length - count + 1);
+    for (let start = 1; start < words.length; start += 1)
+        add(words.slice(start), words.length + start);
+    return found;
+}
+const candidate = (entry) => ({ index: entry < 0 ? ~entry : entry, alternate: entry < 0 });
+/**
+ * Turns one carrier location ("ZUERICH, CH", "Härkingen 4622", "Agence DPD de
+ * La Crau (283)", "Germany") into a place, or null when the text names no
+ * place we can be confident about. A wrong dot is worse than no dot.
+ */
+export function locatePlace(location, hints = {}) {
+    const text = location?.trim();
+    if (!text)
+        return null;
+    const facility = facilityPlace(text);
+    if (facility)
+        return facility;
+    const data = gazetteer();
+    const explicit = trackingPlace(text);
+    let country = explicit.country && data.countries.has(explicit.country) ? explicit.country : null;
+    let rest = explicit.country ? explicit.place : text;
+    const hinted = [...(hints.countries ?? [])];
+    const admin = [];
+    const postcodes = [];
+    // A trailing code without a comma ("ZUERICH CH"), or one that is also a state
+    // or canton ("KOELN, DE", "Buchs SG"): a hint either way.
+    const trailing = /[\s,;]+([A-Z]{2})$/.exec(rest)?.[1];
+    if (!country && trailing && data.countries.has(trailing)) {
+        rest = rest.slice(0, -trailing.length).replace(/[\s,;]+$/, '');
+        hinted.unshift(trailing);
+        admin.push(trailing);
+        if (!/,|;/.test(text.slice(0, -trailing.length)) && !ambiguousAddressCodes.has(trailing))
+            country = trailing;
+    }
+    for (const match of rest.matchAll(/\b([A-Z]{2,3})\b/g))
+        admin.push(match[1]);
+    for (const match of rest.matchAll(/(?:\b[A-Z]{1,2}-)?\b(\d{4,5})\b/g))
+        postcodes.push(match[1]);
+    // French departments and Italian provinces in brackets: "Sausheim 68 (68)", "Cologne (BS)".
+    for (const match of rest.matchAll(/\((\d{2}|[A-Z]{2})\)|(?:^|\s)(\d{2})(?=\s|$)/g))
+        admin.push(match[1] ?? match[2]);
+    // Postcodes only confirm a name, and only in a country the scan or the parcel
+    // names: on its own, "2024" is more likely a year than a village.
+    const countries = country ? [country] : hinted;
+    let postcode = null;
+    for (const code of postcodes) {
+        for (const candidateCountry of countries) {
+            const entry = data.postcodes.get(`${candidateCountry}:${code}`);
+            if (entry) {
+                postcode = { ...entry, country: candidateCountry };
+                break;
+            }
+        }
+        if (postcode)
+            break;
+    }
+    let best = null;
+    const fields = rest.split(/[,;|()]|\s+-\s+/).map((field) => field.trim()).filter(Boolean);
+    for (const [fieldIndex, field] of fields.entries()) {
+        for (const phrase of phrases(field)) {
+            for (const entry of [data.keys.get(phrase.key) ?? []].flat()) {
+                const { index, alternate } = candidate(entry);
+                const placeCountry = data.codes[data.country[index]];
+                if (country && placeCountry !== country)
+                    continue;
+                const hint = hinted.indexOf(placeCountry);
+                const admin1 = data.codes[data.admin1[index]];
+                const adminCodes = [admin1, data.codes[data.admin2[index]]].filter(Boolean);
+                const adminMatch = admin.some((code) => adminCodes.includes(code) || ADMIN_CODES[placeCountry]?.[code] === admin1);
+                const postcodeMatch = postcode !== null && postcode.country === placeCountry
+                    && distanceKm(postcode.latitude, postcode.longitude, data.latitude[index], data.longitude[index]) < 30;
+                const confirmed = Boolean(country) || hint >= 0 || adminMatch || postcodeMatch;
+                const thousands = data.population[index];
+                if (!confirmed && thousands < UNCONFIRMED_MIN_THOUSANDS)
+                    continue;
+                const score = Math.log10(Math.max(thousands, .3) * 1000)
+                    + (alternate ? 0 : 1.8)
+                    + (country ? 4 : hint >= 0 ? 2.5 - Math.min(hint, 3) * .4 : 0)
+                    + (adminMatch ? 3 : 0) + (postcodeMatch ? 3 : 0)
+                    - phrase.rank * .3 - fieldIndex * .5;
+                if (!best || score > best.score)
+                    best = { index, score, text: phrase.text };
+            }
+        }
+    }
+    if (best) {
+        const { index, text: written } = best;
+        return {
+            latitude: round(data.latitude[index]),
+            longitude: round(data.longitude[index]),
+            precision: 'city',
+            country: data.codes[data.country[index]],
+            // Keep the carrier's spelling unless it is shouting: "La Crau", but "Köln" for "KOELN".
+            name: /\p{Ll}/u.test(written) ? written : data.names[index],
+        };
+    }
+    const area = country ? data.countries.get(country) : null;
+    return area && country ? { latitude: area.latitude, longitude: area.longitude, precision: 'country', country, name: area.name } : null;
+}
+const round = (value) => Math.round(value * 1000) / 1000;
+/** A sorting centre the table knows, by its number and the town its name starts with. */
+function facilityPlace(text) {
+    const match = /^(.*\S)\s+(\d{6})$/.exec(text);
+    const facility = match && FACILITIES.get(`CH:${match[2]}`);
+    if (!facility || !`${nameKey(match[1])} `.startsWith(`${nameKey(facility.town)} `))
+        return null;
+    const { latitude, longitude, country, town, name } = facility;
+    return { latitude, longitude, precision: 'city', country, name: town, ...(name === town ? {} : { site: name }) };
+}
+/** The carrier's own point in place of the town's centre, when the two agree. */
+function atPoint(place, point) {
+    if (!place || !point || place.precision !== 'city')
+        return place;
+    if (distanceKm(place.latitude, place.longitude, point.latitude, point.longitude) > POINT_MAX_KM)
+        return place;
+    return { ...place, latitude: point.latitude, longitude: point.longitude };
+}
+const cache = new Map();
+const CACHE_SIZE = 20_000;
+function cachedPlace(location, countries) {
+    const key = `${countries.join(',')}|${location ?? ''}`;
+    if (cache.has(key))
+        return cache.get(key);
+    const place = locatePlace(location, { countries });
+    if (cache.size >= CACHE_SIZE)
+        cache.clear();
+    cache.set(key, place);
+    return place;
+}
+/**
+ * Places for a parcel's scans, oldest first. A scan that names no country
+ * borrows one from the scans around it, then the destination and the
+ * carrier's home countries, so "Buchs" after "Zürich" stays in Switzerland.
+ * A carrier's own point for a scan, or for another scan with the same text,
+ * moves it from the town's centre to the facility, if the two are within
+ * 30 km of each other.
+ */
+export function placesForEvents(locations, { destinationCountry, carrierCountries = [], points = [] } = {}) {
+    const base = [...new Set([destinationCountry, ...carrierCountries].filter((code) => Boolean(code)))];
+    const first = locations.map((location) => cachedPlace(location, base));
+    // A carrier can place some scans of an office and not others: they all share it.
+    const pointAt = new Map();
+    locations.forEach((location, index) => {
+        const point = points[index];
+        if (location && point && !pointAt.has(location.trim()))
+            pointAt.set(location.trim(), point);
+    });
+    return locations.map((location, index) => {
+        if (!location?.trim())
+            return null;
+        const before = first.slice(0, index).reverse().find(Boolean)?.country;
+        const after = first.slice(index + 1).find(Boolean)?.country;
+        const neighbours = [...new Set([before, after].filter((code) => Boolean(code)))];
+        const place = !neighbours.length || neighbours.every((code) => base.includes(code))
+            ? first[index]
+            : cachedPlace(location, [...neighbours, ...base.filter((code) => !neighbours.includes(code))]) ?? first[index];
+        return atPoint(place, points[index] ?? pointAt.get(location.trim()));
+    });
+}

package/dist/places/names.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Lower case, no accents, words separated by single spaces:
+ * "Zürich" and "ZURICH" both become "zurich", "St. Gallen" becomes "st gallen".
+ * @param {string} name
+ * @returns {string}
+ */
+export function nameKey(name: string): string;
+/**
+ * Every key a name answers to, including the German transliteration carriers
+ * print in capitals ("ZUERICH", "KOELN") and each half of a bilingual name
+ * ("Biel/Bienne").
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function nameKeys(name: string): string[];

package/dist/places/names.mjs

@@ -0,0 +1,36 @@
+// Place-name keys shared by the gazetteer generator and the server lookup, so
+// both sides spell every name the same way. Plain JavaScript on purpose: the
+// generator runs in Node without a TypeScript build.
+
+const letters = { ß: 'ss', æ: 'ae', Æ: 'ae', ø: 'o', Ø: 'o', œ: 'oe', Œ: 'oe', ł: 'l', Ł: 'l', đ: 'd', Đ: 'd', ı: 'i', þ: 'th', ð: 'd' };
+const german = { ä: 'ae', ö: 'oe', ü: 'ue', Ä: 'ae', Ö: 'oe', Ü: 'ue' };
+
+/**
+ * Lower case, no accents, words separated by single spaces:
+ * "Zürich" and "ZURICH" both become "zurich", "St. Gallen" becomes "st gallen".
+ * @param {string} name
+ * @returns {string}
+ */
+export function nameKey(name) {
+  return name
+    .replace(/[ßæÆøØœŒłŁđĐıþð]/g, (letter) => letters[/** @type {keyof typeof letters} */ (letter)])
+    .normalize('NFD')
+    .replace(/\p{Mn}/gu, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+/**
+ * Every key a name answers to, including the German transliteration carriers
+ * print in capitals ("ZUERICH", "KOELN") and each half of a bilingual name
+ * ("Biel/Bienne").
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function nameKeys(name) {
+  const keys = new Set([nameKey(name), nameKey(name.replace(/[äöüÄÖÜ]/g, (letter) => german[/** @type {keyof typeof german} */ (letter)]))]);
+  if (name.includes('/')) for (const part of name.split('/')) keys.add(nameKey(part));
+  keys.delete('');
+  return [...keys];
+}

package/dist/places/trackingLocation.d.ts

@@ -0,0 +1,18 @@
+/** Country codes that are also states or cantons ("Hebron, KY", "Buchs AG"), so a bare one is not a country. */
+export declare const ambiguousAddressCodes: ReadonlySet<string>;
+/** Passport evidence: only an explicit final country field; never a country inferred from a city. */
+export declare function trackingLocationCountry(location?: string): string | null;
+export interface TrackingPlace {
+    /** The country the carrier wrote, as an ISO 3166-1 alpha-2 code. */
+    country: string | null;
+    /** The rest of the location; empty when the country was all of it. */
+    place: string;
+}
+/**
+ * For display, take an explicit country off a location: the final field ("Zürich, CH",
+ * repeated in "Hebron, KY, US, US") or a leading name ("Switzerland Haerkingen").
+ */
+export declare function trackingPlace(location: string): TrackingPlace;
+export declare function countryFlag(code: string): string;
+/** The region's name, with the short "Hong Kong" and "Macao" iOS also uses. */
+export declare function countryName(code: string, languageTag: string): string;

package/dist/places/trackingLocation.js

@@ -0,0 +1,89 @@
+const regionCodes = new Set('AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI FJ FK FM FO FR GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY HK HM HN HR HT HU ID IE IL IM IN IO IQ IR IS IT JE JM JO JP KE KG KH KI KM KN KP KR KW KY KZ LA LB LC LI LK LR LS LT LU LV LY MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NR NU NZ OM PA PE PF PG PH PK PL PM PN PR PS PT PW PY QA RE RO RS RU RW SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ UA UG UM US UY UZ VA VC VE VG VI VN VU WF WS YE YT ZA ZM ZW'.split(' '));
+/** Country codes that are also states or cantons ("Hebron, KY", "Buchs AG"), so a bare one is not a country. */
+export const ambiguousAddressCodes = new Set('AL AZ AR CA CO DE GA ID IL IN KY LA ME MD MA MN MS MO MT NE NC PA SC SD TN VA AG AI BE BL BS FR GE GL GR LU SG SH SO SZ TG NL NU PE SK YT SA'.split(' '));
+// Carrier spellings no region name matches. Display only: Passport evidence
+// stays in step with private.passport_country, which Friends stamps use.
+const carrierSpellings = new Map([
+    ['united states of america', 'US'], ['great britain', 'GB'], ['czech republic', 'CZ'], ['holland', 'NL'],
+    ['hong kong', 'HK'], ['macau', 'MO'], ['macao', 'MO'], ['turkey', 'TR'], ['russian federation', 'RU'],
+    ['korea', 'KR'], ['republic of korea', 'KR'],
+]);
+// Apple's ICU (Safari, iOS) calls CN "China mainland" in every language; carriers write "China".
+const chinaNames = new Map([['en', 'China'], ['de', 'China'], ['fr', 'Chine'], ['it', 'Cina'], ['es', 'China'], ['pt', 'China'], ['pl', 'Chiny']]);
+// "Mexico City" is a city, not Mexico followed by one.
+const settlementWords = new Set(['city', 'town', 'ville', 'stadt', 'ciudad', 'cidade', 'citta']);
+const normalized = (value) => value.trim().normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase();
+let countryNames;
+const displayNames = new Map();
+function namedCountry(name, display) {
+    if (!countryNames) {
+        countryNames = new Map([['usa', 'US'], ['uk', 'GB']]);
+        for (const language of ['en', 'de', 'fr', 'it', 'es', 'pt', 'pl']) {
+            const names = new Intl.DisplayNames([language], { type: 'region' });
+            for (const code of regionCodes)
+                countryNames.set(normalized(names.of(code) ?? code), code);
+        }
+        for (const name of chinaNames.values())
+            countryNames.set(normalized(name), 'CN');
+    }
+    const key = normalized(name);
+    const code = countryNames.get(key);
+    if (code || !display)
+        return code ?? null;
+    const bare = key.replace(/^the /, '');
+    return countryNames.get(bare) ?? carrierSpellings.get(bare) ?? null;
+}
+function fieldCountry(field, location, display) {
+    if (regionCodes.has(field))
+        return location === field || !ambiguousAddressCodes.has(field) ? field : null;
+    return namedCountry(field, display);
+}
+/** Passport evidence: only an explicit final country field; never a country inferred from a city. */
+export function trackingLocationCountry(location) {
+    const text = location?.trim();
+    const field = text?.split(/[,;|()]/).map((value) => value.trim()).filter(Boolean).at(-1);
+    return field ? fieldCountry(field, text, false) : null;
+}
+/**
+ * For display, take an explicit country off a location: the final field ("Zürich, CH",
+ * repeated in "Hebron, KY, US, US") or a leading name ("Switzerland Haerkingen").
+ */
+export function trackingPlace(location) {
+    const text = location.trim();
+    const fields = [...text.matchAll(/[^,;|()]+/g)].filter((match) => match[0].trim());
+    let country = null;
+    let kept = fields.length;
+    while (kept > 0) {
+        const code = fieldCountry(fields[kept - 1][0].trim(), text, true);
+        if (!code || (country && code !== country))
+            break;
+        country = code;
+        kept -= 1;
+    }
+    if (country)
+        return { country, place: kept ? text.slice(0, fields[kept].index).replace(/[\s,;|(]+$/u, '') : '' };
+    if (fields.length === 1 && text === fields[0][0]) {
+        const words = text.split(/\s+/);
+        for (let count = Math.min(words.length - 1, 4); count > 0; count -= 1) {
+            const code = namedCountry(words.slice(0, count).join(' '), true);
+            const place = words.slice(count).join(' ');
+            if (code && /^\p{Lu}/u.test(place) && !settlementWords.has(normalized(place)))
+                return { country: code, place };
+        }
+    }
+    return { country: null, place: text };
+}
+export function countryFlag(code) {
+    return [...code].map((letter) => String.fromCodePoint(letter.charCodeAt(0) + 127397)).join('');
+}
+/** The region's name, with the short "Hong Kong" and "Macao" iOS also uses. */
+export function countryName(code, languageTag) {
+    const china = code === 'CN' ? chinaNames.get(languageTag.split('-')[0]) : undefined;
+    if (china)
+        return china;
+    const style = code === 'HK' || code === 'MO' ? 'short' : 'long';
+    const key = `${languageTag}:${style}`;
+    if (!displayNames.has(key))
+        displayNames.set(key, new Intl.DisplayNames([languageTag], { type: 'region', style }));
+    return displayNames.get(key).of(code) ?? code;
+}

package/dist/providers/coverage.d.ts

@@ -0,0 +1,31 @@
+import type { UniversalSource } from './types.js';
+export type CoverageAnswer = 'history' | 'no_history' | 'summary_only' | 'sign_in' | 'postcode_prompt' | 'wrong_carrier' | 'refused' | 'error' | 'blocked' | 'unverified' | 'n/a';
+/** History rows, an answer, or history marked partial with the reason. */
+export type CoverageCell = number | CoverageAnswer | {
+    rows: number;
+    partial: string;
+};
+export interface CoverageReference {
+    /** What this extra reference is; the first one is the table's comparison reference. */
+    note?: string;
+    /** Too old for a negative to say anything about current coverage. */
+    stale?: boolean;
+    results: Partial<Record<UniversalSource, CoverageCell>>;
+}
+export interface CarrierCoverage {
+    carrier: string;
+    /** Table name, when it differs from the catalog's display name. */
+    name?: string;
+    /** The table's direct-support and direct-sample cells. */
+    direct: string;
+    sample: string;
+    references: CoverageReference[];
+}
+export type CoverageTier = 'full' | 'partial' | 'unknown' | 'empty' | 'excluded';
+export declare const COVERAGE_SOURCES: readonly UniversalSource[];
+export declare const CARRIER_COVERAGE: readonly CarrierCoverage[];
+export declare function isHistory(cell: CoverageCell | undefined): boolean;
+/** The problems of one coverage entry, empty when it is valid. */
+export declare function coverageProblems(entry: CarrierCoverage): string[];
+/** Each provider's tier for a carrier, or null when the carrier has no coverage evidence. */
+export declare function coverageTiers(carrier: string | null | undefined): Record<UniversalSource, CoverageTier> | null;

package/dist/providers/coverage.js

@@ -0,0 +1,70 @@
+/**
+ * What each universal provider returned for public references of a carrier
+ * ([coverage.json](coverage.json), rendered in COVERAGE.md), graded for routing.
+ *
+ * A carrier's references decide one tier per provider:
+ * - `full`: history, with none marked partial and no reference missed that
+ *   another provider knew;
+ * - `partial`: history, but marked partial (label only, stops early, missing a
+ *   leg, undated), or missing a reference another provider knew;
+ * - `unknown`: nothing conclusive (errors, challenges, unverified, or only
+ *   negatives on references too old to say anything);
+ * - `empty`: answered without history (no history, summary only, a sign-in or
+ *   postcode prompt);
+ * - `excluded`: never history, and it answered with another carrier's parcel
+ *   or refused the number format.
+ *
+ * Positives are strong evidence, negatives weak: one old reference can miss a
+ * parcel the provider would know today. So an empty provider is asked last,
+ * never skipped; only a wrong parcel or a refused format excludes it.
+ */
+import data from './coverage.json' with { type: 'json' };
+export const COVERAGE_SOURCES = ['Ship24', 'ParcelsApp', '17TRACK', 'Postal Ninja', 'UPU'];
+const ANSWERS = new Set(['history', 'no_history', 'summary_only', 'sign_in', 'postcode_prompt',
+    'wrong_carrier', 'refused', 'error', 'blocked', 'unverified', 'n/a']);
+const EMPTY = new Set(['no_history', 'summary_only', 'sign_in', 'postcode_prompt']);
+export const CARRIER_COVERAGE = data.carriers;
+const BY_CARRIER = new Map(CARRIER_COVERAGE.map((entry) => [entry.carrier, entry]));
+export function isHistory(cell) {
+    return typeof cell === 'number' || cell === 'history' || (typeof cell === 'object' && cell !== null);
+}
+/** The problems of one coverage entry, empty when it is valid. */
+export function coverageProblems(entry) {
+    const problems = [];
+    if (!entry.references.length)
+        problems.push('no reference');
+    for (const [index, reference] of entry.references.entries()) {
+        for (const [source, cell] of Object.entries(reference.results)) {
+            if (!COVERAGE_SOURCES.includes(source))
+                problems.push(`reference ${index + 1}: unknown source ${source}`);
+            const valid = typeof cell === 'number' ? Number.isInteger(cell) && cell > 0
+                : typeof cell === 'string' ? ANSWERS.has(cell)
+                    : typeof cell === 'object' && cell !== null && Number.isInteger(cell.rows) && cell.rows > 0
+                        && typeof cell.partial === 'string' && cell.partial.length > 0;
+            if (!valid)
+                problems.push(`reference ${index + 1}: invalid ${source} result ${JSON.stringify(cell)}`);
+        }
+    }
+    return problems;
+}
+function tierOf(source, references) {
+    const seen = references.filter((reference) => reference.results[source] !== undefined);
+    // A reference another provider knew, which this one did not.
+    const missed = seen.some((reference) => !reference.stale
+        && (EMPTY.has(reference.results[source]) || reference.results[source] === 'wrong_carrier')
+        && Object.entries(reference.results).some(([other, cell]) => other !== source && other !== 'UPU' && isHistory(cell)));
+    if (seen.some((reference) => isHistory(reference.results[source]))) {
+        const marked = seen.some((reference) => typeof reference.results[source] === 'object');
+        return marked || missed ? 'partial' : 'full';
+    }
+    if (seen.some((reference) => ['wrong_carrier', 'refused'].includes(reference.results[source])))
+        return 'excluded';
+    return seen.some((reference) => !reference.stale && EMPTY.has(reference.results[source])) ? 'empty' : 'unknown';
+}
+/** Each provider's tier for a carrier, or null when the carrier has no coverage evidence. */
+export function coverageTiers(carrier) {
+    const entry = carrier ? BY_CARRIER.get(carrier) : undefined;
+    if (!entry)
+        return null;
+    return Object.fromEntries(COVERAGE_SOURCES.map((source) => [source, tierOf(source, entry.references)]));
+}