universal-parcel-scraper 0.13.0-main.337 → 0.13.1

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

@@ -2,6 +2,8 @@ import { type AdapterFactory, type AdapterEnvironment, type TrackingContext } fr
 import type { CarrierResult } from '../../core/result/index.js';
 export declare function normalizeNumber(raw: string): string;
 export declare function trackingUrl(raw: string): string;
+/** Public DHL web tracking: bind both the waybill and the Express division. */
+export declare function parseUnified(payload: unknown, raw: string): CarrierResult;
 /** A waybill can be reused. Multiple or duplicate shipments need recipient disambiguation. */
 export declare function parse(payload: unknown, raw: string): CarrierResult;
 export declare class DhlExpressTracker {

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

@@ -1,14 +1,19 @@
 import { DateTime } from 'luxon';
-import { accepted, lookupBudget, recognizeFromLookup } from '../../core/adapter/index.js';
+import { accepted, lookupBudget, recognizeFromBrowserLookup, recognizeFromLookup } from '../../core/adapter/index.js';
 import { isValidDhlExpressWaybill } from '../../core/detection/numericChecksums.js';
 import { BudgetExceededError, ChallengeError, IndeterminateError, InvalidInputError, NotFoundError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { runSteps } from '../../core/runner/index.js';
 import { classifyWording } from '../../core/status/index.js';
-import { clean, decodeText, fetchBounded, parseJsonBytes, TRAWL_TRANSPORT_ALLOWANCE_MS } from '../../core/transport/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean, decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
 const PROVIDER = 'DHL Express';
 const API = 'https://mydhl.express.dhl/shipmentTracking';
+const BROWSER_API = 'https://www.dhl.com/utapi';
 const MAX_BYTES = 1_000_000;
+// The scoped browser runner bounds context cleanup to 1.5 seconds. Leave room
+// for that and transport without consuming most of a short recognition budget.
+const BROWSER_CLEANUP_ALLOWANCE_MS = 2_000;
 export function normalizeNumber(raw) {
     const number = raw.replace(/[\s.-]/g, '');
     if (!isValidDhlExpressWaybill(number)) {
@@ -46,6 +51,46 @@ function stage(description) {
         return { stage: 'customs', source: 'carrier_map' };
     return classifyWording(description, 'pending');
 }
+/** Public DHL web tracking: bind both the waybill and the Express division. */
+export function parseUnified(payload, raw) {
+    const number = normalizeNumber(raw);
+    if (!isRecord(payload) || !Array.isArray(payload.shipments) || payload.shipments.length > 20
+        || payload.shipments.some((shipment) => !isRecord(shipment)))
+        throw new SchemaError(PROVIDER, 'DHL returned invalid shipments');
+    const matching = payload.shipments.filter(isRecord).filter((shipment) => shipment.id === number);
+    if (!matching.length)
+        throw new SchemaError(PROVIDER, 'DHL returned a different waybill');
+    if (matching.length !== 1)
+        throw new IndeterminateError(PROVIDER, 'DHL returned a reused waybill');
+    const shipment = matching[0];
+    if (shipment.service !== 'express')
+        throw new IndeterminateError(PROVIDER, 'DHL returned a different division');
+    if (!Array.isArray(shipment.events) || shipment.events.length > 1000)
+        throw new SchemaError(PROVIDER, 'DHL returned invalid events');
+    if (!shipment.events.length)
+        throw new IndeterminateError(PROVIDER, 'DHL has no shipment activity');
+    const event = (row) => {
+        if (!isRecord(row) || typeof row.description !== 'string' || !row.description.trim())
+            throw new SchemaError(PROVIDER, 'DHL returned an invalid event');
+        const description = row.statusCode === 'delivered' ? 'Delivered' : clean(row.description).slice(0, 1000);
+        const mapped = stage(description);
+        const time = typeof row.timestamp === 'string' && /(?:Z|[+-](?:[01]\d|2[0-3]):?[0-5]\d)$/i.test(row.timestamp)
+            ? explicitOffsetTime(row.timestamp)?.iso : undefined;
+        const address = isRecord(row.location) && isRecord(row.location.address) ? row.location.address : {};
+        return { description, stage: mapped.stage, stage_source: mapped.source,
+            ...(time ? { time } : {}), ...(typeof address.addressLocality === 'string' ? { location: clean(address.addressLocality).slice(0, 300) } : {}),
+            ...(typeof row.status === 'string' ? { provider_code: row.status.slice(0, 100) } : {}) };
+    };
+    const events = shipment.events.map(event);
+    const current = event(shipment.status);
+    const status = current.stage === 'delivered' ? 'delivered' : current.stage === 'out_for_delivery' ? 'out_for_delivery'
+        : ['exception', 'failed_attempt', 'returned'].includes(current.stage) ? 'exception'
+            : ['pending', 'registered'].includes(current.stage) ? 'pending' : 'in_transit';
+    const destination = isRecord(shipment.destination) && isRecord(shipment.destination.address) ? shipment.destination.address : {};
+    return { status, current_stage: current.stage, current_stage_source: current.stage_source,
+        last_status_text: current.description, last_update: current.time ?? null, events,
+        ...(typeof destination.countryCode === 'string' && /^[A-Z]{2}$/.test(destination.countryCode) ? { destination_country: destination.countryCode } : {}) };
+}
 /** A waybill can be reused. Multiple or duplicate shipments need recipient disambiguation. */
 export function parse(payload, raw) {
     const number = normalizeNumber(raw);
@@ -104,36 +149,48 @@ export class DhlExpressTracker {
         const budget = lookupBudget(context, 45_000, PROVIDER);
         if (!this.environment.trawl)
             throw new ChallengeError(PROVIDER, 'DHL Express requires the browser tracking service');
-        const timeoutMs = budget.remainingMs() - TRAWL_TRANSPORT_ALLOWANCE_MS;
+        const timeoutMs = budget.remainingMs() - BROWSER_CLEANUP_ALLOWANCE_MS;
         if (timeoutMs < 1)
             throw new BudgetExceededError(PROVIDER, budget.budgetMs);
-        const page = await this.environment.trawl.scrape({ url: trackingUrl(number), skipHttp: true, maxTier: 3,
-            maxTimeout: timeoutMs, captureResponses: [API], settleTimeout: Math.min(timeoutMs, 10_000),
+        const page = await this.environment.trawl.scrape({ url: `https://www.dhl.com/global-en/home/tracking/tracking-parcel.html?submit=1&tracking-id=${normalizeNumber(number)}`, skipHttp: true, maxTier: 3,
+            maxTimeout: timeoutMs, captureResponses: [BROWSER_API], settleTimeout: timeoutMs,
         }, { provider: PROVIDER, timeoutMs, signal: budget.signal, maxBytes: 6_000_000, requireSolved: false });
         budget.signal.throwIfAborted();
         const captures = page.capturedResponses.filter((r) => {
             try {
                 const url = new URL(r.url);
-                return url.origin + url.pathname === API && !url.username && !url.password
-                    && url.searchParams.getAll('AWB').length === 1 && url.searchParams.get('AWB') === number && r.status !== 204;
+                return url.origin + url.pathname === BROWSER_API && !url.username && !url.password
+                    && url.searchParams.getAll('trackingNumber').length === 1 && url.searchParams.get('trackingNumber') === number && r.status !== 204;
             }
             catch {
                 return false;
             }
         });
         const response = captures.at(-1);
-        if (!response || captures.length > 10 || response.error || response.truncated || response.base64Encoded || response.body === null) {
+        if (!response || captures.length > 10 || response.error || response.truncated || response.base64Encoded) {
             throw new TransportError(PROVIDER, 'DHL Express returned no complete matching browser response');
         }
         if (response.status === 429)
             throw new RateLimitedError(PROVIDER);
-        if ([401, 403].includes(response.status) || /^\s*</.test(response.body))
+        if ([401, 403, 428].includes(response.status) || /^\s*</.test(response.body ?? ''))
             throw new ChallengeError(PROVIDER);
+        if (response.status === 404 && response.body) {
+            let missing;
+            try {
+                missing = JSON.parse(response.body);
+            }
+            catch { /* An arbitrary 404 is not a shipment answer. */ }
+            if (isRecord(missing) && missing.status === 404 && missing.title === 'No result found'
+                && missing.detail === 'No shipment with given tracking number found.')
+                throw new NotFoundError(PROVIDER);
+        }
         if (response.status >= 400)
             throw new UpstreamHttpError(PROVIDER, response.status);
+        if (response.body === null)
+            throw new TransportError(PROVIDER, 'DHL Express returned no complete matching browser response');
         if (response.status !== 200 || Buffer.byteLength(response.body) > MAX_BYTES)
             throw new SchemaError(PROVIDER, 'DHL Express returned invalid browser data');
-        return this.decode(new TextEncoder().encode(response.body), number);
+        return parseUnified(parseJsonBytes(new TextEncoder().encode(response.body), PROVIDER), number);
     }
     decode(bytes, number) {
         let payload;
@@ -160,15 +217,6 @@ export const adapter = (environment) => {
         recognizeWithBrowser: async (number, context, previousError) => {
             if (previousError instanceof RateLimitedError || previousError instanceof SchemaError || previousError instanceof NotFoundError)
                 throw previousError;
-            try {
-                const result = await tracker.browser(normalizeNumber(number), context);
-                // Local facility clocks establish dated activity, but never an instant for ranking reuse.
-                return result.events?.some((event) => event.time) ? { known: true, lastActivityAt: null, result } : { known: false };
-            }
-            catch (error) {
-                if (error instanceof NotFoundError)
-                    return { known: false };
-                throw error;
-            }
+            return recognizeFromBrowserLookup(() => tracker.browser(normalizeNumber(number), context));
         } };
 };

package/dist/server/openapi.json

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

package/package.json

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