universal-parcel-scraper 0.554.0-main.2562 → 0.556.0-main.2575

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **598 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **600 dedicated adapters** and **5 universal fallbacks**
 
 <sub>774 catalog entries · 134 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 16,040 such statuses, each filed under one stage.
+The carrier folders record 16,079 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/catalog.json

@@ -2339,6 +2339,11 @@
     "trackingSearchUrl": "https://www.post.at/en/s/track-and-trace-search",
     "linkRules": [],
     "detectionRules": [
+      {
+        "pattern": "^10\\d{20}$",
+        "confidence": "low",
+        "preferred": true
+      },
       {
         "pattern": "^\\d{22}$",
         "confidence": "low"
@@ -3871,7 +3876,6 @@
     "tracking": {
       "mode": "automatic",
       "adapter": "sf-express",
-      "localClocks": true,
       "browser": true
     },
     "canaryUrl": "https://htm.sf-express.com/tw/en/dynamic_function/waybill/",
@@ -9020,7 +9024,9 @@
     "timezone": "Asia/Kuala_Lumpur",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "citylink-express",
+      "recognitionRank": 533,
+      "localClocks": true
     },
     "canaryUrl": "https://www.citylinkexpress.com/track-your-shipment/",
     "trackingUrlTemplate": "https://www.citylinkexpress.com/tracking-result/?track0={trackingNumber}",
@@ -13595,7 +13601,8 @@
     "timezone": "America/Chicago",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "fedex-freight",
+      "localClocks": true
     },
     "canaryUrl": "https://www.fedexfreight.com/en-us/tracking",
     "trackingUrlTemplate": "https://www.fedexfreight.com/fedextrack/?trknbr={trackingNumber}",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 774,
-  "activeAdapters": 598,
+  "activeAdapters": 600,
   "countries": 134,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -10469,6 +10469,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -10923,6 +10926,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -10990,6 +10996,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -11232,6 +11241,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -11423,6 +11435,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -11476,6 +11491,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -11489,6 +11507,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -11502,6 +11523,9 @@
       "usps",
       "estafeta"
     ],
+    "preferred": [
+      "austrian-post"
+    ],
     "asked": [
       "austrian-post"
     ]
@@ -85975,6 +85999,14 @@
       "sf-express"
     ]
   },
+  {
+    "input": "SF6047696957042",
+    "carrier": "sf-express",
+    "confidence": "high",
+    "candidates": [
+      "sf-express"
+    ]
+  },
   {
     "input": "SF6047789135544",
     "carrier": "sf-express",
@@ -85983,6 +86015,30 @@
       "sf-express"
     ]
   },
+  {
+    "input": "SF6047826456714",
+    "carrier": "sf-express",
+    "confidence": "high",
+    "candidates": [
+      "sf-express"
+    ]
+  },
+  {
+    "input": "SF6047918078324",
+    "carrier": "sf-express",
+    "confidence": "high",
+    "candidates": [
+      "sf-express"
+    ]
+  },
+  {
+    "input": "SF6047933110963",
+    "carrier": "sf-express",
+    "confidence": "high",
+    "candidates": [
+      "sf-express"
+    ]
+  },
   {
     "input": "SF632454478AJI",
     "carrier": "shadowfax",

package/dist/browser/scraper.js

@@ -2152,6 +2152,11 @@ var Je = {
 		trackingSearchUrl: "https://www.post.at/en/s/track-and-trace-search",
 		linkRules: [],
 		detectionRules: [
+			{
+				pattern: "^10\\d{20}$",
+				confidence: "low",
+				preferred: !0
+			},
 			{
 				pattern: "^\\d{22}$",
 				confidence: "low"
@@ -3367,7 +3372,6 @@ var Je = {
 		tracking: {
 			mode: "automatic",
 			adapter: "sf-express",
-			localClocks: !0,
 			browser: !0
 		},
 		canaryUrl: "https://htm.sf-express.com/tw/en/dynamic_function/waybill/",
@@ -7177,7 +7181,9 @@ var Je = {
 		timezone: "Asia/Kuala_Lumpur",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "citylink-express",
+			recognitionRank: 533,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.citylinkexpress.com/track-your-shipment/",
 		trackingUrlTemplate: "https://www.citylinkexpress.com/tracking-result/?track0={trackingNumber}",
@@ -10533,7 +10539,8 @@ var Je = {
 		timezone: "America/Chicago",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "fedex-freight",
+			localClocks: !0
 		},
 		canaryUrl: "https://www.fedexfreight.com/en-us/tracking",
 		trackingUrlTemplate: "https://www.fedexfreight.com/fedextrack/?trknbr={trackingNumber}",
@@ -23633,6 +23640,7 @@ var Je = {
 		"bpost-jjbe"
 	],
 	"austrian-post": [
+		"austrian-post-4",
 		"austrian-post-1",
 		"austrian-post-3",
 		"austrian-post-2"
@@ -29790,6 +29798,7 @@ var Al = {
 	chunil: 621,
 	ciblex: 640,
 	"city-express-rs": 817,
+	"citylink-express": 533,
 	citymail: 868,
 	"cj-logistics": 977,
 	"cj-packet": 956,

package/dist/carriers/austrian-post/carrier.json

@@ -65,6 +65,12 @@
   },
   "links": [],
   "detection": [
+    {
+      "id": "austrian-post-4",
+      "pattern": "^10\\d{20}$",
+      "confidence": "low",
+      "preferred": true
+    },
     {
       "id": "austrian-post-1",
       "pattern": "^\\d{22}$",

package/dist/carriers/cacesa/status.js

@@ -13,9 +13,11 @@ const EVENTS = {
     // Customs released the parcel.
     ico_okaduana: 'in_transit',
 };
-// Incidents CACESA names by icon: customs holding the parcel for inspection.
+// Incidents CACESA names by icon: customs holding the parcel for inspection,
+// or for the documents it checks ("ko" beside the customs icon).
 const INCIDENTS = {
     ico_aduana: 'exception',
+    ico_aduanako: 'exception',
 };
 /** The provider code of a milestone: its type, a slash and its icon ("EVENTO/ico_aduana"). */
 export function cacesaCode(type, icon) {

package/dist/carriers/cacesa/statuses.json

@@ -7,6 +7,7 @@
     { "code": "EVENTO/ico_aduana", "wording": "Start Custom clearance Process", "language": "en", "stage": "customs", "confirmedBy": "live" },
     { "code": "EVENTO/ico_okaduana", "wording": "Customs cleared-Green channel", "language": "en", "stage": "in_transit", "confirmedBy": "live", "note": "Customs released the parcel." },
     { "code": "EVENTO/ico_subirdocu", "wording": "Customs document required uploaded", "language": "en", "stage": "customs", "confirmedBy": "live", "note": "The recipient uploaded the document customs asked for." },
-    { "code": "INCIDENCIA/ico_aduana", "wording": "Shipment held in warehouse for inspection", "language": "en", "stage": "exception", "confirmedBy": "live", "note": "An incident: customs holds the parcel for inspection." }
+    { "code": "INCIDENCIA/ico_aduana", "wording": "Shipment held in warehouse for inspection", "language": "en", "stage": "exception", "confirmedBy": "live", "note": "An incident: customs holds the parcel for inspection." },
+    { "code": "INCIDENCIA/ico_aduanako", "wording": "Held by customs-documentary verification", "language": "en", "stage": "exception", "confirmedBy": "live", "firstSeen": "2026-10-19", "note": "An incident: customs holds the parcel until it has checked the shipment's documents." }
   ]
 }

package/dist/carriers/citylink-express/adapter.d.ts

@@ -0,0 +1,15 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+/** The lookup the tracking-result page on citylinkexpress.com makes for the number in its address. */
+export declare const CITYLINK_API = "https://www.citylinkexpress.com/wp-json/wp/v2/getTracking";
+export declare class CitylinkTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/citylink-express/adapter.js

@@ -0,0 +1,73 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { firstAttemptMs, networkRetryStep } from '../../core/runner/networkRetry.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { CITYLINK_MAX_BYTES, isCitylinkNotFound, normalizeCitylinkNumber, parseCitylink, PROVIDER } from './parser.js';
+/** The lookup the tracking-result page on citylinkexpress.com makes for the number in its address. */
+export const CITYLINK_API = 'https://www.citylinkexpress.com/wp-json/wp/v2/getTracking';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// Bot checks Cloudflare, in front of the site, could put in place of the reply.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|<title>\s*(?:Just a moment|Attention Required)|cf-error-details/i;
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'City-Link answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'City-Link returned a reply that is not JSON', { cause });
+    }
+}
+export class CitylinkTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeCitylinkNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(CITYLINK_API, { method: 'POST', signal, headers: {
+                    Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+                    'User-Agent': userAgentOf(this.options.userAgent),
+                }, body: new URLSearchParams({ tracking: number, xr_option: 'false' }).toString() }, { provider: PROVIDER,
+                timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: CITYLINK_MAX_BYTES, redirect: 'manual',
+                fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'City-Link redirected its tracking lookup');
+            if (response.status === 404) {
+                // The tracker's own answer for a number it has no record of; any other
+                // 404, such as WordPress's for a route it no longer has, is a moved route.
+                let payload;
+                try {
+                    payload = JSON.parse(decodeText(bytes));
+                }
+                catch {
+                    payload = undefined;
+                }
+                if (isCitylinkNotFound(payload))
+                    throw new NotFoundError(PROVIDER);
+                throw new TransportError(PROVIDER, 'City-Link tracking lookup is unavailable');
+            }
+            if (response.status === 410)
+                throw new TransportError(PROVIDER, 'City-Link tracking lookup is unavailable');
+            return parseCitylink(json(decodeText(bytes)), number);
+        };
+        // A request that fails to reach the site, or hangs, gets one more try: the
+        // first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'citylink-express', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, firstAttemptMs(remainingMs)) },
+            networkRetryStep(({ signal, remainingMs }) => read(signal, remainingMs)),
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CitylinkTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'citylink-express', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCitylinkNumber(number))),
+    };
+};

package/dist/carriers/citylink-express/carrier.json

@@ -19,18 +19,69 @@
   "timezone": "Asia/Kuala_Lumpur",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "citylink-express",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 533
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "provider_code",
+    "location",
+    "delivered_at",
+    "weight"
+  ],
   "portal": {
     "url": "https://www.citylinkexpress.com/tracking-result/?track0={trackingNumber}",
     "searchUrl": "https://www.citylinkexpress.com/track-your-shipment/",
     "canaryUrl": "https://www.citylinkexpress.com/track-your-shipment/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "progress_rail",
+      "history",
+      "location",
+      "origin",
+      "destination",
+      "customer_reference",
+      "item_category",
+      "parcel_count",
+      "related_tracking_numbers",
+      "driver_name",
+      "signatory",
+      "proof_of_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code",
+      "delivered_at",
+      "weight"
+    ],
+    "discarded": [
+      "progress_rail",
+      "origin",
+      "destination",
+      "customer_reference",
+      "item_category",
+      "parcel_count",
+      "related_tracking_numbers",
+      "driver_name",
+      "signatory",
+      "proof_of_delivery"
+    ],
+    "unavailable": [
+      "eta",
+      "service_name",
+      "offset_timestamps",
+      "sender_name",
+      "recipient_name"
+    ]
   },
   "links": [
     {

package/dist/carriers/citylink-express/parser.d.ts

@@ -0,0 +1,22 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "City-Link Express";
+export declare const CITYLINK_MAX_BYTES: number;
+/** A City-Link consignment number; anything else is not one City-Link issues. */
+export declare function normalizeCitylinkNumber(raw: string): string;
+/**
+ * A scan's wording as the page shows it, without the `SR - ` the page drops,
+ * the courier or the person who signed, or phone numbers.
+ */
+export declare function citylinkWording(raw: string): string;
+/** A scan's code: `CP_Code`, with its `DisposeCode` after a colon when it has one, as `SP:60`. */
+export declare function citylinkCode(row: Record<string, unknown>): string;
+/** Whether a reply is the tracker's own answer for a number it has no record of. */
+export declare function isCitylinkNotFound(payload: unknown): boolean;
+/**
+ * The reply of the tracking page's `/wp-json/wp/v2/getTracking` for one
+ * number: City-Link's answer in `req.data`, its scans oldest first. A number it
+ * has no record of is an HTTP 404 instead (see `isCitylinkNotFound`). The
+ * shipment must name the number asked. Only its number, weight and scans are
+ * read.
+ */
+export declare function parseCitylink(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/citylink-express/parser.js

@@ -0,0 +1,178 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { countryTimeZone, firstOccurrence, sharedClockZone } from '../../core/time/index.js';
+import { clean, cleanScalar } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { citylinkStage } from './status.js';
+export const PROVIDER = 'City-Link Express';
+// A long history is a few kilobytes.
+export const CITYLINK_MAX_BYTES = 256 * 1024;
+// The tracker asks for the fifteen digits of the consignment note.
+const NUMBER = /^\d{15}$/;
+// City-Link's own clock: its system and its Malaysian branches keep Malaysia's.
+const ZONE = 'Asia/Kuala_Lumpur';
+const DATE = /^(\d{2})\/(\d{2})\/(\d{4})$/;
+const CLOCK = /^(\d{2})(\d{2})(\d{2})$/;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/** A City-Link consignment number; anything else is not one City-Link issues. */
+export function normalizeCitylinkNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'City-Link consignment numbers are fifteen digits');
+    return number;
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 300) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `City-Link returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+// The courier a scan names after its label: "With City-Link delivery courier: …".
+const COURIER = /\b(courier|rider|driver)\s*:[\s\S]*$/i;
+// Who took the parcel, after the scan's own words: "Package Delivered - Signed for by: …".
+const RECEIVER = /\s*[,;:\-–(]?\s*\b(signed for by|received by|collected by|delivered to)\b\s*:?\s*\S[\s\S]*$/i;
+// A run of nine or more digits, with spaces, brackets, dots or hyphens
+// between them, as phone numbers are written.
+const PHONE = /(?<![A-Z\d])\+?\d(?:[\s().-]{0,2}\d){8,}(?![A-Z\d])/gi;
+/**
+ * A scan's wording as the page shows it, without the `SR - ` the page drops,
+ * the courier or the person who signed, or phone numbers.
+ */
+export function citylinkWording(raw) {
+    let own = clean(raw).replace(/\bSR - /g, '').replace(COURIER, '$1').replace(PHONE, '');
+    const receiver = RECEIVER.exec(own);
+    // A wording that is only the label keeps it.
+    if (receiver)
+        own = own.slice(0, receiver.index).trim() || receiver[1];
+    return clean(own).replace(/^[\s,;:.\-–]+|[\s,;:\-–]+$/g, '');
+}
+/** A scan's `detDate` (`DD/MM/YYYY`) and `detTime` (`HHmmss`) as an offset-less wall clock. */
+function wallClock(row) {
+    const date = DATE.exec(text(row, 'detDate', 16));
+    const clock = CLOCK.exec(text(row, 'detTime', 16));
+    const wall = date && clock ? `${date[3]}-${date[2]}-${date[1]}T${clock[1]}:${clock[2]}:${clock[3]}` : '';
+    // Parsing in UTC checks the calendar digits only. Luxon rolls 24:00:00 over to the next day.
+    const checked = DateTime.fromISO(wall, { zone: 'UTC' });
+    if (!wall || !checked.isValid || checked.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== wall) {
+        throw new SchemaError(PROVIDER, 'City-Link returned an invalid scan time');
+    }
+    return wall;
+}
+/**
+ * A scan's instant, when its place settles the clock: the country after the
+ * location's last comma keeps Malaysia's clock at that moment, so the reading
+ * is the same whether the branch or City-Link's system stamped it. Malaysia,
+ * Singapore and Brunei do; elsewhere, or without a location, the wall clock
+ * stays local.
+ */
+function scanInstant(wall, location) {
+    const comma = location.lastIndexOf(',');
+    const zone = comma < 0 ? null : countryTimeZone(location.slice(comma + 1).trim());
+    const shared = zone ? sharedClockZone([ZONE, zone], wall) : null;
+    return shared ? firstOccurrence(DateTime.fromISO(wall, { zone: shared })).toISO({ suppressMilliseconds: true }) : null;
+}
+/** A scan's code: `CP_Code`, with its `DisposeCode` after a colon when it has one, as `SP:60`. */
+export function citylinkCode(row) {
+    const code = cleanScalar(row.CP_Code, 16).toUpperCase();
+    const disposal = cleanScalar(row.DisposeCode, 16).toUpperCase();
+    return code && disposal ? `${code}:${disposal}` : code;
+}
+function projectRow(row) {
+    const description = citylinkWording(text(row, 'status', 500));
+    if (!description)
+        throw new SchemaError(PROVIDER, 'City-Link returned a scan without wording');
+    const wall = wallClock(row);
+    const location = text(row, 'location', 120);
+    const time = scanInstant(wall, location);
+    const code = citylinkCode(row);
+    const staged = citylinkStage(code, description);
+    const event = {
+        ...(time ? { time } : { local_time: wall }),
+        ...(location ? { location } : {}),
+        description,
+        ...(code ? { provider_code: code } : {}),
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+    return { key: JSON.stringify([wall, code, description, location]), wall, event };
+}
+/** The weight in kilograms the reply gives as a decimal string; none when it is missing or zero. */
+function weight(data) {
+    const value = cleanScalar(data.weight, 16);
+    const kilograms = /^\d{1,5}(?:\.\d{1,3})?$/.test(value) ? Number(value) : 0;
+    return kilograms > 0 ? kilograms : null;
+}
+/** Whether a reply is the tracker's own answer for a number it has no record of. */
+export function isCitylinkNotFound(payload) {
+    return isRecord(payload) && typeof payload.error === 'string' && /^no tracking data found\.?$/i.test(payload.error.trim());
+}
+/**
+ * The reply of the tracking page's `/wp-json/wp/v2/getTracking` for one
+ * number: City-Link's answer in `req.data`, its scans oldest first. A number it
+ * has no record of is an HTTP 404 instead (see `isCitylinkNotFound`). The
+ * shipment must name the number asked. Only its number, weight and scans are
+ * read.
+ */
+export function parseCitylink(payload, raw) {
+    const number = normalizeCitylinkNumber(raw);
+    const request = isRecord(payload) ? payload.req : undefined;
+    if (!isRecord(request) || !Object.hasOwn(request, 'data'))
+        throw new SchemaError(PROVIDER, 'City-Link returned an invalid envelope');
+    if (request.status !== undefined && request.status !== 200)
+        throw new IndeterminateError(PROVIDER, 'City-Link did not complete the lookup');
+    const data = request.data;
+    if (!isRecord(data) || typeof data.returncode !== 'string')
+        throw new SchemaError(PROVIDER, 'City-Link returned a reply without its result code');
+    // The page reports any other code as no details found; the tracker's own
+    // answer for an unknown number is the 404, so another code is inconclusive.
+    if (data.returncode !== '00')
+        throw new IndeterminateError(PROVIDER, 'City-Link did not complete the lookup');
+    if (typeof data.trackingNo !== 'string')
+        throw new SchemaError(PROVIDER, 'City-Link returned a shipment without its number');
+    if (normalizeTrackingNumber(clean(data.trackingNo, 64)) !== number)
+        throw new IndeterminateError(PROVIDER, 'City-Link answered for another shipment');
+    const rows = data.trackDetails;
+    if (!Array.isArray(rows))
+        throw new SchemaError(PROVIDER, 'City-Link returned a shipment with invalid scans');
+    if (rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'City-Link returned an oversized history');
+    const seen = new Set();
+    const scans = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'City-Link returned an invalid scan');
+        const scan = projectRow(row);
+        if (seen.has(scan.key))
+            continue;
+        seen.add(scan.key);
+        scans.push(scan);
+    }
+    if (!scans.length)
+        throw new NoHistoryError(PROVIDER);
+    // Newest first, as the page lists them; it turns the reply's order round.
+    if (scans[0].wall < scans.at(-1).wall)
+        scans.reverse();
+    const events = scans.map((scan) => scan.event);
+    const newest = events[0];
+    const current = events.find((event) => event.stage);
+    const stage = current?.stage;
+    const deliveredAt = stage === 'delivered' ? current.time : undefined;
+    const kilograms = weight(data);
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: current.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: newest.time ?? null,
+        ...(newest.time ? {} : { last_update_local: newest.local_time }),
+        expected_delivery: null,
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        ...(kilograms ? { weight_kg: kilograms } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/citylink-express/status.d.ts

@@ -0,0 +1,7 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage City-Link's own vocabulary gives a scan: its code, else its wording. */
+export declare function citylinkMappedStage(code: string | null, wording: string): Stage | undefined;
+/** A scan's stage: its code or wording, else the shared wording rules, else nothing. */
+export declare function citylinkStage(code: string, wording: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;