universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/core/catalog/definitions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Typed access to the merged carrier catalog.
+ *
+ * What it is: the generated `x-carriers` data read through the catalog types,
+ * plus the lookups the server and the detection engine need (definition,
+ * timezone, adapter, active input requirements, automatic-carrier sets).
+ * What it is not: no provider I/O, no HTTP, no application code. Everything
+ * here is a pure function of the generated catalog.
+ */
+import { type CarrierId } from '../../generated/catalog.js';
+import type { CarrierDefinition, CarrierRequirementRule } from './types.js';
+export declare const CARRIER_DEFINITIONS: Record<CarrierId, CarrierDefinition>;
+export declare function carrierDefinition(carrierId: string): CarrierDefinition;
+export declare function carrierTimezone(carrierId: string): string;
+export declare function carrierAdapter(carrierId: string): string | null;
+/**
+ * The requirements that apply to one number. The pattern is anchored here,
+ * unlike the unanchored UI filter in `carrierRequirements`.
+ */
+export declare function activeRequirements(carrierId: string, trackingNumber: string): CarrierRequirementRule[];
+/** The inputs a lookup cannot run without; an optional one only adds detail. */
+export declare function requiredRequirements(carrierId: string, trackingNumber: string): CarrierRequirementRule[];
+export declare const AUTOMATIC_CARRIER_IDS: Set<string>;
+export declare const CARRIER_NAMES: Map<string, string>;

package/dist/core/catalog/definitions.js

@@ -0,0 +1,44 @@
+/**
+ * Typed access to the merged carrier catalog.
+ *
+ * What it is: the generated `x-carriers` data read through the catalog types,
+ * plus the lookups the server and the detection engine need (definition,
+ * timezone, adapter, active input requirements, automatic-carrier sets).
+ * What it is not: no provider I/O, no HTTP, no application code. Everything
+ * here is a pure function of the generated catalog.
+ */
+import { CARRIER_CATALOG } from '../../generated/catalog.js';
+export const CARRIER_DEFINITIONS = CARRIER_CATALOG;
+export function carrierDefinition(carrierId) {
+    const definition = CARRIER_DEFINITIONS[carrierId];
+    if (!definition)
+        throw new RangeError(`Unknown carrier ${carrierId}`);
+    return definition;
+}
+export function carrierTimezone(carrierId) {
+    return carrierDefinition(carrierId).timezone ?? 'UTC';
+}
+export function carrierAdapter(carrierId) {
+    return carrierDefinition(carrierId).tracking.adapter;
+}
+/**
+ * The requirements that apply to one number. The pattern is anchored here,
+ * unlike the unanchored UI filter in `carrierRequirements`.
+ */
+export function activeRequirements(carrierId, trackingNumber) {
+    return (carrierDefinition(carrierId).tracking.requirements ?? []).filter((requirement) => !requirement.whenTrackingNumber
+        || new RegExp(`^(?:${requirement.whenTrackingNumber})$`).test(trackingNumber));
+}
+/** The inputs a lookup cannot run without; an optional one only adds detail. */
+export function requiredRequirements(carrierId, trackingNumber) {
+    return activeRequirements(carrierId, trackingNumber).filter((requirement) => requirement.optional !== true);
+}
+export const AUTOMATIC_CARRIER_IDS = new Set(Object.entries(CARRIER_DEFINITIONS)
+    .filter(([, definition]) => definition.tracking.mode === 'automatic')
+    .map(([carrierId]) => carrierId));
+export const CARRIER_NAMES = new Map(Object.entries(CARRIER_DEFINITIONS)
+    .filter(([carrierId]) => AUTOMATIC_CARRIER_IDS.has(carrierId))
+    .map(([carrierId, definition]) => [
+    carrierId,
+    definition.tracking.upstreamName ?? definition.displayName,
+]));

package/dist/core/catalog/handoff.d.ts

@@ -0,0 +1,9 @@
+import type { CarrierResult } from '../result/index.js';
+export interface DeliveryHandoff {
+    carrier: string;
+    number: string;
+    basis: 'partner' | 'destination' | 'reference';
+}
+export declare function hasDirectHandoffAdapter(carrier: string, number: string): boolean;
+/** Propose one confirmation lookup; a candidate never changes the carrier by itself. */
+export declare function deliveryHandoff(carrier: string, number: string, result: CarrierResult): DeliveryHandoff | null;

package/dist/core/catalog/handoff.js

@@ -0,0 +1,56 @@
+import { activeRequirements, AUTOMATIC_CARRIER_IDS, carrierAdapter, requiredRequirements } from './index.js';
+import { carrierIdsFromPartnerLinks, nationalPostCandidate } from './hints.js';
+import { detectCarrierMatch, isValidS10TrackingNumber, supportsSwissPostHandoff } from '../detection/index.js';
+export function hasDirectHandoffAdapter(carrier, number) {
+    if (!AUTOMATIC_CARRIER_IDS.has(carrier) || carrierAdapter(carrier) === 'universal')
+        return false;
+    // Another carrier's inputs are never borrowed, so a required one rules the carrier out.
+    if (requiredRequirements(carrier, number).length > 0)
+        return false;
+    // A carrier with only an optional input (DPD's postcode) looks parcels up by
+    // its own number: hand it a reference of its own shape, never a postal one.
+    return activeRequirements(carrier, number).length === 0
+        || detectCarrierMatch(number).candidates.includes(carrier);
+}
+/** Propose one confirmation lookup; a candidate never changes the carrier by itself. */
+export function deliveryHandoff(carrier, number, result) {
+    if (result.delivery_tracking_number != null && (typeof result.delivery_tracking_number !== 'string'
+        || !/^[A-Z0-9]{4,40}$/.test(result.delivery_tracking_number)))
+        return null;
+    const linked = carrierIdsFromPartnerLinks([result.last_status_text, ...(result.events ?? []).map((event) => event.description)], carrier);
+    if (!result.delivery_carrier && linked.length > 1)
+        return null;
+    let target = result.delivery_carrier ?? linked[0];
+    let basis = 'partner';
+    const reference = result.delivery_tracking_number || number;
+    const destination = typeof result.destination_country === 'string' ? result.destination_country
+        : typeof result.destination_country_name === 'string' ? result.destination_country_name : undefined;
+    // S10 binds the postal identity across borders. Its issuer suffix does not
+    // identify the destination operator; try that country's post only when no
+    // partner is named, and let the shared progress/freshness checks confirm it.
+    if (!target && isValidS10TrackingNumber(reference)) {
+        target = nationalPostCandidate(destination);
+        if (target)
+            basis = 'destination';
+    }
+    // A downstream reference binds the two identities, but does not prove its
+    // operator. Only a unique high-confidence catalog match may propose a probe.
+    if (!target && result.delivery_tracking_number) {
+        const detected = detectCarrierMatch(reference);
+        if (detected.confidence === 'high') {
+            target = detected.carrier;
+            basis = 'reference';
+        }
+    }
+    // Compatibility with the common AliExpress Swiss letter-post journey. This
+    // remains a bounded confirmation lookup, never an automatic carrier choice.
+    if (!target && !result.delivery_tracking_number && ['aliexpress', 'intl-post'].includes(carrier)
+        && supportsSwissPostHandoff(number) && (!destination || ['ch', 'switzerland'].includes(destination.trim().toLowerCase()))) {
+        target = 'swiss-post';
+        basis = 'reference';
+    }
+    if (!target || target === carrier || !/^[A-Z0-9]{4,40}$/.test(reference)
+        || !hasDirectHandoffAdapter(target, reference))
+        return null;
+    return { carrier: target, number: reference, basis };
+}

package/dist/core/catalog/hints.d.ts

@@ -0,0 +1,45 @@
+import { carrierBrand } from './networks.js';
+import type { CarrierId } from '../../generated/catalog.js';
+export { carrierBrand };
+/** Accept ISO codes or exact English country names supplied by a provider. */
+export declare function nationalPostCandidate(country: unknown): CarrierId | undefined;
+/** A name is only a lookup hint; the destination adapter still has to verify the parcel. */
+export declare function carrierIdFromName(name: string): string | undefined;
+/**
+ * Whether a reported carrier name is already in the catalog: a carrier or alias,
+ * another network of a brand that has several ("DHL Express", "GLS Italy"), or
+ * one of those followed by a country. Any other name is a carrier new to us.
+ */
+export declare function isKnownCarrierName(name: string): boolean;
+/**
+ * The single clock of the country after a known carrier or brand network
+ * ("DPD UK", "GLS Italy", "DHL Parcel Netherlands"), for scans that carry no
+ * zone of their own. A zone only, never a carrier. Null for a country with
+ * several zones and for names new to the catalog, whose last word need not be
+ * a place. The name can be a branch rather than where the scan happened
+ * ("Cainiao (China)"), so a scan's own location comes first.
+ */
+export declare function carrierNameCountryZone(name: string): string | null;
+/**
+ * The catalog networks of a brand named bare or as a group ("DPD", "DPD
+ * Group", "GLS", "Hermes"): every carrier whose id is the brand or starts with
+ * it and a dash. Empty for other names. The name alone cannot say which
+ * network it means; only the tracking number can narrow it.
+ */
+export declare function brandCarrierIds(name: string): string[];
+/**
+ * The catalog zones of a brand's networks (`brandCarrierIds`). The name cannot
+ * say which network scanned, so use them only when they all read the scan's
+ * clock as one instant (`sharedClockZone`). Empty for other names, and when
+ * any network has no local clock (DHL, whose eCommerce network is UTC). The
+ * set follows the catalog: a new network of a brand on another clock turns the
+ * brand's zone off, which moves the stored instants, and so the event ids, of
+ * that brand's past scans.
+ */
+export declare function brandTimeZones(name: string): string[];
+/** Reconcile a structured partner name and optional official link, without country guesses. */
+export declare function carrierIdFromPartner(name: string, url?: string): string | undefined;
+/** Retain ambiguity so weaker hints cannot override conflicting partner links. */
+export declare function carrierIdsFromPartnerLinks(descriptions: (string | null | undefined)[], origin: string): string[];
+/** An unambiguous partner link in carrier wording may propose one confirmation lookup. */
+export declare function carrierIdFromPartnerLinks(descriptions: (string | null | undefined)[], origin: string): string | undefined;

package/dist/core/catalog/hints.js

@@ -0,0 +1,162 @@
+import { CARRIER_DEFINITIONS, carrierTimezone } from './definitions.js';
+import { matchesDomain } from './linkRules.js';
+import { countryTimeZone } from '../time/index.js';
+import { NETWORK_BRANDS, carrierBrand } from './networks.js';
+export { carrierBrand };
+const key = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, '');
+// These brands have several regional/service adapters.
+const AMBIGUOUS_BRANDS = ['dhl', 'dpd', 'gls', 'hermes', 'post'];
+const NAME_ALIASES = {
+    ups: 'ups', swisspost: 'swiss-post', laposte: 'la-poste', colissimo: 'la-poste',
+    dhlecommerce: 'dhl-ecommerce', cainiao: 'aliexpress', postnl: 'spring-gds',
+    asendiausa: 'asendia',
+};
+const CATALOG_NAMES = new Set([
+    ...Object.entries(CARRIER_DEFINITIONS).filter(([id]) => id !== 'unknown')
+        .map(([, definition]) => key(definition.displayName)),
+    ...Object.keys(NAME_ALIASES), ...AMBIGUOUS_BRANDS,
+]);
+// Postal lookup candidates, not proof of which operator delivers a shipment.
+// Only operators with a dedicated adapter are useful here. The host also
+// checks adapter availability and required inputs before making a request.
+const NATIONAL_POSTS = new Map([
+    ['CA', 'canada-post'], ['CH', 'swiss-post'], ['DE', 'dhl'],
+    ['ES', 'correos-spain'], ['FI', 'posti'], ['FR', 'la-poste'],
+    ['GB', 'royal-mail'], ['IN', 'india-post'], ['IT', 'poste-italiane'],
+    ['JP', 'japan-post'], ['MY', 'pos-malaysia'], ['NL', 'spring-gds'], ['PT', 'ctt'], ['SE', 'postnord'], ['US', 'usps'],
+]);
+const englishCountries = new Intl.DisplayNames(['en'], { type: 'region' });
+// Deprecated codes carry their successor's name, so fold them into it ("FX" is France).
+const currentRegion = (code) => new Intl.Locale(`und-${code}`).region ?? code;
+// Every region's English name, plus the common short forms, by name key.
+const COUNTRY_CODES = new Map([
+    ...Array.from({ length: 26 * 26 }, (_, index) => String.fromCharCode(65 + Math.floor(index / 26), 65 + (index % 26)))
+        .map((code) => [key(englishCountries.of(code) ?? ''), currentRegion(code)])
+        .filter(([name, code]) => name !== '' && name !== code.toLowerCase()),
+    ['uk', 'GB'], ['usa', 'US'],
+]);
+/** Accept ISO codes or exact English country names supplied by a provider. */
+export function nationalPostCandidate(country) {
+    if (typeof country !== 'string')
+        return undefined;
+    const value = country.trim().toUpperCase();
+    const direct = NATIONAL_POSTS.get(value);
+    if (direct)
+        return direct;
+    return [...NATIONAL_POSTS].find(([code]) => englishCountries.of(code)?.toUpperCase() === value)?.[1];
+}
+function catalogCarrier(normalized) {
+    if (AMBIGUOUS_BRANDS.includes(normalized))
+        return undefined;
+    if (Object.hasOwn(NAME_ALIASES, normalized))
+        return NAME_ALIASES[normalized];
+    const matches = Object.entries(CARRIER_DEFINITIONS)
+        .filter(([id, definition]) => id !== 'unknown' && key(definition.displayName) === normalized);
+    return matches.length === 1 ? matches[0][0] : undefined;
+}
+/** "Chronopost France", "Royal Mail (UK)": the name before a trailing country, and its ISO code. */
+function countryQualified(name) {
+    const words = name.replace(/[()]/g, ' ').trim().split(/\s+/);
+    for (let size = Math.min(3, words.length - 1); size > 0; size--) {
+        const tail = words.slice(-size).join(' ');
+        const country = COUNTRY_CODES.get(key(tail))
+            ?? (/^[A-Z]{2}$/.test(tail) && englishCountries.of(tail) !== tail ? currentRegion(tail) : undefined);
+        if (country)
+            return { base: words.slice(0, -size).join(' '), country };
+    }
+    return undefined;
+}
+/** A name is only a lookup hint; the destination adapter still has to verify the parcel. */
+export function carrierIdFromName(name) {
+    const exact = catalogCarrier(key(name));
+    if (exact)
+        return exact;
+    // The carrier's own country names the same carrier; another country can be a
+    // different company under the brand, and a multi-zone country cannot tell.
+    const qualified = countryQualified(name);
+    const carrier = qualified && catalogCarrier(key(qualified.base));
+    const zone = qualified && countryTimeZone(qualified.country);
+    return carrier && zone && CARRIER_DEFINITIONS[carrier]?.timezone === zone ? carrier : undefined;
+}
+/**
+ * Whether a reported carrier name is already in the catalog: a carrier or alias,
+ * another network of a brand that has several ("DHL Express", "GLS Italy"), or
+ * one of those followed by a country. Any other name is a carrier new to us.
+ */
+export function isKnownCarrierName(name) {
+    const qualified = countryQualified(name);
+    return [key(name), ...(qualified ? [key(qualified.base)] : [])].some((candidate) => CATALOG_NAMES.has(candidate) || NETWORK_BRANDS.some((brand) => candidate.startsWith(brand)));
+}
+/**
+ * The single clock of the country after a known carrier or brand network
+ * ("DPD UK", "GLS Italy", "DHL Parcel Netherlands"), for scans that carry no
+ * zone of their own. A zone only, never a carrier. Null for a country with
+ * several zones and for names new to the catalog, whose last word need not be
+ * a place. The name can be a branch rather than where the scan happened
+ * ("Cainiao (China)"), so a scan's own location comes first.
+ */
+export function carrierNameCountryZone(name) {
+    const qualified = countryQualified(name);
+    return qualified && isKnownCarrierName(name) ? countryTimeZone(qualified.country) : null;
+}
+/**
+ * The catalog networks of a brand named bare or as a group ("DPD", "DPD
+ * Group", "GLS", "Hermes"): every carrier whose id is the brand or starts with
+ * it and a dash. Empty for other names. The name alone cannot say which
+ * network it means; only the tracking number can narrow it.
+ */
+export function brandCarrierIds(name) {
+    const normalized = key(name);
+    const brand = NETWORK_BRANDS.find((candidate) => normalized === candidate || normalized === `${candidate}group`);
+    if (!brand)
+        return [];
+    return Object.keys(CARRIER_DEFINITIONS).filter((id) => carrierBrand(id) === brand);
+}
+/**
+ * The catalog zones of a brand's networks (`brandCarrierIds`). The name cannot
+ * say which network scanned, so use them only when they all read the scan's
+ * clock as one instant (`sharedClockZone`). Empty for other names, and when
+ * any network has no local clock (DHL, whose eCommerce network is UTC). The
+ * set follows the catalog: a new network of a brand on another clock turns the
+ * brand's zone off, which moves the stored instants, and so the event ids, of
+ * that brand's past scans.
+ */
+export function brandTimeZones(name) {
+    const zones = brandCarrierIds(name).map((id) => carrierTimezone(id));
+    return zones.includes('UTC') ? [] : [...new Set(zones)];
+}
+/** Known portal hosts only. This identifies a lookup hint; it never follows the URL. */
+function carriersFromUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+        return [];
+    // Arrival notices also use the Swiss Post homepage instead of its tracking subdomain.
+    if (['post.ch', 'www.post.ch'].includes(url.hostname))
+        return ['swiss-post'];
+    return Object.entries(CARRIER_DEFINITIONS).filter(([, definition]) => definition.linkRules.some((rule) => rule.domains.some((domain) => matchesDomain(url.hostname, domain)))).map(([id]) => id);
+}
+/** Reconcile a structured partner name and optional official link, without country guesses. */
+export function carrierIdFromPartner(name, url = '') {
+    const named = carrierIdFromName(name);
+    const linked = carriersFromUrl(url);
+    if (named)
+        return !linked.length || linked.includes(named) ? named : undefined;
+    return linked.length === 1 ? linked[0] : undefined;
+}
+/** Retain ambiguity so weaker hints cannot override conflicting partner links. */
+export function carrierIdsFromPartnerLinks(descriptions, origin) {
+    const candidates = new Set(descriptions.flatMap((description) => [...String(description ?? '').matchAll(/https?:\/\/[^\s<>"')]+/gi)]
+        .flatMap(([url]) => carriersFromUrl(url)).filter((carrier) => carrier !== origin)));
+    return [...candidates];
+}
+/** An unambiguous partner link in carrier wording may propose one confirmation lookup. */
+export function carrierIdFromPartnerLinks(descriptions, origin) {
+    const candidates = carrierIdsFromPartnerLinks(descriptions, origin);
+    return candidates.length === 1 ? candidates[0] : undefined;
+}

package/dist/core/catalog/index.d.ts

@@ -0,0 +1,38 @@
+import type { CarrierId } from '../../generated/catalog.js';
+import { amazonOrdersUrl } from './amazon.js';
+import type { CarrierInfo, CarrierInputRequirement, ParcelTrackingLink, TrackedParcel } from './types.js';
+export * from './types.js';
+export * from './definitions.js';
+export * from './linkRules.js';
+export * from './amazon.js';
+/** Carrier-specific printed identifiers expected by the official portal. */
+export declare function trackingNumberForLink(carrierId: CarrierId, raw: string): string;
+/** Build a carrier's portal link factory from its catalog template. */
+export declare function trackingLink(carrierId: CarrierId, template: string | undefined): typeof amazonOrdersUrl | undefined;
+export declare const CARRIERS: Record<CarrierId, CarrierInfo>;
+export declare function carrierInfo(id: CarrierId, locale?: string): CarrierInfo;
+export declare const SELECTABLE_CARRIERS: CarrierInfo[];
+/** The requirements a form shows for one number, matched unanchored. */
+export declare function carrierRequirements(carrierId: CarrierId, trackingNumber: string): CarrierInputRequirement[];
+/**
+ * Whether a form value lets the parcel be saved: blank passes only for an
+ * optional input, and a value that is typed must still match the pattern.
+ */
+export declare function requirementSatisfied(requirement: Pick<CarrierInputRequirement, 'optional' | 'pattern'>, raw: string): boolean;
+export declare function tracksAutomatically(carrierId: CarrierId): boolean;
+export declare function carrierTrackingHintKey(carrierId: CarrierId): "add.amazonAccount" | "add.autoSync" | "add.linkSync";
+/** The source shown on cards and used as the primary link. */
+export declare function activeTrackingCarrierId(parcel: Pick<TrackedParcel, 'carrier' | 'trackingNumber' | 'trackingSource'>): CarrierId;
+/** Keep the original carrier identity when separate tracking numbers have been linked. */
+export declare function displayedCarrierId(parcel: Pick<TrackedParcel, 'carrier' | 'trackingNumber' | 'trackingSource' | 'originalCarrier'>): CarrierId;
+/** Distinct numbers in delivery-first order, including carriers without a website. */
+export declare function parcelTrackingNumbers(parcel: Pick<TrackedParcel, 'carrier' | 'trackingNumber' | 'trackingSource' | 'activeTrackingNumber' | 'originalCarrier' | 'originalTrackingNumber'>): {
+    carrier: CarrierId;
+    number: string;
+}[];
+/** Link to the source of the displayed result, never a speculative routing preference. */
+export declare function parcelTrackingLinks(parcel: Parameters<typeof carrierTrackingLinks>[0], locale?: string): ParcelTrackingLink[];
+/** Primary delivery tracker first, followed by the earlier international journey. */
+declare function carrierTrackingLinks(parcel: Pick<TrackedParcel, 'carrier' | 'trackingNumber' | 'trackingUrl' | 'trackingSource' | 'trackingProvider' | 'carrierAnswered' | 'activeTrackingNumber' | 'swissPostReady' | 'originalCarrier' | 'originalTrackingNumber' | 'originalTrackingUrl'>, locale?: string): ParcelTrackingLink[];
+/** Point a carrier portal at the reader's language when the site supports it. */
+export declare function localizedCarrierUrl(carrierId: CarrierId, url: string, locale?: string): string;

package/dist/core/catalog/index.js

@@ -0,0 +1,223 @@
+/**
+ * The carrier catalog, as the application consumes it.
+ *
+ * What it is: the `CARRIERS` record derived from the generated catalog, the
+ * per-carrier lookups, and the tracking links that follow from catalog data
+ * alone (carrier portals, localized URLs, a parcel's link list).
+ * What it is not: no provider I/O, no HTTP, no application or framework code.
+ * Everything here is a pure function of the catalog and its arguments.
+ */
+import { normalizeCourierGuyNumber } from '../../carriers/the-courier-guy/number.js';
+import { postlogisticsIdentifier } from '../../carriers/postlogistics/number.js';
+import { isValidMondialRelayBarcode } from '../detection/mondialRelay.js';
+import { normalizeTrackingNumber } from '../detection/normalize.js';
+import { supportsSwissPostHandoff } from '../detection/s10.js';
+import { amazonOrdersUrl, amazonShippingUrl, requiresAmazonAccount } from './amazon.js';
+import { CARRIER_DEFINITIONS } from './definitions.js';
+export * from './types.js';
+export * from './definitions.js';
+export * from './linkRules.js';
+export * from './amazon.js';
+/** Carrier-specific printed identifiers expected by the official portal. */
+export function trackingNumberForLink(carrierId, raw) {
+    const normalized = normalizeTrackingNumber(raw);
+    if (carrierId === 'mondial-relay' && isValidMondialRelayBarcode(normalized))
+        return normalized.slice(0, 12);
+    if (carrierId === 'c-chez-vous') {
+        const composite = /^([A-Z0-9]{11})(\d{5})$/.exec(normalized);
+        if (composite)
+            return `${composite[1]}--${composite[2]}`;
+    }
+    if (carrierId === 'the-courier-guy') {
+        const product = /^(DD|LD)([A-Z0-9]{6})$/.exec(normalized);
+        if (product)
+            return normalizeCourierGuyNumber(normalized);
+    }
+    if (carrierId === 'postlogistics')
+        return postlogisticsIdentifier(raw);
+    return raw;
+}
+/** Build a carrier's portal link factory from its catalog template. */
+export function trackingLink(carrierId, template) {
+    if (carrierId === 'amazon-logistics')
+        return amazonOrdersUrl;
+    if (carrierId === 'amazon-shipping')
+        return amazonShippingUrl;
+    if (!template)
+        return undefined;
+    return (trackingNumber) => template.replace('{trackingNumber}', encodeURIComponent(trackingNumberForLink(carrierId, trackingNumber)));
+}
+function builtCarrierInfo(id, carrier) {
+    return {
+        id,
+        name: carrier.displayName,
+        aliases: carrier.aliases ?? [],
+        countries: carrier.countries ?? [],
+        trackingSiteName: carrier.trackingSiteName,
+        color: carrier.color,
+        trackingUrl: trackingLink(id, carrier.trackingUrlTemplate),
+        capabilities: {
+            tracking: {
+                mode: carrier.tracking.mode,
+                adapter: carrier.tracking.adapter,
+                requirements: [...(carrier.tracking.requirements ?? [])],
+            },
+            selectable: carrier.selectable,
+            timezone: carrier.timezone,
+        },
+    };
+}
+export const CARRIERS = Object.fromEntries(Object.entries(CARRIER_DEFINITIONS).map(([id, carrier]) => [
+    id,
+    builtCarrierInfo(id, carrier),
+]));
+export function carrierInfo(id, locale) {
+    const carrier = CARRIERS[id] ?? CARRIERS.unknown;
+    const name = locale ? CARRIER_DEFINITIONS[carrier.id].displayNames?.[locale] : undefined;
+    return name ? { ...carrier, name } : carrier;
+}
+export const SELECTABLE_CARRIERS = Object.values(CARRIERS).filter((carrier) => carrier.capabilities.selectable);
+/** The requirements a form shows for one number, matched unanchored. */
+export function carrierRequirements(carrierId, trackingNumber) {
+    const normalized = normalizeTrackingNumber(trackingNumber);
+    return CARRIERS[carrierId].capabilities.tracking.requirements.filter((requirement) => !requirement.whenTrackingNumber
+        || new RegExp(requirement.whenTrackingNumber).test(normalized));
+}
+/**
+ * Whether a form value lets the parcel be saved: blank passes only for an
+ * optional input, and a value that is typed must still match the pattern.
+ */
+export function requirementSatisfied(requirement, raw) {
+    const value = raw.trim();
+    if (!value)
+        return requirement.optional === true;
+    return !requirement.pattern || new RegExp(requirement.pattern).test(value);
+}
+export function tracksAutomatically(carrierId) {
+    return CARRIERS[carrierId].capabilities.tracking.mode === 'automatic';
+}
+export function carrierTrackingHintKey(carrierId) {
+    return requiresAmazonAccount(carrierId) ? 'add.amazonAccount'
+        : tracksAutomatically(carrierId) ? 'add.autoSync' : 'add.linkSync';
+}
+/** The source shown on cards and used as the primary link. */
+export function activeTrackingCarrierId(parcel) {
+    if (requiresAmazonAccount(parcel.carrier, parcel.trackingNumber))
+        return 'amazon-logistics';
+    if (parcel.trackingSource)
+        return parcel.trackingSource;
+    return supportsSwissPostHandoff(parcel.trackingNumber) ? 'aliexpress' : parcel.carrier;
+}
+/** Keep the original carrier identity when separate tracking numbers have been linked. */
+export function displayedCarrierId(parcel) {
+    return parcel.originalCarrier ?? activeTrackingCarrierId(parcel);
+}
+/** Distinct numbers in delivery-first order, including carriers without a website. */
+export function parcelTrackingNumbers(parcel) {
+    const delivery = { carrier: activeTrackingCarrierId(parcel), number: parcel.activeTrackingNumber ?? parcel.trackingNumber };
+    const original = { carrier: parcel.originalCarrier ?? parcel.carrier, number: parcel.originalTrackingNumber ?? parcel.trackingNumber };
+    return delivery.number === original.number ? [delivery] : [delivery, original];
+}
+/** Link to the source of the displayed result, never a speculative routing preference. */
+export function parcelTrackingLinks(parcel, locale) {
+    if (requiresAmazonAccount(parcel.carrier, parcel.trackingNumber)) {
+        const carrier = carrierInfo('amazon-logistics', locale);
+        return [{ carrier, name: carrier.name, url: amazonOrdersUrl(parcel.trackingNumber), active: true, ready: true, role: 'active' }];
+    }
+    const links = carrierTrackingLinks(parcel, locale);
+    const number = encodeURIComponent(parcel.originalCarrier && parcel.trackingSource
+        ? parcel.activeTrackingNumber ?? parcel.trackingNumber : parcel.trackingNumber);
+    const provider = parcel.carrierAnswered ? undefined : parcel.trackingProvider;
+    const url = provider === '17TRACK' ? `https://t.17track.net/en#nums=${number}`
+        : provider === 'ParcelsApp' ? `https://parcelsapp.com/en/tracking/${number}`
+            : provider === 'Ship24' ? `https://www.ship24.com/tracking?p=${number}`
+                // Postal Ninja's verified public entry point; no guessed session/private URL.
+                : provider === 'Postal Ninja' ? 'https://postal.ninja/en/track'
+                    : provider === 'UPU' ? 'https://globaltracktrace.ptc.post/gtt.web/Search.aspx' : undefined;
+    if (!url || !provider)
+        return links;
+    const primary = { carrier: carrierInfo('unknown', locale), name: provider,
+        url: localizedCarrierUrl('unknown', url, locale), active: true, ready: true, role: 'active' };
+    return [primary, ...links.filter((link) => link.role !== 'active' && link.url !== primary.url)];
+}
+/** Primary delivery tracker first, followed by the earlier international journey. */
+function carrierTrackingLinks(parcel, locale) {
+    if (parcel.originalCarrier && parcel.originalTrackingNumber) {
+        const active = parcelTrackingLinks({
+            carrier: activeTrackingCarrierId(parcel), trackingNumber: parcel.activeTrackingNumber ?? parcel.trackingNumber,
+            trackingUrl: activeTrackingCarrierId(parcel) === parcel.carrier
+                && (!parcel.activeTrackingNumber || parcel.activeTrackingNumber === parcel.trackingNumber) ? parcel.trackingUrl : undefined,
+        }, locale);
+        const original = parcelTrackingLinks({
+            carrier: parcel.originalCarrier, trackingNumber: parcel.originalTrackingNumber,
+            trackingUrl: parcel.originalTrackingUrl,
+        }, locale).map((link) => ({ ...link, active: false, role: 'history' }));
+        return [...active, ...original];
+    }
+    if (!supportsSwissPostHandoff(parcel.trackingNumber)) {
+        const carrier = carrierInfo(activeTrackingCarrierId(parcel), locale);
+        const number = parcel.activeTrackingNumber ?? parcel.trackingNumber;
+        // Repair obsolete generated links saved by earlier app versions.
+        let savedUrl = requiresAmazonAccount(carrier.id, number) || carrier.id === 'intl-post' || carrier.id !== parcel.carrier
+            || number !== parcel.trackingNumber ? undefined : parcel.trackingUrl;
+        if (parcel.carrier === 'spring-gds' && savedUrl) {
+            try {
+                const saved = new URL(savedUrl);
+                if (saved.hostname === 'postnl.post' && saved.pathname.startsWith('/details/')) {
+                    savedUrl = undefined;
+                }
+            }
+            catch {
+                // Leave other saved URLs to the existing link validation.
+            }
+        }
+        const url = savedUrl ?? carrier.trackingUrl?.(number);
+        return url ? [{
+                carrier,
+                name: carrier.trackingSiteName ?? carrier.name,
+                url: localizedCarrierUrl(carrier.id, url, locale),
+                active: true,
+                ready: true,
+                role: 'active',
+            }] : [];
+    }
+    const activeCarrier = activeTrackingCarrierId(parcel);
+    const swissPostReady = parcel.swissPostReady === true || activeCarrier === 'swiss-post';
+    const links = ['aliexpress', 'swiss-post'].map((carrierId) => {
+        const carrier = carrierInfo(carrierId, locale);
+        const active = carrierId === activeCarrier;
+        const ready = carrierId !== 'swiss-post' || swissPostReady;
+        return {
+            carrier,
+            name: carrier.trackingSiteName ?? carrier.name,
+            url: localizedCarrierUrl(carrier.id, carrier.trackingUrl(parcel.trackingNumber), locale),
+            active,
+            ready,
+            role: active ? 'active' : ready ? 'history' : 'waiting',
+        };
+    });
+    return links.sort((first, second) => Number(second.active) - Number(first.active));
+}
+/** Point a carrier portal at the reader's language when the site supports it. */
+export function localizedCarrierUrl(carrierId, url, locale) {
+    if (!locale || !['en', 'de', 'fr', 'it', 'es', 'pt', 'pl'].includes(locale))
+        return url;
+    try {
+        const localizedUrl = new URL(url);
+        if (carrierId === 'swiss-post') {
+            localizedUrl.searchParams.set('lang', ['en', 'de', 'fr', 'it'].includes(locale) ? locale : 'en');
+        }
+        else if (localizedUrl.hostname === 't.17track.net' || localizedUrl.hostname === 'parcelsapp.com') {
+            // Parcels supports Spanish and Portuguese, but has no Polish page.
+            const siteLocale = localizedUrl.hostname === 'parcelsapp.com' && locale === 'pl' ? 'en' : locale;
+            localizedUrl.pathname = localizedUrl.pathname.replace(/^\/[a-z]{2}(?=\/|$)/i, `/${siteLocale}`);
+        }
+        else {
+            return url;
+        }
+        return localizedUrl.toString();
+    }
+    catch {
+        return url;
+    }
+}

package/dist/core/catalog/inputs.d.ts

@@ -0,0 +1,6 @@
+export { AUTOMATIC_CARRIER_IDS, CARRIER_NAMES, activeRequirements, carrierAdapter, carrierDefinition, carrierTimezone, requiredRequirements, } from './index.js';
+export { isValidS10TrackingNumber, supportsSwissPostHandoff, } from '../detection/index.js';
+export declare function normalizeCarrierInputs(carrierId: string, trackingNumber: string, trackingUrl: string, dpdPostcode: string): {
+    trackingUrl: string | null;
+    dpdPostcode: string | null;
+};