universal-parcel-scraper 0.97.0-main.997 → 0.99.0-main.1001

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 **156 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **157 dedicated adapters** and **5 universal fallbacks**
 
 <sub>208 catalog entries · 66 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 4,357 such statuses, each filed under one stage.
+The carrier folders record 4,426 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

@@ -1983,7 +1983,11 @@
     "tracking": {
       "mode": "automatic",
       "adapter": "royal-mail",
-      "browserRecognitionRank": 900
+      "browserRecognitionRank": 900,
+      "refresh": {
+        "minMinutes": 60
+      },
+      "localClocks": true
     },
     "canaryUrl": "https://www.royalmail.com/track-your-item",
     "trackingUrlTemplate": "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",
@@ -8360,7 +8364,9 @@
     "color": "#fd4f00",
     "aliases": [
       "Whistl UK",
-      "TNT Post UK"
+      "TNT Post UK",
+      "Parcelhub",
+      "Whistl Despatch"
     ],
     "countries": [
       "GB"
@@ -8369,7 +8375,9 @@
     "timezone": "Europe/London",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "whistl",
+      "recognitionRank": 880,
+      "localClocks": true
     },
     "canaryUrl": "https://web.parcelhub.net/Tracking",
     "trackingUrlTemplate": "https://web.parcelhub.net/Tracking/reference/{trackingNumber}",
@@ -8377,9 +8385,10 @@
     "linkRules": [
       {
         "domains": [
-          "web.parcelhub.net"
+          "web.parcelhub.net",
+          "despatch.whistl.co.uk"
         ],
-        "path": "^/Tracking/reference/([^/?#]+)/?$"
+        "path": "^/Tracking/reference/([^/?#]+)(?:/postcode/[^/?#]*)?/?$"
       },
       {
         "domains": [

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 208,
-  "activeAdapters": 156,
+  "activeAdapters": 157,
   "countries": 66,
   "referenceCarriers": 100,
   "comparison": {

package/dist/browser/scraper.js

@@ -1724,7 +1724,9 @@ var be = {
 		tracking: {
 			mode: "automatic",
 			adapter: "royal-mail",
-			browserRecognitionRank: 900
+			browserRecognitionRank: 900,
+			refresh: { minMinutes: 60 },
+			localClocks: !0
 		},
 		canaryUrl: "https://www.royalmail.com/track-your-item",
 		trackingUrlTemplate: "https://www.royalmail.com/portal/rm/track?trackNumber={trackingNumber}",
@@ -6599,20 +6601,27 @@ var be = {
 	whistl: {
 		displayName: "Whistl",
 		color: "#fd4f00",
-		aliases: ["Whistl UK", "TNT Post UK"],
+		aliases: [
+			"Whistl UK",
+			"TNT Post UK",
+			"Parcelhub",
+			"Whistl Despatch"
+		],
 		countries: ["GB"],
 		selectable: !0,
 		timezone: "Europe/London",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "whistl",
+			recognitionRank: 880,
+			localClocks: !0
 		},
 		canaryUrl: "https://web.parcelhub.net/Tracking",
 		trackingUrlTemplate: "https://web.parcelhub.net/Tracking/reference/{trackingNumber}",
 		trackingSearchUrl: "https://web.parcelhub.net/Tracking",
 		linkRules: [{
-			domains: ["web.parcelhub.net"],
-			path: "^/Tracking/reference/([^/?#]+)/?$"
+			domains: ["web.parcelhub.net", "despatch.whistl.co.uk"],
+			path: "^/Tracking/reference/([^/?#]+)(?:/postcode/[^/?#]*)?/?$"
 		}, {
 			domains: ["trackmyitem.whistl.co.uk"],
 			path: "^/tracking/([^/?#]+)/?$"
@@ -12010,6 +12019,7 @@ var bc = {
 	uniuni: 330,
 	venipak: 630,
 	"vinted-go": 720,
+	whistl: 880,
 	"yurtici-kargo": 660
 }, xc = 5;
 function Sc(e) {

package/dist/carriers/royal-mail/carrier.json

@@ -20,7 +20,11 @@
     ],
     "browserRecognition": {
       "rank": 900
-    }
+    },
+    "refresh": {
+      "minMinutes": 60
+    },
+    "localClocks": true
   },
   "capabilities": [
     "history",

package/dist/carriers/royal-mail/identity.d.ts

@@ -0,0 +1,2 @@
+import type { SameInstantIdentityPolicy } from '../../core/catalog/eventIdentity.js';
+export declare const sameInstantIdentityPolicy: SameInstantIdentityPolicy;

package/dist/carriers/royal-mail/identity.js

@@ -0,0 +1,5 @@
+// Scans abroad kept the UK offset Royal Mail labels them with until October
+// 2026 and now show their country's, unless the country keeps several clocks.
+export const sameInstantIdentityPolicy = {
+    sourceCarrierId: 'royal-mail', storedSources: ['royal-mail'], requireProviderCode: true, relabelledFrom: 'Europe/London',
+};

package/dist/carriers/royal-mail/parser.js

@@ -2,7 +2,7 @@ import { DateTime } from 'luxon';
 import { load } from 'cheerio';
 import { ChallengeError, IndeterminateError, InvalidInputError, RateLimitedError, SchemaError } from '../../core/errors/index.js';
 import { clean, cleanScalar } from '../../core/transport/index.js';
-import { explicitOffsetTime } from '../../core/time/index.js';
+import { countryCode, countryTimeZone, explicitOffsetTime, isoTime } from '../../core/time/index.js';
 import { isRecord } from '../../core/types.js';
 import { isRoyalMailDomesticReference } from '../../core/detection/royalMail.js';
 import { isValidS10TrackingNumber } from '../../core/detection/s10.js';
@@ -41,6 +41,22 @@ function eventTime(value) {
         return null;
     return explicitOffsetTime(raw)?.iso ?? null;
 }
+/**
+ * A scan abroad names its country after the place, and Royal Mail labels that
+ * office's wall clock with the UK's offset. The clock is read in the country's
+ * zone, or kept as a wall clock when the country has several; null at home.
+ */
+function abroadClock(raw, location) {
+    const country = countryCode(/,\s*([^,]+)$/.exec(location)?.[1]);
+    if (!country || country === 'GB' || !eventTime(raw))
+        return null;
+    const wall = DateTime.fromISO(raw, { setZone: true }).toISO({ includeOffset: false, suppressMilliseconds: true });
+    if (!wall)
+        return null;
+    const zone = countryTimeZone(country);
+    const placed = zone ? isoTime(wall, zone) : null;
+    return placed ? { time: placed.iso } : { local_time: wall };
+}
 // Royal Mail appends a Post Office branch's postcode in brackets, and an
 // overseas partner can report a delivery office by postcode alone.
 const POSTCODE = /^(?:[A-Z]{1,2}\d[A-Z\d]? ?\d[A-Z]{2}|\d{3,10}(?:-\d{3,4})?)$/i;
@@ -78,13 +94,14 @@ export function parseRoyalMailTrackingResponse(payload, trackingNumber) {
         throw new SchemaError('Royal Mail', 'Royal Mail did not return the requested parcel');
     }
     const summary = mailpiece.summary;
-    const summaryText = cleanScalar(summary.statusDescription);
+    const summaryText = cleanScalar(summary.statusDescription).replace(/\*\*/g, '').trim();
     if (mailpiece.events !== undefined && !Array.isArray(mailpiece.events)) {
         throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
     }
     const scans = Array.isArray(mailpiece.events) ? mailpiece.events : [];
     const events = [];
     const seen = new Set();
+    const abroad = new Map();
     for (const raw of scans.slice(0, MAX_EVENTS_TO_INSPECT)) {
         if (!isRecord(raw))
             throw new SchemaError('Royal Mail', 'Royal Mail returned invalid tracking events');
@@ -96,12 +113,15 @@ export function parseRoyalMailTrackingResponse(payload, trackingNumber) {
         const code = cleanScalar(raw.eventCode, 64);
         const mapped = royalMailEventStage(code);
         const stage = mapped ?? royalMailStage(description) ?? undefined;
-        const time = eventTime(raw.eventDateTime);
         const timeText = cleanScalar(raw.eventDateTime, 64);
         const location = placeName(raw.locationName);
+        const clock = abroadClock(timeText, location);
+        if (clock && !abroad.has(timeText))
+            abroad.set(timeText, clock);
+        const time = clock ? ('time' in clock ? clock.time : null) : eventTime(raw.eventDateTime);
         const event = {
-            ...(time ? { time } : {}),
-            ...(!time && timeText ? { provider_time_text: timeText } : {}),
+            ...(clock ?? (time ? { time } : {})),
+            ...(!time && !clock && timeText ? { provider_time_text: timeText } : {}),
             ...(location ? { location } : {}),
             description: stage === 'delivered' ? 'Delivered' : description,
             ...(stage ? { stage } : {}),
@@ -127,15 +147,19 @@ export function parseRoyalMailTrackingResponse(payload, trackingNumber) {
         throw new SchemaError('Royal Mail', 'Royal Mail returned no usable tracking status');
     const stage = royalMailSummaryStage(summaryCategory, statusText) ?? undefined;
     const delivered = stage === 'delivered';
+    // The summary repeats the newest scan's label, which a scan abroad corrects.
+    const lastText = cleanScalar(summary.lastEventDateTime, 64);
+    const lastClock = abroad.get(lastText);
+    const lastTime = lastClock ? ('time' in lastClock ? lastClock.time : null) : eventTime(lastText);
     const deliveredAt = !delivered ? null : trimmed.find(event => event.stage === 'delivered' && event.time)?.time
-        ?? (royalMailEventStage(cleanScalar(summary.lastEventCode, 64)) === 'delivered' ? eventTime(summary.lastEventDateTime) : null);
+        ?? (royalMailEventStage(cleanScalar(summary.lastEventCode, 64)) === 'delivered' ? lastTime : null);
     // Only the full-history reply names the destination.
     const destination = cleanScalar(summary.destinationCountryCode, 8);
     return {
         status: stage ? statusForStage(stage) : 'unknown',
         ...(stage ? { current_stage: stage } : {}),
         last_status_text: delivered ? 'Delivered' : statusText,
-        last_update: eventTime(summary.lastEventDateTime) || trimmed[0]?.time || null,
+        last_update: lastClock ? lastTime : lastTime || trimmed[0]?.time || null,
         expected_delivery: delivered || !isRecord(mailpiece.estimatedDelivery)
             ? null : expectedDelivery(mailpiece.estimatedDelivery.date),
         ...(deliveredAt ? { delivered_at: deliveredAt } : {}),

package/dist/carriers/royal-mail/status.js

@@ -28,6 +28,8 @@ const EVENT_STAGES = new Map([
     ['EVHOE', 'in_transit'],
     ['EVIIS', 'in_transit'],
     ['EVBAH', 'in_transit'],
+    ['EVJOE', 'in_transit'],
+    ['EVJDU', 'in_transit'],
     ['EVCAD', 'accepted'],
     ['EVPPA', 'accepted'],
     ['EVAIP', 'registered'],

package/dist/carriers/royal-mail/statuses.json

@@ -257,6 +257,24 @@
       "confirmedBy": "live",
       "firstSeen": "2026-10-08",
       "note": "Same notice as EVAIP."
+    },
+    {
+      "code": "EVJOE",
+      "wording": "Item Received",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-12",
+      "note": "Arrival at the destination country's office of exchange; the shared wording alone would read as acceptance."
+    },
+    {
+      "code": "EVJDU",
+      "wording": "Item has left the overseas International Processing Centre",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-12",
+      "note": "Departure from the destination country's office of exchange."
     }
   ]
 }

package/dist/carriers/whistl/adapter.d.ts

@@ -0,0 +1,14 @@
+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';
+export declare const WHISTL_ENDPOINT = "https://web.parcelhub.net/Tracking/reference/";
+export declare class WhistlTracker {
+    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/whistl/adapter.js

@@ -0,0 +1,54 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { IndeterminateError, 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 { normalizeWhistlNumber, parseWhistl, PROVIDER, WHISTL_MAX_BYTES } from './parser.js';
+// Whistl's parcel tracker on its Parcelhub platform, which Whistl's site links
+// and whose form opens a reference at this path. No postcode is sent: the
+// tracker takes it only to narrow the search.
+export const WHISTL_ENDPOINT = 'https://web.parcelhub.net/Tracking/reference/';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// A missing route is not a missing parcel: the tracker answers unknown references with a heading.
+const GONE = [404, 410];
+export class WhistlTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeWhistlNumber(raw);
+        const url = `${WHISTL_ENDPOINT}${encodeURIComponent(number)}`;
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(url, { method: 'GET', signal, headers: {
+                    Accept: 'text/html,application/xhtml+xml',
+                    'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: WHISTL_MAX_BYTES,
+                redirect: 'manual', allowHttpStatuses: [...REDIRECTS, ...GONE], fetcher: this.options.fetcher });
+            if (REDIRECTS.includes(response.status))
+                throw new IndeterminateError(PROVIDER, 'Whistl sent the lookup to another page');
+            if (GONE.includes(response.status))
+                throw new TransportError(PROVIDER, 'Whistl tracking page is unavailable');
+            const html = decodeText(bytes);
+            if (!html.trim())
+                throw new IndeterminateError(PROVIDER, 'Whistl returned an empty page');
+            return parseWhistl(html, number);
+        };
+        // A request that fails to reach Whistl, or hangs, gets one more try: the
+        // first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'whistl', 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 WhistlTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'whistl', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeWhistlNumber(number))),
+    };
+};

package/dist/carriers/whistl/carrier.json

@@ -3,7 +3,9 @@
   "displayName": "Whistl",
   "aliases": [
     "Whistl UK",
-    "TNT Post UK"
+    "TNT Post UK",
+    "Parcelhub",
+    "Whistl Despatch"
   ],
   "region": {
     "countries": [
@@ -17,25 +19,66 @@
   "timezone": "Europe/London",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "whistl",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 880
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "service_name",
+    "delivery_partner",
+    "delivery_tracking_number",
+    "canonical_tracking_number"
+  ],
   "portal": {
     "url": "https://web.parcelhub.net/Tracking/reference/{trackingNumber}",
     "searchUrl": "https://web.parcelhub.net/Tracking",
     "canaryUrl": "https://web.parcelhub.net/Tracking",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "service_name",
+      "delivery_partner",
+      "delivery_tracking_number",
+      "sender_reference",
+      "recipient_reference"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "service_name",
+      "delivery_partner",
+      "delivery_tracking_number"
+    ],
+    "discarded": [
+      "sender_reference",
+      "recipient_reference",
+      "signatory"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "sender_name",
+      "recipient_name",
+      "offset_timestamps"
+    ]
   },
   "links": [
     {
       "domains": [
-        "web.parcelhub.net"
+        "web.parcelhub.net",
+        "despatch.whistl.co.uk"
       ],
-      "path": "^/Tracking/reference/([^/?#]+)/?$"
+      "path": "^/Tracking/reference/([^/?#]+)(?:/postcode/[^/?#]*)?/?$"
     },
     {
       "domains": [

package/dist/carriers/whistl/numbers.json

@@ -12,13 +12,13 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
         "confidence": "none"
       },
-      "note": "A review on Whistl's Trustpilot page gives it as the tracking number."
+      "note": "A review on Whistl's Trustpilot page gives it as the tracking number. Whistl's Parcelhub tracker knows it as a shipment reference whose one parcel another carrier delivers under its own number."
     },
     {
       "number": "L1213411000055365001",

package/dist/carriers/whistl/parser.d.ts

@@ -0,0 +1,14 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Whistl";
+export declare const WHISTL_MAX_BYTES = 1000000;
+/** A reference as Whistl's tracker takes it: letters and digits, at least one digit. */
+export declare function normalizeWhistlNumber(raw: string): string;
+/**
+ * Whistl's tracker page for one shipment reference or tracking number: the
+ * shipment's reference as its heading, the carrier and service, and for each
+ * parcel its tracking number and scans, newest first. The tracker finds a
+ * shipment by its reference or by a parcel's tracking number, so the page
+ * must name the requested number as one of them. Sender's and recipient's
+ * references, signatories and comments are never read.
+ */
+export declare function parseWhistl(html: string, rawNumber: string): CarrierResult;