universal-parcel-scraper 0.25.2-main.365 → 0.25.3-main.367

package/data/catalog.json

@@ -461,7 +461,7 @@
         "confidence": "high"
       },
       {
-        "pattern": "^00340434\\d{12}$",
+        "pattern": "^0034043[45]\\d{12}$",
         "confidence": "high"
       },
       {

package/data/detection-golden.json

@@ -155,6 +155,14 @@
       "dhl"
     ]
   },
+  {
+    "input": "00340435061352161527",
+    "carrier": "dhl",
+    "confidence": "high",
+    "candidates": [
+      "dhl"
+    ]
+  },
   {
     "input": "00573132901903503247",
     "carrier": "unknown",
@@ -2612,6 +2620,27 @@
       "dpd-fr"
     ]
   },
+  {
+    "input": "2522622410",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "dhl-express",
+      "dhl",
+      "mondial-relay",
+      "relais-colis",
+      "tipsa",
+      "estafeta"
+    ],
+    "preferred": [
+      "dhl-express"
+    ],
+    "asked": [
+      "dhl-express",
+      "relais-colis",
+      "tipsa"
+    ]
+  },
   {
     "input": "25631818",
     "carrier": "unknown",

package/dist/browser/scraper.js

@@ -464,7 +464,7 @@ var le = {
 				confidence: "high"
 			},
 			{
-				pattern: "^00340434\\d{12}$",
+				pattern: "^0034043[45]\\d{12}$",
 				confidence: "high"
 			},
 			{

package/dist/carriers/dhl/carrier.json

@@ -101,7 +101,7 @@
     },
     {
       "id": "dhl-5",
-      "pattern": "^00340434\\d{12}$",
+      "pattern": "^0034043[45]\\d{12}$",
       "confidence": "high"
     },
     {

package/dist/carriers/dhl/numbers.json

@@ -15,6 +15,23 @@
       },
       "note": "Publicly reported shipment number; the attribution was not independently verified."
     },
+    {
+      "number": "00340435061352161527",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://de.trustpilot.com/review/www.dhl.de",
+        "date": "2026-10-07"
+      },
+      "context": {
+        "assessment": "confirmed"
+      },
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number in the second 0034043 range; DHL's recipient endpoint returned its history."
+    },
     {
       "number": "8449089972",
       "role": "shipment",

package/dist/carriers/dhl-express/clock.d.ts

@@ -1,8 +1,8 @@
 /**
- * The zone of a DHL Express facility, from its location: "CITY - COUNTRY", or
- * "CITY - REGION - COUNTRY" in the USA and Canada. Null when the location does
- * not settle one: a country with several clocks and no region DHL names, or a
- * country it writes in a form this does not know.
+ * The zone of a DHL Express facility, from its location: "CITY - COUNTRY", and
+ * in the USA and Canada "CITY - REGION - COUNTRY" or "CITY, ST - COUNTRY". Null
+ * when the location does not settle one: a country with several clocks and no
+ * region DHL names, or a country it writes in a form this does not know.
  *
  * A US state or Canadian province with several clocks takes its majority zone.
  * Spain and Portugal take their mainland's, except for a town or island of the

package/dist/carriers/dhl-express/clock.js

@@ -16,6 +16,12 @@ const CANADA_PROVINCES = {
     'NOVA SCOTIA': 'NS', 'NORTHWEST TERRITORIES': 'NT', NUNAVUT: 'NU', ONTARIO: 'ON', 'PRINCE EDWARD ISLAND': 'PE',
     QUEBEC: 'QC', SASKATCHEWAN: 'SK', YUKON: 'YT',
 };
+// DHL's own names for countries the English ones do not cover: the forms on its
+// scans, and those of its country list for the countries whose zone is known.
+const COUNTRIES = {
+    UK: 'GB', "PEOPLE'S REPUBLIC OF CHINA": 'CN', 'CHINA, PEOPLES REPUBLIC': 'CN', 'CZECH REPUBLIC': 'CZ',
+    'IRELAND, REPUBLIC OF': 'IE', 'KOREA, REPUBLIC OF (SOUTH K.)': 'KR', TURKEY: 'TR',
+};
 // Island groups an hour behind their mainland, which DHL files under the country.
 const ISLANDS = {
     'Europe/Madrid': { group: 'ES-CN', zone: 'Atlantic/Canary' },
@@ -26,10 +32,10 @@ function regionCode(region, names) {
     return parts.find((part) => /^[A-Z]{2}$/.test(part)) ?? parts.map((part) => names[part]).find(Boolean) ?? '';
 }
 /**
- * The zone of a DHL Express facility, from its location: "CITY - COUNTRY", or
- * "CITY - REGION - COUNTRY" in the USA and Canada. Null when the location does
- * not settle one: a country with several clocks and no region DHL names, or a
- * country it writes in a form this does not know.
+ * The zone of a DHL Express facility, from its location: "CITY - COUNTRY", and
+ * in the USA and Canada "CITY - REGION - COUNTRY" or "CITY, ST - COUNTRY". Null
+ * when the location does not settle one: a country with several clocks and no
+ * region DHL names, or a country it writes in a form this does not know.
  *
  * A US state or Canadian province with several clocks takes its majority zone.
  * Spain and Portugal take their mainland's, except for a town or island of the
@@ -38,15 +44,15 @@ function regionCode(region, names) {
 export function facilityZone(location) {
     const parts = location.split(' - ').map((part) => part.trim());
     const country = parts.length > 1 ? parts.at(-1).toUpperCase() : '';
-    const region = parts.length > 2 ? parts.at(-2) : '';
+    // The region is a part of its own, or the code that ends the city's.
+    const region = parts.length > 2 ? parts.at(-2) : /, ([A-Z]{2})$/i.exec(parts[0])?.[1] ?? '';
     if (country === 'USA')
         return usStateTimeZone(regionCode(region, US_STATES));
     if (country === 'CANADA')
         return canadaProvinceTimeZone(regionCode(region, CANADA_PROVINCES));
-    if (country === 'UK')
-        return 'Europe/London';
-    // DHL writes some countries article last, and some with a comma: "NETHERLANDS, THE".
-    const zone = countryTimeZone(country.replace(/, THE$/, '').replaceAll(',', ''));
+    // DHL writes the article first or last: "THE PEOPLE'S REPUBLIC OF CHINA", "NETHERLANDS, THE".
+    const name = country.replace(/^THE /, '').replace(/, THE$/, '');
+    const zone = countryTimeZone(COUNTRIES[name] ?? name.replaceAll(',', ''));
     const islands = zone ? ISLANDS[zone] : undefined;
     return islands && regionHasTown(islands.group, parts[0]) ? islands.zone : zone;
 }

package/dist/carriers/dhl-express/numbers.json

@@ -1,6 +1,28 @@
 {
   "carrier": "dhl-express",
   "records": [
+    {
+      "number": "2522622410",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/iFoxz17/sc-delay-prediction/blob/b9e2f99fcdc157b4fb5ff3b0903e79f75f6b32cb/code/m4estro/LambdaTS/Carrier/sample.json",
+        "date": "2025-08-30"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-express",
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "A provider's reply for a DHL Express waybill, published as sample data with its scans. DHL has since issued the waybill to another shipment."
+    },
     {
       "number": "3408372365",
       "role": "shipment",

package/dist/data/catalog.json

@@ -461,7 +461,7 @@
                 "confidence": "high"
             },
             {
-                "pattern": "^00340434\\d{12}$",
+                "pattern": "^0034043[45]\\d{12}$",
                 "confidence": "high"
             },
             {

package/dist/generated/catalog.d.ts

@@ -301,7 +301,7 @@ export declare const CARRIER_CATALOG: {
             readonly pattern: "^JD\\d{18}$";
             readonly confidence: "high";
         }, {
-            readonly pattern: "^00340434\\d{12}$";
+            readonly pattern: "^0034043[45]\\d{12}$";
             readonly confidence: "high";
         }, {
             readonly pattern: "^JVGL[0-9]{20}$";

package/dist/generated/catalog.js

@@ -462,7 +462,7 @@ export const CARRIER_CATALOG = {
                 "confidence": "high"
             },
             {
-                "pattern": "^00340434\\d{12}$",
+                "pattern": "^0034043[45]\\d{12}$",
                 "confidence": "high"
             },
             {

package/dist/providers/parcelsapp/adapter.js

@@ -10,7 +10,6 @@
 import { load } from 'cheerio';
 import { DateTime } from 'luxon';
 import timers from 'node:timers/promises';
-import { facilityZone } from '../../carriers/dhl-express/clock.js';
 import { carrierTimezone } from '../../core/catalog/index.js';
 import { brandTimeZones, carrierIdFromName, carrierNameCountryZone } from '../../core/catalog/hints.js';
 import { CarrierError, carrierErrorKind, ChallengeError, IndeterminateError, InputRequiredError, NoHistoryError, SchemaError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
@@ -18,6 +17,7 @@ import { runSteps } from '../../core/runner/index.js';
 import { canadaProvinceTimeZone, countryCode, countryTimeZone, mislabeledLocalTime, mislabeledWallTime, regionHasTown, sharedClockZone, timeZoneCountry, usStateTimeZone, } from '../../core/time/index.js';
 import { isRecord } from '../../core/types.js';
 import { capturedBodies, loadCapture } from '../shared/capture.js';
+import { facilityZone, LatestScan, relaysFacilityClock } from '../shared/facilityClock.js';
 import { universalCarrierHints } from '../shared/hints.js';
 import { event, isNotice, localEvent, numberOf, result } from '../shared/result.js';
 import { carrierScan, markReturnLeg } from '../shared/scans.js';
@@ -117,29 +117,6 @@ function regionScanZone(name, location, inNorthAmerica) {
     const region = typeof name === 'string' && LOCAL_CLOCK_CARRIERS.test(name.trim()) ? regionClock(location) : null;
     return region && (region.certain || inNorthAmerica) ? region : null;
 }
-/** A DHL Express date with no zone for its facility: a wall time that no label makes an instant. */
-function isFacilityClock(payload, state) {
-    const name = stateCarrierName(payload, state);
-    return typeof name === 'string' && carrierIdFromName(name) === 'dhl-express';
-}
-/**
- * The newest wall clock of a reply, and whether that scan was left without an
- * instant. A reply whose latest scan has none cannot say where the parcel is,
- * and an older scan must not stand in for it.
- */
-class LatestScan {
-    wall = '';
-    unplaced = false;
-    see(date, unplaced) {
-        const wall = mislabeledWallTime(date) ?? '';
-        if (wall > this.wall || (wall === this.wall && unplaced))
-            [this.wall, this.unplaced] = [wall, unplaced];
-    }
-    check() {
-        if (this.unplaced)
-            throw new IndeterminateError(SOURCE, 'ParcelsApp cannot place the latest DHL Express scan');
-    }
-}
 function scanZone(payload, state, fallback, number, inNorthAmerica = false) {
     const name = stateCarrierName(payload, state);
     const carrier = typeof name === 'string' ? carrierIdFromName(name) : undefined;
@@ -153,10 +130,8 @@ function scanZone(payload, state, fallback, number, inNorthAmerica = false) {
     if (zone !== 'UTC' && !(typeof name === 'string' && carrierNameCountryZone(name)))
         return zone;
     const location = typeof state.location === 'string' ? state.location.trim() : '';
-    // DHL Express dates are its facility's clock, whatever the label: its mobile
-    // API gives the same clocks scan for scan, and Ship24 the same clocks with
-    // the facility's offset (checked 2026-10-06). No other step applies to them.
-    if (carrier === 'dhl-express')
+    // A facility's clock, whatever the label: no other step applies to it.
+    if (relaysFacilityClock(name))
         return facilityZone(location);
     const place = location.split(',').at(-1);
     // A state or province the town confirms beats the country its code also
@@ -242,14 +217,14 @@ function parseHistory(payload, trackingNumber, timezone = null) {
         return wall && text ? `${wall}|${text}` : '';
     };
     const localClocks = new Map(entries.filter((entry) => entry.local).map((entry) => [copyKey(entry), entry.zone]).filter(([key]) => key));
-    const latest = new LatestScan();
+    const latest = new LatestScan(SOURCE);
     for (const entry of entries) {
         const { raw, name, scan } = entry;
         const zone = (localClocks.size && !entry.local ? localClocks.get(copyKey(entry)) : undefined) ?? entry.zone;
-        const facilityClock = !zone && isFacilityClock(payload, raw);
-        const parsed = localEvent((zone ? mislabeledLocalTime(raw.date, zone)?.iso : facilityClock ? mislabeledWallTime(raw.date) : undefined) ?? raw.date, entry.wording);
+        const unplaced = !zone && relaysFacilityClock(name);
+        const parsed = localEvent((zone ? mislabeledLocalTime(raw.date, zone)?.iso : unplaced ? mislabeledWallTime(raw.date) : undefined) ?? raw.date, entry.wording);
         if (parsed)
-            latest.see(raw.date, facilityClock);
+            latest.see(mislabeledWallTime(raw.date) ?? '', unplaced);
         // Nor has an offset-less date that no zone resolves: a wall time, not an instant.
         if (parsed && !parsed.time) {
             undated++;
@@ -320,7 +295,7 @@ export function parseParcelsAppHtml(html, trackingNumber, timezone = null) {
     const carriers = [];
     const scans = [];
     let undated = 0;
-    const latest = new LatestScan();
+    const latest = new LatestScan(SOURCE);
     nodes.each((_, node) => {
         const row = $(node);
         if (row.find('input, select, form').length)
@@ -352,9 +327,9 @@ export function parseParcelsAppHtml(html, trackingNumber, timezone = null) {
         const zone = scanZone({ carriers }, state, timezone, numberOf(trackingNumber));
         const scan = carrierScan(name ? carrierIdFromName(name) : undefined, description);
         // The page prints no location, so no DHL Express scan has a facility to read its clock in.
-        const facilityClock = !zone && isFacilityClock({ carriers }, state);
-        latest.see(state.date, facilityClock);
-        if (facilityClock) {
+        const unplaced = !zone && relaysFacilityClock(name);
+        latest.see(mislabeledWallTime(state.date) ?? '', unplaced);
+        if (unplaced) {
             undated++;
             return;
         }

package/dist/providers/seventeentrack/adapter.d.ts

@@ -1,13 +1,3 @@
-/**
- * 17TRACK (t.17track.net), a universal aggregator with richer China Post history.
- *
- * Transport: the browser service loads the public tracking page and captures
- * the page's own `restapi` response; unsigned direct probes answer HTTP 200
- * with a rejection code instead of history (verified 2026-09-10). The parser
- * keeps only history whose shipment number equals the requested one, and turns
- * the provider's own rejection codes into typed errors so routing can tell a
- * verification wall from an outage.
- */
 import type { AdapterFactory } from '../../core/adapter/index.js';
 import { ChallengeError, NoHistoryError, TransportError } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';

package/dist/providers/seventeentrack/adapter.js

@@ -1,8 +1,20 @@
+/**
+ * 17TRACK (t.17track.net), a universal aggregator with richer China Post history.
+ *
+ * Transport: the browser service loads the public tracking page and captures
+ * the page's own `restapi` response; unsigned direct probes answer HTTP 200
+ * with a rejection code instead of history (verified 2026-09-10). The parser
+ * keeps only history whose shipment number equals the requested one, and turns
+ * the provider's own rejection codes into typed errors so routing can tell a
+ * verification wall from an outage.
+ */
+import { DateTime } from 'luxon';
 import { ChallengeError, NoHistoryError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { isRecord } from '../../core/types.js';
 import { universalCarrierHints } from '../shared/hints.js';
 import { capturedBodies, captureFailure, loadCapture } from '../shared/capture.js';
+import { facilityZone, LatestScan, relaysFacilityClock } from '../shared/facilityClock.js';
 import { numberOf, result, text } from '../shared/result.js';
 import { seventeenTrackEvent } from './events.js';
 const SOURCE = '17TRACK';
@@ -57,6 +69,12 @@ function lookupError(code, providerMessage) {
         ? new SeventeenTrackVerificationError(code, providerMessage)
         : new SeventeenTrackLookupError('lookup_unavailable', code, providerMessage);
 }
+/** The offset-less clock of a scan whose offset 17TRACK added itself. */
+function facilityWall(raw) {
+    const clock = isRecord(raw.time_raw) && raw.time_raw.timezone === null ? raw.time_raw : null;
+    return clock && typeof clock.date === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(clock.date)
+        && typeof clock.time === 'string' && /^\d{2}:\d{2}:\d{2}$/.test(clock.time) ? `${clock.date}T${clock.time}` : null;
+}
 export function parse17TrackResponse(payload, trackingNumber) {
     const number = numberOf(trackingNumber);
     if (!isRecord(payload) || !isRecord(payload.meta) || !Number.isInteger(payload.meta.code)) {
@@ -91,6 +109,7 @@ export function parse17TrackResponse(payload, trackingNumber) {
     const events = [];
     let count = 0;
     let undated = 0;
+    const latest = new LatestScan(SOURCE);
     for (const provider of tracking.providers) {
         if (!isRecord(provider) || !Array.isArray(provider.events))
             throw new SchemaError(SOURCE, '17TRACK returned invalid provider history');
@@ -103,17 +122,29 @@ export function parse17TrackResponse(payload, trackingNumber) {
                 throw new SchemaError(SOURCE, '17TRACK returned invalid events');
             if (raw.time_utc == null && raw.time_iso == null)
                 undated++;
+            // A facility's clock, on which 17TRACK puts one offset for the whole parcel.
+            const wall = relaysFacilityClock(name) ? facilityWall(raw) : null;
+            const zone = wall ? facilityZone(text(raw.location)) : null;
+            const placed = wall && zone ? DateTime.fromISO(wall, { zone }) : null;
             let parsed;
             try {
-                parsed = seventeenTrackEvent(raw, operator);
+                parsed = seventeenTrackEvent(placed?.isValid ? { ...raw, time_utc: placed.toUTC().toISO() } : raw, operator);
             }
             catch (cause) {
                 throw new SchemaError(SOURCE, '17TRACK returned an invalid tracking event', { cause });
             }
-            if (parsed)
+            if (!parsed)
+                continue;
+            const unplaced = wall !== null && !placed?.isValid;
+            latest.see(wall ?? String(raw.time_iso ?? raw.time_utc).slice(0, 19), unplaced);
+            // With no zone for the facility it is a wall time, counted like a row without a date.
+            if (unplaced)
+                undated++;
+            else
                 events.push(parsed);
         }
     }
+    latest.check();
     if (count === 0 && isRecord(shipment.latest_status) && shipment.latest_status.status === 'NotFound') {
         throw new NotFoundError(SOURCE);
     }

package/dist/providers/shared/facilityClock.d.ts

@@ -0,0 +1,25 @@
+import { facilityZone } from '../../carriers/dhl-express/clock.js';
+import type { UniversalSource } from './result.js';
+/**
+ * DHL Express dates a scan with its facility's clock and no offset, and the
+ * providers relay that clock under a label of their own: UTC at ParcelsApp, one
+ * offset for the whole parcel at 17TRACK. Ship24 relays it with the facility's
+ * offset, and DHL's mobile API gives the same clocks scan for scan (checked
+ * 2026-10-06). So such a scan is read in its facility's zone, and with no zone
+ * for the facility it is a wall time that no label makes an instant.
+ */
+export declare function relaysFacilityClock(carrierName: unknown): boolean;
+export { facilityZone };
+/**
+ * The newest wall clock of a reply, and whether that scan was left without an
+ * instant. A reply whose latest scan has none cannot say where the parcel is,
+ * and an older scan must not stand in for it.
+ */
+export declare class LatestScan {
+    private readonly source;
+    private wall;
+    private unplaced;
+    constructor(source: UniversalSource);
+    see(wall: string, unplaced: boolean): void;
+    check(): void;
+}

package/dist/providers/shared/facilityClock.js

@@ -0,0 +1,36 @@
+import { facilityZone } from '../../carriers/dhl-express/clock.js';
+import { carrierIdFromName } from '../../core/catalog/hints.js';
+import { IndeterminateError } from '../../core/errors/index.js';
+/**
+ * DHL Express dates a scan with its facility's clock and no offset, and the
+ * providers relay that clock under a label of their own: UTC at ParcelsApp, one
+ * offset for the whole parcel at 17TRACK. Ship24 relays it with the facility's
+ * offset, and DHL's mobile API gives the same clocks scan for scan (checked
+ * 2026-10-06). So such a scan is read in its facility's zone, and with no zone
+ * for the facility it is a wall time that no label makes an instant.
+ */
+export function relaysFacilityClock(carrierName) {
+    return typeof carrierName === 'string' && carrierIdFromName(carrierName) === 'dhl-express';
+}
+export { facilityZone };
+/**
+ * The newest wall clock of a reply, and whether that scan was left without an
+ * instant. A reply whose latest scan has none cannot say where the parcel is,
+ * and an older scan must not stand in for it.
+ */
+export class LatestScan {
+    source;
+    wall = '';
+    unplaced = false;
+    constructor(source) {
+        this.source = source;
+    }
+    see(wall, unplaced) {
+        if (wall > this.wall || (wall === this.wall && unplaced))
+            [this.wall, this.unplaced] = [wall, unplaced];
+    }
+    check() {
+        if (this.unplaced)
+            throw new IndeterminateError(this.source, `${this.source} cannot place the latest DHL Express scan`);
+    }
+}

package/dist/server/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Universal Parcel Scraper",
-    "version": "0.25.2"
+    "version": "0.25.3"
   },
   "paths": {
     "/health": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-parcel-scraper",
-  "version": "0.25.2-main.365",
+  "version": "0.25.3-main.367",
   "description": "Self-hosted parcel tracking: carrier detection, dedicated scrapers and optional universal providers.",
   "type": "module",
   "license": "Apache-2.0",