universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/asendia/numbers.json

@@ -0,0 +1,177 @@
+{
+  "carrier": "asendia",
+  "records": [
+    {
+      "number": "AHOY1X39DP45",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ship24.com/couriers/asendia-tracking"
+      },
+      "expect": {
+        "carrier": "asendia",
+        "confidence": "high"
+      },
+      "note": "Published Pirate Ship export number carried by Asendia USA; A1 returned its delivered history on 2026-09-22."
+    },
+    {
+      "number": "AS010007869US",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ship24.com/couriers/asendia-tracking"
+      },
+      "expect": {
+        "carrier": "asendia",
+        "confidence": "high"
+      },
+      "note": "Published Asendia USA example with an invalid S10 check digit; A1 had no data for it on 2026-09-22."
+    },
+    {
+      "number": "AS010501721US",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ship24.com/couriers/asendia-tracking"
+      },
+      "expect": {
+        "carrier": "asendia",
+        "confidence": "high"
+      },
+      "note": "Published Asendia USA example; Asendia USA's A1 tracking returned its delivered history on 2026-09-22."
+    },
+    {
+      "number": "ASE12345678",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "asendia",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "ASHK12123456789011",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://a1api.asendiausa.com/swagger/index.html?urls.primaryName=Parcel+v1.0"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Example Asendia unique identifier (ashid) in Asendia USA's Parcel API reference, not a real shipment."
+    },
+    {
+      "number": "EEUS027373790JP0",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ship24.com/couriers/asendia-tracking"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Published eBay International Shipping number attributed to Asendia; A1 had no data for it on 2026-09-22. On 2026-09-30 ParcelsApp filed its Asendia scans under EasyShip on local clocks, matching Ship24's instants and Swiss Post's own scan when read in each place's zone."
+    },
+    {
+      "number": "EEUS027988469JP0",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.ship24.com/couriers/asendia-tracking"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Published eBay International Shipping number carried by Asendia USA; A1 returned its delivered history on 2026-09-22."
+    },
+    {
+      "number": "LF079877211FR",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://marketplace.fnacdarty.com/s/article/Dois-je-obligatoirement-renseigner-un-num%C3%A9ro-de-suivi-tracking-pour-ma-commande?language=fr_BE"
+      },
+      "expect": {
+        "carrier": "la-poste",
+        "confidence": "high"
+      },
+      "note": "Published integration example, not a real shipment. The source attributes it to Asendia; detection selects La Poste / Colissimo."
+    },
+    {
+      "number": "LS232735825CH",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a680c8b8a48f47256b888b9",
+        "date": "2026-07-28"
+      },
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported Asendia USA shipment returned from Germany through Switzerland; detection selects Swiss Post. On 2026-09-30 ParcelsApp listed its Asendia USA scans in both countries at the UTC instants A1 returned."
+    },
+    {
+      "number": "LS244428589CH",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aa36fc3b355e35ecf1ef14e",
+        "date": "2026-09-11"
+      },
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment sent from the USA through Asendia; detection selects Swiss Post. Asendia USA's A1 tracking returned its history on 2026-09-29."
+    },
+    {
+      "number": "UX000352872CH",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://a1api.asendiausa.com/swagger/index.html?urls.primaryName=Parcel+v1.0"
+      },
+      "expect": {
+        "carrier": "swiss-post",
+        "confidence": "high"
+      },
+      "note": "Example value of the trackingNumber field in Asendia USA's Parcel API reference, not a real shipment; detection selects Swiss Post for this S10 shape."
+    },
+    {
+      "number": "UX911572560FR",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a064349008e8e5d4cf776a3",
+        "date": "2026-05-14"
+      },
+      "expect": {
+        "carrier": "la-poste",
+        "confidence": "high"
+      },
+      "note": "Publicly reported Asendia USA shipment; detection selects La Poste / Colissimo. On 2026-09-30 ParcelsApp listed its Asendia USA scans at the UTC instants A1 returned."
+    },
+    {
+      "number": "LN242142606US",
+      "role": "quarantined",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Asendia; detection falls back to the generic postal rule."
+    }
+  ]
+}

package/dist/carriers/asendia/probe.d.ts

@@ -0,0 +1,31 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeAsendiaTrackingNumber(raw: string): string;
+export declare function asendiaTrackingUrl(rawTrackingNumber: string): string;
+export declare function asendiaTrackingApiUrl(): string;
+export declare function asendiaConfigApiUrl(): string;
+export declare function asendiaEnvironmentUrl(): string;
+/**
+ * Read the public request-checksum key the portal publishes in its own
+ * environment script. It is a browser-visible value, not an account secret,
+ * and it rotates with a frontend deployment.
+ */
+export declare function parseAsendiaPublicHitKey(script: string): string;
+export declare function asendiaHitToken(rawTrackingNumber: string, isoDate: string, publicHitKey: string): string;
+export declare function parseAsendiaTrackingResponse(payload: unknown, rawTrackingNumber: string): CarrierResult;
+export interface AsendiaTrackerOptions {
+    timeoutMs?: number;
+    now?: () => Date;
+    turnstileTokenProvider?: () => string | Promise<string>;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+}
+export declare class AsendiaTracker {
+    readonly timeoutMs: number;
+    readonly now: () => Date;
+    readonly turnstileTokenProvider: () => string | Promise<string>;
+    readonly fetcher?: typeof fetch;
+    constructor(options?: AsendiaTrackerOptions);
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+    private requestText;
+    private requestJson;
+}

package/dist/carriers/asendia/probe.js

@@ -0,0 +1,355 @@
+/**
+ * Asendia global portal (track.asendia.com) protocol probe.
+ *
+ * Not on the sync path: the registered adapter (`adapter.ts`) reads Asendia
+ * USA's A1 platform. This module reproduces the global portal's public request
+ * protocol far enough to prove that its Cloudflare Turnstile gate still behaves
+ * the way we recorded, and it parses a response when one is obtained.
+ *
+ * Protocol provenance (inspected 2026-08-30, rechecked 2026-09-22):
+ * https://track.asendia.com/track
+ * https://track.asendia.com/_next/static/chunks/pages/track/%5B%5B...tracking_id%5D%5D-a4e56a18621e52da.js
+ * The official frontend loads a tenant config and a public daily checksum key,
+ * then POSTs to branded-parcel-search. `fe-tracking-configuration` sets
+ * `TRACKING.ENABLE_CAPTCHA`, and with it a fresh Cloudflare Turnstile token is
+ * a required body field; callers must obtain that token through an approved
+ * interactive browser flow and inject it into this module. The checksum hashes
+ * the comma-joined ids, which is the plain number for the single id sent here.
+ *
+ * Privacy: the parcel payload carries the order reference and the recipient's
+ * name, address and e-mail. `parseAsendiaTrackingResponse()` rebuilds every
+ * event from an explicit allowlist (time, harmonized wording, scanning
+ * location, harmonized code) and copies nothing else.
+ */
+import { createHash } from 'node:crypto';
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { ChallengeError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { isoTime, zonedTime } from '../../core/time/index.js';
+import { cleanScalar, decodeText, fetchBounded, parseJsonBytes, UpstreamHttpError, } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyAsendiaStatus } from './status.js';
+const TRACKING_ORIGIN = 'https://track.asendia.com';
+const TRACKING_PAGE = `${TRACKING_ORIGIN}/track`;
+const TRACKING_API = `${TRACKING_ORIGIN}/api/1.0/branded-url/branded-parcel-search`;
+const CONFIG_API = `${TRACKING_ORIGIN}/api/1.0/branded-url/get-config-data/track.asendia.com`;
+const ENVIRONMENT_SCRIPT = `${TRACKING_ORIGIN}/__env.js`;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+const ZONE = 'Europe/Zurich';
+const EVENT_TIME_FORMATS = [
+    'dd/MM/yyyy HH:mm:ss',
+    'dd/MM/yyyy HH:mm',
+    'yyyy-MM-dd HH:mm:ss',
+    'yyyy-MM-dd HH:mm',
+    'dd/MM/yyyy',
+    'yyyy-MM-dd',
+];
+/**
+ * Strip markup from a short provider string. Kept local rather than using
+ * `textFromHtml`: the portal embeds entity-encoded wording that Cheerio decodes
+ * fully, where the regex helper would leave numeric entities behind.
+ */
+function plainText(value, maxLength = 500) {
+    const raw = cleanScalar(value, Math.max(5_000, maxLength * 10));
+    return raw ? cleanScalar(load(raw).text(), maxLength) : '';
+}
+export function normalizeAsendiaTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s-]/g, '');
+    if (!/^[A-Z0-9]{8,40}$/.test(value) || !/\d/.test(value)) {
+        throw new TypeError('Asendia tracking numbers must contain 8 to 40 ASCII letters and digits');
+    }
+    return value;
+}
+export function asendiaTrackingUrl(rawTrackingNumber) {
+    return `${TRACKING_PAGE}/${encodeURIComponent(normalizeAsendiaTrackingNumber(rawTrackingNumber))}`;
+}
+export function asendiaTrackingApiUrl() {
+    const url = new URL(TRACKING_API);
+    url.searchParams.set('sort', 'shipment_date');
+    return url.toString();
+}
+export function asendiaConfigApiUrl() {
+    return CONFIG_API;
+}
+export function asendiaEnvironmentUrl() {
+    return ENVIRONMENT_SCRIPT;
+}
+/**
+ * Read the public request-checksum key the portal publishes in its own
+ * environment script. It is a browser-visible value, not an account secret,
+ * and it rotates with a frontend deployment.
+ */
+export function parseAsendiaPublicHitKey(script) {
+    const match = /window\.__ENV\s*=\s*(\{[^;]*\})\s*;?/.exec(script);
+    if (!match)
+        throw new SchemaError('Asendia', 'Asendia returned an invalid public environment script');
+    let payload;
+    try {
+        payload = JSON.parse(match[1]);
+    }
+    catch (error) {
+        throw new SchemaError('Asendia', 'Asendia returned an invalid public environment script', { cause: error });
+    }
+    const key = isRecord(payload) ? cleanScalar(payload.NEXT_PUBLIC_BRANDED_HIT_KEY, 128) : '';
+    if (!/^[a-f0-9]{64}$/i.test(key)) {
+        throw new SchemaError('Asendia', 'Asendia did not publish a valid request checksum key');
+    }
+    return key.toLocaleLowerCase('en-US');
+}
+export function asendiaHitToken(rawTrackingNumber, isoDate, publicHitKey) {
+    const trackingNumber = normalizeAsendiaTrackingNumber(rawTrackingNumber);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(isoDate) || !DateTime.fromISO(isoDate).isValid) {
+        throw new TypeError('Asendia request dates must use YYYY-MM-DD');
+    }
+    if (!/^[a-f0-9]{64}$/i.test(publicHitKey)) {
+        throw new TypeError('Asendia request checksum keys must contain 64 hexadecimal characters');
+    }
+    return createHash('sha256')
+        .update(`${trackingNumber}${isoDate}${publicHitKey.toLocaleLowerCase('en-US')}`)
+        .digest('hex');
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function parseTenantConfig(payload) {
+    if (!isRecord(payload) || !isRecord(payload.data)) {
+        throw new SchemaError('Asendia', 'Asendia returned an invalid tracking configuration');
+    }
+    const data = payload.data;
+    const id = typeof data.id === 'number' || typeof data.id === 'string' ? data.id : '';
+    const subsidiary = cleanScalar(data.subsidiary_name, 128);
+    const subsidiaryId = typeof data.subsidiary === 'number' || typeof data.subsidiary === 'string'
+        ? data.subsidiary
+        : '';
+    const brands = records(data.brand_id)
+        .map((brand) => cleanScalar(brand.customer_id, 128))
+        .filter(Boolean);
+    if (id === '' || !subsidiary || subsidiaryId === '' || brands.length === 0) {
+        throw new SchemaError('Asendia', 'Asendia returned an incomplete tracking configuration');
+    }
+    return {
+        id,
+        subsidiary,
+        subsidiaryId,
+        brandId: brands.includes('*') ? '*' : brands,
+    };
+}
+function responseIdentifier(parcel) {
+    for (const value of [parcel.tracking_id, parcel.upper_tracking_id]) {
+        try {
+            return normalizeAsendiaTrackingNumber(cleanScalar(value, 64));
+        }
+        catch {
+            // Try the alternate provider field.
+        }
+    }
+    return '';
+}
+function selectParcel(payload, rawTrackingNumber) {
+    const trackingNumber = normalizeAsendiaTrackingNumber(rawTrackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError('Asendia', 'Asendia returned an invalid tracking response');
+    const parcels = records(payload.data);
+    if (parcels.length === 0)
+        throw new NotFoundError('Asendia');
+    const matches = parcels.filter((parcel) => responseIdentifier(parcel) === trackingNumber);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1)
+        throw new SchemaError('Asendia', 'Asendia returned an ambiguous shipment');
+    throw new SchemaError('Asendia', 'Asendia returned a different shipment');
+}
+/**
+ * Scan stamps arrive either as ISO strings (with or without an offset) or in
+ * one of the portal's display formats. Offset-less values are read in the
+ * portal's own zone rather than guessed as UTC.
+ */
+function parseEventTime(value) {
+    const iso = isoTime(value, ZONE, 64);
+    if (iso)
+        return iso;
+    for (const format of EVENT_TIME_FORMATS) {
+        const parsed = zonedTime(value, format, ZONE, { maxLength: 64 });
+        if (parsed)
+            return parsed;
+    }
+    return null;
+}
+function safeEventCode(value) {
+    const code = cleanScalar(value, 32).toLocaleUpperCase('en-US');
+    return /^[A-Z0-9._-]{1,32}$/.test(code) ? code : '';
+}
+function parseEvents(parcel) {
+    const parsed = [];
+    const seen = new Set();
+    records(parcel.events).slice(0, MAX_EVENTS_TO_INSPECT).forEach((raw, sourceIndex) => {
+        const time = parseEventTime(raw.eventDateTime ?? raw.event_datetime ?? raw.datetime);
+        const description = plainText(raw.harmonizedEvent)
+            || plainText(raw.harmonized_event)
+            || plainText(raw.eventDesc)
+            || plainText(raw.description);
+        if (!time || !description)
+            return;
+        const location = plainText(raw.scanningLocation ?? raw.scanning_location, 200);
+        const code = safeEventCode(raw.harmonizedCode ?? raw.eventId ?? raw.event_id);
+        const identity = JSON.stringify([time.iso, location, description, code]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyAsendiaStatus(description);
+        parsed.push({
+            sourceIndex,
+            timestamp: time.timestamp,
+            status: classified.status,
+            event: {
+                time: time.iso,
+                location,
+                description,
+                stage: classified.stage,
+                ...(code ? { provider_code: code } : {}),
+            },
+        });
+    });
+    parsed.sort((left, right) => (right.timestamp - left.timestamp || left.sourceIndex - right.sourceIndex));
+    return parsed.slice(0, MAX_EVENTS_TO_RETURN);
+}
+function expectedDelivery(parcel) {
+    for (const value of [parcel.estimated_delivery_date, parcel.delivery_date]) {
+        const raw = cleanScalar(value, 64);
+        if (!raw)
+            continue;
+        let parsed = DateTime.fromISO(raw, { zone: ZONE });
+        if (!parsed.isValid)
+            parsed = DateTime.fromFormat(raw, 'dd/MM/yyyy', { zone: ZONE });
+        if (parsed.isValid)
+            return parsed.toISODate();
+    }
+    return null;
+}
+export function parseAsendiaTrackingResponse(payload, rawTrackingNumber) {
+    const parcel = selectParcel(payload, rawTrackingNumber);
+    const parsedEvents = parseEvents(parcel);
+    const events = parsedEvents.map(({ event }) => event);
+    const currentText = plainText(parcel.status)
+        || plainText(parcel.parcel_progress)
+        || events[0]?.description
+        || 'Tracking information received';
+    const current = classifyAsendiaStatus(currentText);
+    const latestKnown = parsedEvents.find((event) => event.status !== 'unknown');
+    const status = current.status !== 'unknown'
+        ? current.status
+        : latestKnown?.status ?? 'unknown';
+    return {
+        status,
+        last_status_text: events[0]?.description ?? currentText,
+        last_update: events[0]?.time ?? null,
+        expected_delivery: ['delivered', 'exception'].includes(status)
+            ? null
+            : expectedDelivery(parcel),
+        timezone: ZONE,
+        events,
+    };
+}
+function challengeToken(value) {
+    const token = cleanScalar(value, 4_096);
+    if (!/^[A-Za-z0-9._-]{20,4096}$/.test(token)) {
+        throw new ChallengeError('Asendia', 'Asendia requires a fresh Cloudflare Turnstile token');
+    }
+    return token;
+}
+function baseHeaders() {
+    return {
+        Accept: 'application/json',
+        'Accept-Language': 'en',
+        'Content-Type': 'application/json',
+        'x-tenant-id': 'track.asendia.com',
+        'X-Language': 'en',
+        'X-Timezone': ZONE,
+        Origin: TRACKING_ORIGIN,
+        Referer: `${TRACKING_PAGE}/`,
+        'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+    };
+}
+export class AsendiaTracker {
+    timeoutMs;
+    now;
+    turnstileTokenProvider;
+    fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.now = options.now ?? (() => new Date());
+        this.fetcher = options.fetcher;
+        this.turnstileTokenProvider = options.turnstileTokenProvider
+            ?? (() => '');
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Asendia timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizeAsendiaTrackingNumber(rawTrackingNumber);
+        const token = challengeToken(await this.turnstileTokenProvider());
+        const [environmentScript, configPayload] = await Promise.all([
+            this.requestText(ENVIRONMENT_SCRIPT, 'Asendia public environment'),
+            this.requestJson(CONFIG_API, { headers: baseHeaders() }, 'Asendia tracking configuration'),
+        ]);
+        const publicHitKey = parseAsendiaPublicHitKey(environmentScript);
+        const config = parseTenantConfig(configPayload);
+        const date = this.now().toISOString().slice(0, 10);
+        const hitToken = asendiaHitToken(trackingNumber, date, publicHitKey);
+        const payload = await this.requestJson(asendiaTrackingApiUrl(), {
+            method: 'POST',
+            headers: { ...baseHeaders(), 'X-Hit-Token': hitToken },
+            body: JSON.stringify({
+                ids: [trackingNumber],
+                id: config.id,
+                subsidiary: [config.subsidiary],
+                subsidiary_id: [config.subsidiaryId],
+                ...(config.brandId === '*' ? { brand_id: '*' } : { customer: config.brandId }),
+                turnstile_token: token,
+            }),
+        }, 'Asendia tracking');
+        const result = parseAsendiaTrackingResponse(payload, trackingNumber);
+        result.tracking_url = asendiaTrackingUrl(trackingNumber);
+        result.tracking_source = 'structured-web-response';
+        return result;
+    }
+    async requestText(url, provider) {
+        const { bytes } = await fetchBounded(url, {
+            headers: {
+                Accept: 'application/javascript,text/javascript,*/*;q=0.8',
+                Referer: `${TRACKING_PAGE}/`,
+            },
+        }, {
+            provider,
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            fetcher: this.fetcher,
+        });
+        return decodeText(bytes);
+    }
+    async requestJson(url, init, provider) {
+        const { response, bytes } = await fetchBounded(url, init, {
+            provider,
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            fetcher: this.fetcher,
+            allowHttpError: true,
+        });
+        const payload = bytes.byteLength > 0 ? parseJsonBytes(bytes, 'Asendia') : null;
+        if (response.status === 404)
+            throw new NotFoundError('Asendia');
+        if (response.status === 403 && provider === 'Asendia tracking') {
+            throw new ChallengeError('Asendia', 'Asendia rejected the Cloudflare Turnstile token');
+        }
+        if (response.status === 400 && isRecord(payload)
+            && /turnstile/i.test(cleanScalar(payload.summary, 256))) {
+            throw new ChallengeError('Asendia', 'Asendia rejected the Cloudflare Turnstile token');
+        }
+        if (!response.ok)
+            throw new UpstreamHttpError(provider, response.status);
+        return payload;
+    }
+}

package/dist/carriers/asendia/status.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Asendia event vocabularies → product stage.
+ *
+ * Two sources, two maps. `classifyAsendiaA1Event` serves the registered
+ * adapter (Asendia USA's A1 platform); `classifyAsendiaStatus` serves the
+ * global-portal probe.
+ *
+ * A1: Asendia's own scans carry numeric codes (`1`, `2`, `2.1`, …) and are
+ * mapped by code. Last-mile partners' scans arrive through the same list with
+ * the partner's codes, which differ by partner, so those are mapped by exact
+ * wording only where a fixture shows it. Anything else returns null and keeps
+ * no event stage, leaving it to the sync's shared wording rules and the
+ * unmapped-wording review.
+ *
+ * Global portal: Asendia's branded portal harmonizes the wording of every partner post into
+ * one English vocabulary (`harmonizedEvent`), which is what this map keys on;
+ * the numeric `harmonizedCode` is retained as the event's `provider_code` but
+ * is not used for mapping, because the same code has been observed with
+ * different harmonized wording across subsidiaries.
+ *
+ * Phrases are compared after lower-casing, stripping diacritics and collapsing
+ * everything that is not a letter or a digit. Order matters: return and
+ * failure phrases are tested before the delivery ones, so "not delivered" can
+ * never match the "delivered" substring. Wording the map does not recognize
+ * gets no carrier stage assignment beyond the transit default.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface ClassifiedAsendiaStatus {
+    status: CarrierStatus;
+    stage: Stage;
+}
+/** Lower-case, unaccent and reduce harmonized wording to letters, digits and single spaces. */
+export declare function comparableText(value: string): string;
+export declare function classifyAsendiaStatus(description: string): ClassifiedAsendiaStatus;
+/**
+ * The explicit mapping for one A1 event, or null when no map knows it. Codes
+ * are read only for Asendia's own sources: partners reuse short codes such as
+ * "10" or "B1" for unrelated scans.
+ */
+export declare function classifyAsendiaA1Event(source: string, code: string, description: string): ClassifiedAsendiaStatus | null;