universal-parcel-scraper 0.4.0-main.320 → 0.5.0-main.322

package/data/catalog.json

@@ -468,7 +468,8 @@
     "timezone": "UTC",
     "tracking": {
       "mode": "automatic",
-      "adapter": "dhl-ecommerce"
+      "adapter": "dhl-ecommerce",
+      "recognitionRank": 23
     },
     "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
     "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -1973,7 +1974,8 @@
     "timezone": "Europe/Helsinki",
     "tracking": {
       "mode": "automatic",
-      "adapter": "posti"
+      "adapter": "posti",
+      "recognitionRank": 27
     },
     "canaryUrl": "https://www.posti.fi/en/tracking",
     "trackingUrlTemplate": "https://www.posti.fi/en/tracking/{trackingNumber}",
@@ -1985,7 +1987,14 @@
         "path": "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$"
       }
     ],
-    "detectionRules": []
+    "detectionRules": [
+      {
+        "pattern": "^[A-Z]{2}\\d{9}FI$",
+        "confidence": "low",
+        "checksum": "s10",
+        "preferred": true
+      }
+    ]
   },
   "correos-express": {
     "displayName": "Correos Express",

package/data/detection-golden.json

@@ -142,6 +142,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1124,6 +1125,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1140,6 +1142,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1622,6 +1625,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1638,6 +1642,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1731,6 +1736,9 @@
     "confidence": "low",
     "candidates": [
       "dhl-ecommerce"
+    ],
+    "asked": [
+      "dhl-ecommerce"
     ]
   },
   {
@@ -1746,6 +1754,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -1922,6 +1931,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -2345,6 +2355,9 @@
     "confidence": "low",
     "candidates": [
       "dhl-ecommerce"
+    ],
+    "asked": [
+      "dhl-ecommerce"
     ]
   },
   {
@@ -2438,6 +2451,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -2454,6 +2468,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -2594,6 +2609,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -2970,6 +2986,7 @@
     "asked": [
       "tnt",
       "correos-express",
+      "dhl-ecommerce",
       "canada-post"
     ]
   },
@@ -3101,6 +3118,9 @@
     "confidence": "low",
     "candidates": [
       "dhl-ecommerce"
+    ],
+    "asked": [
+      "dhl-ecommerce"
     ]
   },
   {
@@ -3112,7 +3132,8 @@
       "colis-prive"
     ],
     "asked": [
-      "colis-prive"
+      "colis-prive",
+      "dhl-ecommerce"
     ]
   },
   {
@@ -3281,6 +3302,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -3428,6 +3452,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -3473,6 +3500,29 @@
       "spring-gds"
     ]
   },
+  {
+    "input": "CP123456785FI",
+    "carrier": "intl-post",
+    "confidence": "high",
+    "candidates": [
+      "intl-post"
+    ],
+    "asked": [
+      "posti",
+      "chronopost"
+    ]
+  },
+  {
+    "input": "CP123456789FI",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "chronopost"
+    ],
+    "asked": [
+      "chronopost"
+    ]
+  },
   {
     "input": "CP123456789PL",
     "carrier": "unknown",
@@ -3490,6 +3540,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4177,6 +4230,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4204,6 +4260,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4220,6 +4279,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4236,6 +4298,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4332,6 +4397,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -4639,6 +4707,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {
@@ -5040,6 +5111,9 @@
     "confidence": "high",
     "candidates": [
       "intl-post"
+    ],
+    "asked": [
+      "chronopost"
     ]
   },
   {

package/dist/browser/scraper.js

@@ -479,7 +479,8 @@ var ue = {
 		timezone: "UTC",
 		tracking: {
 			mode: "automatic",
-			adapter: "dhl-ecommerce"
+			adapter: "dhl-ecommerce",
+			recognitionRank: 23
 		},
 		canaryUrl: "https://www.dhl.com/ch-en/home/tracking.html",
 		trackingUrlTemplate: "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -1595,7 +1596,8 @@ var ue = {
 		timezone: "Europe/Helsinki",
 		tracking: {
 			mode: "automatic",
-			adapter: "posti"
+			adapter: "posti",
+			recognitionRank: 27
 		},
 		canaryUrl: "https://www.posti.fi/en/tracking",
 		trackingUrlTemplate: "https://www.posti.fi/en/tracking/{trackingNumber}",
@@ -1603,7 +1605,12 @@ var ue = {
 			domains: ["posti.fi"],
 			path: "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$"
 		}],
-		detectionRules: []
+		detectionRules: [{
+			pattern: "^[A-Z]{2}\\d{9}FI$",
+			confidence: "low",
+			checksum: "s10",
+			preferred: !0
+		}]
 	},
 	"correos-express": {
 		displayName: "Correos Express",
@@ -7427,6 +7434,7 @@ var Lo = {
 	"colis-prive": 30,
 	"correos-express": 36,
 	"ctt-express": 35,
+	"dhl-ecommerce": 23,
 	dpd: 70,
 	"gls-ch": 60,
 	"gls-de": 50,
@@ -7437,6 +7445,7 @@ var Lo = {
 	"ninja-van": 28,
 	"nz-post": 32,
 	"poczta-polska": 31,
+	posti: 27,
 	postlogistics: 26,
 	"relais-colis": 25,
 	seur: 43,
@@ -7446,20 +7455,26 @@ var Lo = {
 	uniuni: 33
 }, Ro = 5;
 function zo(e, t = {}) {
-	let n = b(e);
-	if (n.confidence !== "low") return [];
-	let r = new Set(n.preferred.filter((e) => Lo[e] === void 0).map((e) => Io(e)).filter(Boolean)), i = (e) => [
+	let n = b(e), r = n.carrier === "intl-post";
+	if (n.confidence !== "low" && !r) return [];
+	let i = g(e), a = r ? Object.entries(_).flatMap(([t, n]) => {
+		let r = n.detectionRules.find((t) => t.confidence === "low" && (!t.checksum || t.checksum === "s10") && new RegExp(t.pattern).test(i) && (!t.rawPattern || new RegExp(t.rawPattern).test(e.trim().toUpperCase())));
+		return r ? [{
+			carrier: t,
+			preferred: r.preferred === !0
+		}] : [];
+	}) : [], o = r ? a.map(({ carrier: e }) => e) : n.candidates, s = r ? a.filter((e) => e.preferred).map(({ carrier: e }) => e) : n.preferred, c = new Set(s.filter((e) => Lo[e] === void 0).map((e) => Io(e)).filter(Boolean)), l = (e) => [
 		+(e === t.hint),
-		+!!n.preferred.includes(e),
+		+!!s.includes(e),
 		Lo[e] ?? 0
 	];
-	return n.candidates.filter((e) => Lo[e] !== void 0 && we.has(e) && xe(e) !== "universal" && !r.has(Io(e)) && !t.skip?.(e)).map((e) => ({
+	return o.filter((e) => Lo[e] !== void 0 && we.has(e) && xe(e) !== "universal" && !c.has(Io(e)) && !t.skip?.(e)).map((e) => ({
 		carrier: e,
-		score: i(e)
+		score: l(e)
 	})).sort((e, t) => t.score[0] - e.score[0] || t.score[1] - e.score[1] || t.score[2] - e.score[2]).map(({ carrier: t }) => ({
 		carrier: t,
 		needsInput: Ce(t, e)[0]?.field ?? null,
-		preferred: n.preferred.includes(t)
+		preferred: s.includes(t)
 	}));
 }
 //#endregion

package/dist/carriers/dhl-ecommerce/adapter.d.ts

@@ -1,20 +1,12 @@
 /**
- * DHL eCommerce, through the public recipient endpoint the global tracking
- * page calls (`www.dhl.com/utapi`).
- *
- * The endpoint answers every direct server request with an Akamai crypto
- * proof-of-work challenge (HTTP 428) that plain HTTP cannot solve (verified
- * 2026-09-10: cookie replay and visiting the page first both still return
- * 428), and browser clearance is not transferable back to Node. The lookup
- * therefore has a single step: a local Chromium session loads the tracking
- * page, the site solves its own challenge and calls the API in that session,
- * and the response to the exact requested URL is parsed.
+ * DHL eCommerce, through its anonymous Americas Webtrack API first, then
+ * the global tracking page's UTAPI for shipments outside Webtrack's scope.
  *
  * DHL may answer with a customer-confirmation id instead of the queried
  * alias, so only one eCommerce shipment from that exact request URL is
  * accepted, and the id itself is never retained.
  */
-import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type AdapterFactory, type Recognition, type TrackingContext } from '../../core/adapter/index.js';
 import { ChallengeError, type CarrierErrorOptions } from '../../core/errors/index.js';
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
@@ -24,6 +16,11 @@ export declare function dhlEcommerceTrackingUrl(number: string): string;
 /** Only call for the response to the exact requested UTAPI URL. DHL can return
  * a customer-confirmation id which differs from every queried parcel alias. */
 export declare function parseDHLEcommerceResponse(payload: unknown): CarrierResult;
+/** Webtrack scopes the read to the requested alias and returns that alias on
+ * each package, as its own client requires. An alias can differ from all of
+ * the package's carrier identifiers, so accept it only on one identified,
+ * unambiguous package. Never accept a bare query echo or a fabricated shell. */
+export declare function parseDHLEcommerceWebtrackResponse(payload: unknown, trackingNumber: string): CarrierResult;
 /**
  * The tracking page answered with a challenge status instead of the tracking
  * application. The name is part of the host's error metadata contract: it
@@ -37,6 +34,8 @@ export declare class DHLEcommerceSessionError extends ChallengeError {
 export interface DHLEcommerceTrackerOptions extends Omit<UniversalBrowserOptions, 'signal'> {
     budgetMs?: number;
     recorder?: StepRecorder;
+    fetcher?: typeof fetch;
+    userAgent?: string;
 }
 export declare class DHLEcommerceTracker {
     readonly options: DHLEcommerceTrackerOptions;
@@ -45,6 +44,9 @@ export declare class DHLEcommerceTracker {
     constructor(options?: DHLEcommerceTrackerOptions);
     /** One browser at a time per instance: a batch must not spawn a Chromium per parcel. */
     fetch(trackingNumber: string, context?: TrackingContext): Promise<CarrierResult>;
+    /** Recognition never starts the global page or spends a browser budget. */
+    recognize(trackingNumber: string, context?: TrackingContext): Promise<Recognition>;
+    private direct;
     private browser;
 }
 export declare const adapter: AdapterFactory;

package/dist/carriers/dhl-ecommerce/adapter.js

@@ -1,30 +1,25 @@
 /**
- * DHL eCommerce, through the public recipient endpoint the global tracking
- * page calls (`www.dhl.com/utapi`).
- *
- * The endpoint answers every direct server request with an Akamai crypto
- * proof-of-work challenge (HTTP 428) that plain HTTP cannot solve (verified
- * 2026-09-10: cookie replay and visiting the page first both still return
- * 428), and browser clearance is not transferable back to Node. The lookup
- * therefore has a single step: a local Chromium session loads the tracking
- * page, the site solves its own challenge and calls the API in that session,
- * and the response to the exact requested URL is parsed.
+ * DHL eCommerce, through its anonymous Americas Webtrack API first, then
+ * the global tracking page's UTAPI for shipments outside Webtrack's scope.
  *
  * DHL may answer with a customer-confirmation id instead of the queried
  * alias, so only one eCommerce shipment from that exact request URL is
  * accepted, and the id itself is never retained.
  */
 import { DateTime } from 'luxon';
-import { ChallengeError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
+import { accepted, lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
 import { runSteps, singleFlight, takeTurn } from '../../core/runner/index.js';
 import { countryTimeZone } from '../../core/time/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
-import { clean as cleanText, UpstreamHttpError } from '../../core/transport/index.js';
+import { clean as cleanText, fetchBounded, parseJsonBytes, UpstreamHttpError, UpstreamNetworkError, userAgentOf } from '../../core/transport/index.js';
 import { scrapeUniversalPage } from '../../core/transport/browser.js';
 import { isRecord } from '../../core/types.js';
 import { stageFor, statusFor } from './status.js';
 const PROVIDER = 'DHL eCommerce';
 const API = 'https://www.dhl.com/utapi';
+const WEBTRACK_API = 'https://api.dhlecs.com/webtrack/v4/tracking';
+const DIRECT_TIMEOUT_MS = 15_000;
 /** Statuses DHL answers with while its challenge is unsolved. */
 const CHALLENGE_STATUSES = [401, 403, 419, 428];
 /**
@@ -117,6 +112,82 @@ export function parseDHLEcommerceResponse(payload) {
         ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
     };
 }
+function webtrackClock(event) {
+    const date = clean(event.date, 32);
+    const time = clean(event.time, 32);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)
+        || !/^\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)?$/.test(time))
+        return null;
+    const raw = `${date}T${time}`;
+    if (!DateTime.fromISO(raw, { zone: 'UTC', setZone: true }).isValid)
+        return null;
+    const location = clean(event.location, 160);
+    const country = location.split(',').at(-1)?.trim().toUpperCase() ?? '';
+    const instant = eventTime({ timestamp: raw, location: { address: {
+                addressLocality: location, ...(/^[A-Z]{2}$/.test(country) ? { countryCode: country } : {}),
+            } } });
+    return instant ? { time: instant } : { local_time: raw };
+}
+/** Webtrack scopes the read to the requested alias and returns that alias on
+ * each package, as its own client requires. An alias can differ from all of
+ * the package's carrier identifiers, so accept it only on one identified,
+ * unambiguous package. Never accept a bare query echo or a fabricated shell. */
+export function parseDHLEcommerceWebtrackResponse(payload, trackingNumber) {
+    const number = normalizeDHLEcommerceNumber(trackingNumber);
+    if (!isRecord(payload) || !Array.isArray(payload.packages) || !Number.isInteger(payload.total)
+        || Number(payload.total) < 0 || payload.packages.length > 50 || payload.offset !== 0
+        || (payload.errors !== undefined && (!Array.isArray(payload.errors) || payload.errors.length > 0))) {
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned an invalid Webtrack response');
+    }
+    if (payload.total === 0 && payload.packages.length === 0) {
+        // Webtrack covers the Americas network; the global endpoint may still
+        // know an item this regional endpoint does not list.
+        throw new IndeterminateError(PROVIDER, 'DHL eCommerce Webtrack does not list this shipment', { reason: 'webtrack_not_found' });
+    }
+    if (payload.total !== 1 || payload.packages.length !== 1 || !isRecord(payload.packages[0])) {
+        throw new SchemaError(PROVIDER, 'DHL eCommerce did not return one unambiguous Webtrack package');
+    }
+    const shipment = payload.packages[0];
+    const identifiers = [shipment.trackingId, shipment.packageId, shipment.dhlPackageId, shipment.deliveryConfirmationNumber];
+    const matches = (value) => typeof value === 'string'
+        && value.toUpperCase().replace(/[\s.-]/g, '') === number;
+    if (!clean(shipment.tmiUid) || !identifiers.some((value) => clean(value))
+        || ![shipment.trackedValue, ...identifiers].some(matches)) {
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned a different or unidentified Webtrack package');
+    }
+    const summary = clean(shipment.status);
+    if (!summary || !Array.isArray(shipment.events) || shipment.events.length > 500
+        || shipment.events.some((event) => !isRecord(event))) {
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned invalid Webtrack tracking history');
+    }
+    const events = shipment.events.flatMap((event) => {
+        const description = clean(event.primaryEventDescription);
+        const clock = webtrackClock(event);
+        if (!description || !clock)
+            return [];
+        const stage = stageFor({ description });
+        return [{ ...clock, description: stage === 'delivered' ? 'Delivered' : description,
+                location: clean(event.location, 160), stage }];
+    }).sort((left, right) => left.time && right.time ? right.time.localeCompare(left.time) : 0).slice(0, 100);
+    const summaryStage = stageFor({ description: summary, statusCode: summary === 'Delivered' ? 'delivered' : undefined });
+    // A published scan carries finer semantics than Webtrack's coarse summary.
+    const stage = ['delivered', 'returned'].includes(summaryStage) ? summaryStage : events[0]?.stage ?? summaryStage;
+    if (events.length === 0) {
+        throw new IndeterminateError(PROVIDER, 'DHL eCommerce has not published Webtrack tracking history', { reason: 'webtrack_no_history' });
+    }
+    const expected = clean(shipment.estimatedDeliveryDate, 32);
+    const sender = clean(isRecord(shipment.sender) ? shipment.sender.name : null, 200);
+    return {
+        status: statusFor(stage), current_stage: stage,
+        last_status_text: stage === 'delivered' ? 'Delivered' : summary,
+        last_update: events.find((event) => event.time)?.time ?? null,
+        expected_delivery: !['delivered', 'returned'].includes(stage) && /^\d{4}-\d{2}-\d{2}$/.test(expected)
+            && DateTime.fromISO(expected).isValid ? expected : null,
+        timezone: 'UTC', events,
+        ...(sender ? { sender_name: sender } : {}),
+        ...(stage === 'delivered' && events[0]?.stage === 'delivered' && events[0].time ? { delivered_at: events[0].time } : {}),
+    };
+}
 /**
  * The tracking page answered with a challenge status instead of the tracking
  * application. The name is part of the host's error metadata contract: it
@@ -149,7 +220,47 @@ export class DHLEcommerceTracker {
     async fetch(trackingNumber, context = {}) {
         const number = normalizeDHLEcommerceNumber(trackingNumber);
         const timeoutMs = this.options.timeoutMs ?? 45_000;
-        return takeTurn(this.serialize, PROVIDER, context, ({ signal, budgetMs }) => runSteps({ carrier: 'dhl-ecommerce', budgetMs: budgetMs ?? this.options.budgetMs ?? timeoutMs + 15_000, signal, recorder: this.recorder }, [{ id: 'browser', run: (step) => this.browser(number, Math.max(1, Math.floor(Math.min(timeoutMs, step.remainingMs))), step.signal) }]));
+        return takeTurn(this.serialize, PROVIDER, context, ({ signal, budgetMs }) => runSteps({ carrier: 'dhl-ecommerce', budgetMs: budgetMs ?? this.options.budgetMs ?? timeoutMs + 15_000, signal, recorder: this.recorder }, [
+            { id: 'direct', run: (step) => this.direct(number, Math.min(DIRECT_TIMEOUT_MS, step.remainingMs), step.signal) },
+            { id: 'browser', recovers: (error) => error instanceof ChallengeError || error instanceof UpstreamNetworkError
+                    || error instanceof UpstreamHttpError && error.status >= 500
+                    || error instanceof IndeterminateError && ['webtrack_not_found', 'webtrack_no_history'].includes(error.reason ?? ''),
+                run: (step) => this.browser(number, Math.max(1, Math.floor(Math.min(timeoutMs, step.remainingMs))), step.signal) },
+        ]));
+    }
+    /** Recognition never starts the global page or spends a browser budget. */
+    async recognize(trackingNumber, context = {}) {
+        return recognizeFromLookup(async () => {
+            const number = normalizeDHLEcommerceNumber(trackingNumber);
+            const budget = lookupBudget(context, DIRECT_TIMEOUT_MS, PROVIDER);
+            try {
+                return await this.direct(number, Math.min(DIRECT_TIMEOUT_MS, budget.remainingMs()), budget.signal);
+            }
+            catch (error) {
+                // A clean regional miss is unknown to this recognition check; it is
+                // never a claim that the global DHL network does not know the number.
+                if (error instanceof IndeterminateError && error.reason === 'webtrack_not_found')
+                    throw new NotFoundError(PROVIDER);
+                throw error;
+            }
+        }, () => accepted(() => normalizeDHLEcommerceNumber(trackingNumber)));
+    }
+    async direct(number, timeoutMs, signal) {
+        try {
+            const { response, bytes } = await fetchBounded(WEBTRACK_API, { method: 'POST', signal,
+                headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': userAgentOf(this.options.userAgent) },
+                body: JSON.stringify({ trackedValue: number, offset: 0, locale: 'en-US' }),
+            }, { provider: PROVIDER, timeoutMs, maxBytes: 1_000_000, fetcher: this.options.fetcher, allowHttpStatuses: [404, 410] });
+            if (!response.ok)
+                throw new IndeterminateError(PROVIDER, 'DHL eCommerce Webtrack endpoint is unavailable');
+            return parseDHLEcommerceWebtrackResponse(parseJsonBytes(bytes, PROVIDER), number);
+        }
+        catch (error) {
+            if (error instanceof UpstreamHttpError && CHALLENGE_STATUSES.includes(error.status)) {
+                throw new DHLEcommerceSessionError(error.status, { cause: error });
+            }
+            throw error;
+        }
     }
     async browser(number, timeoutMs, signal) {
         try {
@@ -170,10 +281,12 @@ export class DHLEcommerceTracker {
 export const adapter = (environment) => {
     const tracker = new DHLEcommerceTracker({
         executablePath: environment.browserExecutablePath ?? undefined, recorder: environment.recorder,
+        fetcher: environment.fetcher, userAgent: environment.userAgent,
     });
     return {
         id: 'dhl-ecommerce', recordsSteps: true,
-        steps: ['browser'],
+        steps: ['direct', 'browser'],
         track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => tracker.recognize(number, context),
     };
 };

package/dist/carriers/dhl-ecommerce/carrier.json

@@ -21,8 +21,12 @@
     "mode": "automatic",
     "adapter": "dhl-ecommerce",
     "steps": [
+      "direct",
       "browser"
-    ]
+    ],
+    "recognition": {
+      "rank": 23
+    }
   },
   "capabilities": [
     "history",

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

@@ -10,7 +10,7 @@ export declare class DPDChallengeError extends ChallengeError {
 /**
  * The guest API answered, but the answer proves nothing about the shipment
  * (unreachable, malformed, unauthenticated, or an HTTP status the guest flow
- * handles itself). The rendered page is allowed to recover from it.
+ * handles itself, except HTTP 503). The rendered page is allowed to recover from it.
  */
 export declare class DPDAPIError extends IndeterminateError {
     constructor(message: string, options?: CarrierErrorOptions);

package/dist/carriers/dpd/adapter.js

@@ -2,7 +2,7 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { randomBytes } from 'node:crypto';
 import { load } from 'cheerio';
 import { lookupBudget } from '../../core/adapter/index.js';
-import { BudgetExceededError, carrierErrorKind, ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { BudgetExceededError, carrierErrorKind, ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { isoTime, explicitOffsetTime, zonedTime } from '../../core/time/index.js';
 import { TrawlClient, decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
@@ -19,7 +19,8 @@ import { API_LABELS, PROOF_OF_DELIVERY_SCAN, apiStage, apiStatus, scanStage, wor
 //   `continueWithoutVerification=true`. A rejected postcode (HTTP 400) is
 //   retried once without verification and reported as unverified rather than
 //   failing the lookup.
-// - The consignee web page is the fallback when the guest API is inconclusive.
+// - The consignee web page is the fallback when the guest API is inconclusive,
+//   except HTTP 503: the service is down, irrespective of the parcel number.
 //   It sits behind Cloudflare, so it is fetched through the browser service's
 //   legacy command API when one is configured and directly otherwise.
 const TRACKING_BASE = 'https://www.dpdgroup.com/ch/mydpd/my-parcels/incoming';
@@ -54,7 +55,7 @@ export class DPDChallengeError extends ChallengeError {
 /**
  * The guest API answered, but the answer proves nothing about the shipment
  * (unreachable, malformed, unauthenticated, or an HTTP status the guest flow
- * handles itself). The rendered page is allowed to recover from it.
+ * handles itself, except HTTP 503). The rendered page is allowed to recover from it.
  */
 export class DPDAPIError extends IndeterminateError {
     constructor(message, options) {
@@ -778,6 +779,10 @@ export class DPDTracker {
         catch (error) {
             throw new DPDAPIError('DPD guest API is unreachable', { cause: error });
         }
+        // A 503 describes DPD's availability, so the page must not turn it into
+        // an answer about the parcel or hold up the caller's other lookups.
+        if (result.response.status === 503)
+            throw new UpstreamHttpError('DPD guest API', 503);
         if (!result.response.ok)
             throw new DPDAPIHttpError(result.response.status);
         let payload;

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

@@ -1,4 +1,4 @@
-import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+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 function normalizePostiTrackingNumber(raw: string): string;

package/dist/carriers/posti/adapter.js

@@ -1,3 +1,4 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
 import { CarrierError, IndeterminateError, InvalidInputError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { explicitOffsetTime } from '../../core/time/index.js';
@@ -191,5 +192,9 @@ export class PostiTracker {
 }
 export const adapter = (environment) => {
     const tracker = new PostiTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
-    return { id: 'posti', recordsSteps: true, steps: ['direct', 'refresh'], track: (input, context) => tracker.fetch(input.number, context) };
+    return {
+        id: 'posti', recordsSteps: true, steps: ['direct', 'refresh'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizePostiTrackingNumber(number))),
+    };
 };

package/dist/carriers/posti/carrier.json

@@ -18,7 +18,10 @@
     "steps": [
       "direct",
       "refresh"
-    ]
+    ],
+    "recognition": {
+      "rank": 27
+    }
   },
   "capabilities": [
     "history",
@@ -65,5 +68,13 @@
       "path": "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$"
     }
   ],
-  "detection": []
+  "detection": [
+    {
+      "id": "posti-1",
+      "pattern": "^[A-Z]{2}\\d{9}FI$",
+      "confidence": "low",
+      "preferred": true,
+      "checksum": "s10"
+    }
+  ]
 }

package/dist/carriers/posti/numbers.json

@@ -1,6 +1,34 @@
 {
   "carrier": "posti",
   "records": [
+    {
+      "number": "CP123456785FI",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Invented checksum-valid Finnish-issued S10 number. The issuer makes Posti a recognition candidate; offline detection stays with the unknown postal carrier."
+    },
+    {
+      "number": "CP123456789FI",
+      "role": "negative",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ],
+        "not": [
+          "posti"
+        ]
+      },
+      "note": "Invented Finnish-shaped identifier with a failed S10 check digit. It cannot suggest Posti."
+    },
     {
       "number": "00264300487130023858",
       "role": "shipment",

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

@@ -12,7 +12,8 @@ export interface RecognitionCandidate {
  * The low-confidence candidates worth asking, best first: the carrier a
  * universal provider named, then the ones number evidence backs, then the
  * catalog's popularity rank. Only carriers that declare `tracking.recognition`
- * qualify. A high-confidence number needs no recognition.
+ * qualify. A high-confidence dedicated carrier needs no recognition; the
+ * unknown postal carrier still needs a direct carrier to confirm it.
  */
 export declare function recognitionCandidates(number: string, options?: {
     hint?: string;

package/dist/core/catalog/recognition.js

@@ -9,7 +9,8 @@
  */
 import { CARRIER_RECOGNITION_RANKS } from '../../generated/recognition.js';
 import { detectCarrierMatch } from '../detection/detect.js';
-import { AUTOMATIC_CARRIER_IDS, carrierAdapter, requiredRequirements } from './definitions.js';
+import { normalizeTrackingNumber } from '../detection/normalize.js';
+import { AUTOMATIC_CARRIER_IDS, CARRIER_DEFINITIONS, carrierAdapter, requiredRequirements } from './definitions.js';
 import { carrierBrand } from './networks.js';
 /** Carriers asked at once. */
 export const MAX_RECOGNITIONS = 5;
@@ -17,24 +18,43 @@ export const MAX_RECOGNITIONS = 5;
  * The low-confidence candidates worth asking, best first: the carrier a
  * universal provider named, then the ones number evidence backs, then the
  * catalog's popularity rank. Only carriers that declare `tracking.recognition`
- * qualify. A high-confidence number needs no recognition.
+ * qualify. A high-confidence dedicated carrier needs no recognition; the
+ * unknown postal carrier still needs a direct carrier to confirm it.
  */
 export function recognitionCandidates(number, options = {}) {
     const detected = detectCarrierMatch(number);
-    if (detected.confidence !== 'low')
+    const unknownPostalCarrier = detected.carrier === 'intl-post';
+    if (detected.confidence !== 'low' && !unknownPostalCarrier)
         return [];
+    // The high-confidence S10 fallback hides low-confidence carrier rules from
+    // detection. Recover those candidates without assigning the issuer's
+    // postal carrier as the deliverer: each candidate must confirm this number.
+    // intl-post already checked the S10 checksum, so only S10 or shape-only rules
+    // can contribute here.
+    const normalized = normalizeTrackingNumber(number);
+    const postalMatches = unknownPostalCarrier ? Object.entries(CARRIER_DEFINITIONS)
+        .flatMap(([carrier, definition]) => {
+        const rule = definition.detectionRules.find((candidate) => candidate.confidence === 'low'
+            && (!candidate.checksum || candidate.checksum === 's10')
+            && new RegExp(candidate.pattern).test(normalized)
+            && (!candidate.rawPattern || new RegExp(candidate.rawPattern).test(number.trim().toUpperCase())));
+        return rule ? [{ carrier, preferred: rule.preferred === true }] : [];
+    }) : [];
+    const candidates = unknownPostalCarrier ? postalMatches.map(({ carrier }) => carrier) : detected.candidates;
+    const preferred = unknownPostalCarrier
+        ? postalMatches.filter((match) => match.preferred).map(({ carrier }) => carrier) : detected.preferred;
     // A carrier the number points to but that cannot be asked (DPD France) keeps
     // its brand's other networks out: DPD's guest API also answers for DPD
     // France parcels, and would file one under DPD Switzerland.
-    const shadowed = new Set(detected.preferred
+    const shadowed = new Set(preferred
         .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] === undefined)
         .map((carrier) => carrierBrand(carrier)).filter(Boolean));
     const score = (carrier) => [
         carrier === options.hint ? 1 : 0,
-        detected.preferred.includes(carrier) ? 1 : 0,
+        preferred.includes(carrier) ? 1 : 0,
         CARRIER_RECOGNITION_RANKS[carrier] ?? 0,
     ];
-    return detected.candidates
+    return candidates
         .filter((carrier) => CARRIER_RECOGNITION_RANKS[carrier] !== undefined && AUTOMATIC_CARRIER_IDS.has(carrier)
         && carrierAdapter(carrier) !== 'universal' && !shadowed.has(carrierBrand(carrier)) && !options.skip?.(carrier))
         .map((carrier) => ({ carrier, score: score(carrier) }))
@@ -43,7 +63,7 @@ export function recognitionCandidates(number, options = {}) {
         .map(({ carrier }) => ({
         carrier,
         needsInput: requiredRequirements(carrier, number)[0]?.field ?? null,
-        preferred: detected.preferred.includes(carrier),
+        preferred: preferred.includes(carrier),
     }));
 }
 /** The carriers the detect route asks about a number, best first; empty when none can answer. */

package/dist/core/recognition/index.js

@@ -2,7 +2,8 @@ import { carrierBrand } from '../catalog/networks.js';
 import { CARRIER_RECOGNITION_RANKS } from '../../generated/recognition.js';
 export { MAX_RECOGNITIONS, recognitionCandidates, } from '../catalog/recognition.js';
 /**
- * Carrier recognition: when a number's shape fits several carriers, ask the
+ * Carrier recognition: when a number's shape fits several carriers or names
+ * only an international postal item, ask the
  * ones that can answer cheaply whether they know it. The Add sheet runs it
  * while the user is still in the form, the first sync runs it again after
  * saving, and routing keeps retrying it while the filed carrier cannot track

package/dist/data/catalog.json

@@ -468,7 +468,8 @@
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "dhl-ecommerce"
+            "adapter": "dhl-ecommerce",
+            "recognitionRank": 23
         },
         "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
         "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -1973,7 +1974,8 @@
         "timezone": "Europe/Helsinki",
         "tracking": {
             "mode": "automatic",
-            "adapter": "posti"
+            "adapter": "posti",
+            "recognitionRank": 27
         },
         "canaryUrl": "https://www.posti.fi/en/tracking",
         "trackingUrlTemplate": "https://www.posti.fi/en/tracking/{trackingNumber}",
@@ -1985,7 +1987,14 @@
                 "path": "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$"
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}FI$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "correos-express": {
         "displayName": "Correos Express",

package/dist/facade/index.js

@@ -129,7 +129,7 @@ export function createTracker(options = {}) {
         if (typeof carrier !== 'string')
             throw new TypeError('Invalid carrier');
         carrierDefinition(carrier);
-        if (!input.carrier && detectCarrierMatch(number).confidence !== 'high') {
+        if (!input.carrier && recognitionCandidates(number).length > 0) {
             try {
                 const answer = await recognize(number, { signal, budgetMs: Math.min(10_000, ms) });
                 if (answer.carrier)

package/dist/generated/catalog.d.ts

@@ -308,6 +308,7 @@ export declare const CARRIER_CATALOG: {
         readonly tracking: {
             readonly mode: "automatic";
             readonly adapter: "dhl-ecommerce";
+            readonly recognitionRank: 23;
         };
         readonly canaryUrl: "https://www.dhl.com/ch-en/home/tracking.html";
         readonly trackingUrlTemplate: "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1";
@@ -1293,6 +1294,7 @@ export declare const CARRIER_CATALOG: {
         readonly tracking: {
             readonly mode: "automatic";
             readonly adapter: "posti";
+            readonly recognitionRank: 27;
         };
         readonly canaryUrl: "https://www.posti.fi/en/tracking";
         readonly trackingUrlTemplate: "https://www.posti.fi/en/tracking/{trackingNumber}";
@@ -1300,7 +1302,12 @@ export declare const CARRIER_CATALOG: {
             readonly domains: readonly ["posti.fi"];
             readonly path: "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$";
         }];
-        readonly detectionRules: readonly [];
+        readonly detectionRules: readonly [{
+            readonly pattern: "^[A-Z]{2}\\d{9}FI$";
+            readonly confidence: "low";
+            readonly checksum: "s10";
+            readonly preferred: true;
+        }];
     };
     readonly "correos-express": {
         readonly displayName: "Correos Express";

package/dist/generated/catalog.js

@@ -469,7 +469,8 @@ export const CARRIER_CATALOG = {
         "timezone": "UTC",
         "tracking": {
             "mode": "automatic",
-            "adapter": "dhl-ecommerce"
+            "adapter": "dhl-ecommerce",
+            "recognitionRank": 23
         },
         "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
         "trackingUrlTemplate": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
@@ -1974,7 +1975,8 @@ export const CARRIER_CATALOG = {
         "timezone": "Europe/Helsinki",
         "tracking": {
             "mode": "automatic",
-            "adapter": "posti"
+            "adapter": "posti",
+            "recognitionRank": 27
         },
         "canaryUrl": "https://www.posti.fi/en/tracking",
         "trackingUrlTemplate": "https://www.posti.fi/en/tracking/{trackingNumber}",
@@ -1986,7 +1988,14 @@ export const CARRIER_CATALOG = {
                 "path": "^/(?:[a-z]{2}/)?tracking/([^/?#]+)(?:/[0-9]+)?/?$"
             }
         ],
-        "detectionRules": []
+        "detectionRules": [
+            {
+                "pattern": "^[A-Z]{2}\\d{9}FI$",
+                "confidence": "low",
+                "checksum": "s10",
+                "preferred": true
+            }
+        ]
     },
     "correos-express": {
         "displayName": "Correos Express",

package/dist/generated/recognition.js

@@ -11,6 +11,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "colis-prive": 30,
     "correos-express": 36,
     "ctt-express": 35,
+    "dhl-ecommerce": 23,
     "dpd": 70,
     "gls-ch": 60,
     "gls-de": 50,
@@ -21,6 +22,7 @@ export const CARRIER_RECOGNITION_RANKS = {
     "ninja-van": 28,
     "nz-post": 32,
     "poczta-polska": 31,
+    "posti": 27,
     "postlogistics": 26,
     "relais-colis": 25,
     "seur": 43,

package/dist/server/openapi.json

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

package/package.json

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