universal-parcel-scraper 0.12.0-main.336 → 0.13.1

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 **96 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **98 dedicated adapters** and **5 universal fallbacks**
 
 <sub>119 catalog entries · 58 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -33,9 +33,9 @@ its own as a command, a Node library or an HTTP server.
 ## Benchmark
 
 <!-- GENERATED:coverage -->
-In a curated benchmark of 113 carriers, dedicated adapters return tracking history for **69**, rising to **82** with all fallbacks enabled. The best single aggregator returns 53.
+In a curated benchmark of 113 carriers, dedicated adapters return tracking history for **71**, rising to **84** with all fallbacks enabled. The best single aggregator returns 53.
 
-<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 82, This project, dedicated adapters alone 69, ParcelsApp 53, Postal Ninja 43, 17TRACK 40, Ship24 42, UPU 12." width="760">
+<img src="docs/assets/coverage.svg" alt="Carriers with tracking history: This project, all fallbacks enabled 84, This project, dedicated adapters alone 71, ParcelsApp 53, Postal Ninja 43, 17TRACK 40, Ship24 42, UPU 12." width="760">
 <!-- /GENERATED:coverage -->
 
 [Method and results per carrier](providers/COVERAGE.md)
@@ -149,7 +149,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 1,779 such statuses, each filed under one stage.
+The carrier folders record 1,785 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

@@ -4172,7 +4172,8 @@
     "timezone": "Europe/London",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "dpd-uk",
+      "localClocks": true
     },
     "canaryUrl": "https://track.dpd.co.uk/",
     "trackingUrlTemplate": "https://track.dpd.co.uk/?reference={trackingNumber}",
@@ -4242,7 +4243,7 @@
     "timezone": "Europe/London",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "evri-uk"
     },
     "canaryUrl": "https://www.evri.com/track-a-parcel",
     "trackingUrlTemplate": "https://www.evri.com/track/parcel/{trackingNumber}/details",

package/data/coverage-summary.json

@@ -1,11 +1,11 @@
 {
   "catalog": 119,
-  "activeAdapters": 96,
+  "activeAdapters": 98,
   "countries": 58,
   "referenceCarriers": 113,
   "comparison": {
-    "combined": 82,
-    "direct": 69,
+    "combined": 84,
+    "direct": 71,
     "providers": {
       "ParcelsApp": 53,
       "Postal Ninja": 43,

package/data/detection-golden.json

@@ -1380,6 +1380,54 @@
       "colis-prive"
     ]
   },
+  {
+    "input": "15504366056765",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "dpd",
+      "dpd-fr",
+      "relais-colis",
+      "ciblex",
+      "seur",
+      "brt",
+      "delhivery",
+      "dpd-de",
+      "dpd-uk",
+      "xpressbees"
+    ],
+    "asked": [
+      "dpd",
+      "seur",
+      "brt",
+      "relais-colis",
+      "ciblex"
+    ]
+  },
+  {
+    "input": "15504366057635",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "dpd",
+      "dpd-fr",
+      "relais-colis",
+      "ciblex",
+      "seur",
+      "brt",
+      "delhivery",
+      "dpd-de",
+      "dpd-uk",
+      "xpressbees"
+    ],
+    "asked": [
+      "dpd",
+      "seur",
+      "brt",
+      "relais-colis",
+      "ciblex"
+    ]
+  },
   {
     "input": "1595193512495",
     "carrier": "unknown",

package/dist/browser/scraper.js

@@ -3213,7 +3213,8 @@ var ce = {
 		timezone: "Europe/London",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "dpd-uk",
+			localClocks: !0
 		},
 		canaryUrl: "https://track.dpd.co.uk/",
 		trackingUrlTemplate: "https://track.dpd.co.uk/?reference={trackingNumber}",
@@ -3261,7 +3262,7 @@ var ce = {
 		timezone: "Europe/London",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "evri-uk"
 		},
 		canaryUrl: "https://www.evri.com/track-a-parcel",
 		trackingUrlTemplate: "https://www.evri.com/track/parcel/{trackingNumber}/details",
@@ -8289,7 +8290,7 @@ var gs = { carriers: [
 			"Postal Ninja": 4,
 			UPU: "no_history"
 		} }, {
-			note: "Alternate public reference returned eight identity-bound full-history scans in an interactive official session; fresh automated browser retrieval remains denied: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/",
+			note: "Alternate public reference returned eight identity-bound full-history scans in an interactive official session. Fresh automated Chromium obtained the matching microsummary, but its separate events request failed; automated full history remains unverified: https://www.reddit.com/r/royalmail/comments/1wh27pw/cant_track_my_shipment/",
 			results: {}
 		}]
 	},
@@ -9713,10 +9714,10 @@ var gs = { carriers: [
 	},
 	{
 		carrier: "dpd-uk",
-		direct: "No adapter",
-		sample: "Blocked",
+		direct: "Yes (UK parcel numbers)",
+		sample: "✓ 7",
 		references: [{
-			note: "UK reference-plus-postcode flow requires a challenge and session before retrieval.",
+			note: "Public UK parcel references returned seven and eight history scans through the current anonymous empty-postcode lookup; unqualified scan clocks remain local: https://uk.trustpilot.com/review/primepaint.co.uk?page=3. Order and collection references behind the postcode form are outside the adapter scope.",
 			results: {
 				Ship24: "unverified",
 				ParcelsApp: "unverified",
@@ -9728,10 +9729,10 @@ var gs = { carriers: [
 	},
 	{
 		carrier: "evri-uk",
-		direct: "No adapter",
-		sample: "Blocked",
+		direct: "Yes (local Chromium)",
+		sample: "✓ 6",
 		references: [{
-			note: "The official interactive navigation flow obtained rotating keys and six dated parcel scans. Fresh automated browser sessions are denied the keys: https://www.trustpilot.com/review/printerval.co.uk",
+			note: "Public domestic reference returned six identity-bound, offset-dated history scans in fresh automated local Chromium. The current anonymous flow obtains rotating keys in the browser and requires no postcode: https://www.trustpilot.com/review/printerval.co.uk",
 			results: {
 				Ship24: "unverified",
 				ParcelsApp: "unverified",
@@ -9866,7 +9867,7 @@ var gs = { carriers: [
 		direct: "No adapter",
 		sample: "Blocked",
 		references: [{
-			note: "The current corporate tracking form posts to the public tracking service, which returns access denied. This is not evidence of parcel absence.",
+			note: "Sagawa has suspended public shipment inquiry and its carrier inquiry API; fresh anonymous history retrieval is unavailable: https://www2.sagawa-exp.co.jp/information/detail/425/",
 			results: {
 				Ship24: "unverified",
 				ParcelsApp: "unverified",

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/carriers/dpd-uk/adapter.d.ts

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class DpdUkTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/dpd-uk/adapter.js

@@ -0,0 +1,58 @@
+import { CarrierError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isDpdUkReferenceAbsent, normalizeDpdUkNumber, parseDpdUkHistory, parseDpdUkReference, PROVIDER, validateDpdUkParcel } from './parser.js';
+const API = 'https://apis.track.dpd.co.uk/v1';
+export class DpdUkTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeDpdUkNumber(raw);
+        return runSteps({ carrier: 'dpd-uk', signal: context.signal, budgetMs: context.budgetMs ?? 15_000,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const deadline = performance.now() + remainingMs;
+                    const read = async (path, reference = false) => {
+                        try {
+                            signal.throwIfAborted();
+                            const { bytes, response } = await fetchBounded(`${API}${path}`, { signal, headers: { Accept: 'application/json' } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(deadline - performance.now())), maxBytes: 1_000_000,
+                                fetcher: this.options.fetcher, allowHttpStatuses: [404, 410] });
+                            let payload;
+                            try {
+                                payload = parseJsonBytes(bytes, PROVIDER);
+                            }
+                            catch {
+                                throw response.ok ? new SchemaError(PROVIDER) : new TransportError(PROVIDER, 'DPD UK tracking endpoint is unavailable');
+                            }
+                            if (!response.ok) {
+                                if (reference && response.status === 404 && isDpdUkReferenceAbsent(payload))
+                                    throw new NotFoundError(PROVIDER);
+                                throw new TransportError(PROVIDER, 'DPD UK tracking endpoint is unavailable');
+                            }
+                            return payload;
+                        }
+                        catch (error) {
+                            signal.throwIfAborted();
+                            // Request diagnostics and malformed bodies can contain an issued parcel
+                            // handle or personal details. Keep the classification, never its cause.
+                            if (error instanceof CarrierError)
+                                throw new CarrierError(error.kind, PROVIDER, `${PROVIDER} tracking failed (${error.kind})`, { status: error.status, retryAfterMs: error.retryAfterMs, reason: error.reason });
+                            throw new TransportError(PROVIDER);
+                        }
+                    };
+                    const query = new URLSearchParams({ origin: 'PRTK', postcode: '', referenceNumber: number });
+                    const code = parseDpdUkReference(await read(`/reference?${query}`, true), number);
+                    const parcelPath = `/parcels/${encodeURIComponent(code)}`;
+                    const detail = await read(parcelPath);
+                    validateDpdUkParcel(detail, number, code);
+                    const history = await read(`${parcelPath}/parcelevents`);
+                    return parseDpdUkHistory(detail, history, number, code);
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new DpdUkTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'dpd-uk', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/dpd-uk/carrier.json

@@ -16,13 +16,15 @@
   "timezone": "Europe/London",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "dpd-uk",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
   },
   "capabilities": [
     "history",
-    "location",
-    "eta"
+    "location"
   ],
   "portal": {
     "url": "https://track.dpd.co.uk/?reference={trackingNumber}",
@@ -33,8 +35,18 @@
       "location",
       "eta"
     ],
-    "scraped": [],
-    "discarded": [],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "parcel_handle",
+      "merchant_reference",
+      "delivery_partner_reference",
+      "recipient_details",
+      "proof_of_delivery_images"
+    ],
     "unavailable": []
   },
   "links": [

package/dist/carriers/dpd-uk/numbers.json

@@ -1,5 +1,33 @@
 {
   "carrier": "dpd-uk",
-  "gap": "no public sample found yet",
-  "records": []
+  "records": [
+    {
+      "number": "15504366056765",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://uk.trustpilot.com/review/primepaint.co.uk?page=3"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": ["dpd", "dpd-fr", "relais-colis", "ciblex", "seur", "brt", "delhivery", "dpd-de", "dpd-uk", "xpressbees"]
+      },
+      "note": "Prime Paint's public reply identifies this as DPD UK. A numeric shape alone does not identify the service. Tracking numbers can be reused; current history need not belong to the original report."
+    },
+    {
+      "number": "15504366057635",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://uk.trustpilot.com/review/primepaint.co.uk?page=3"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": ["dpd", "dpd-fr", "relais-colis", "ciblex", "seur", "brt", "delhivery", "dpd-de", "dpd-uk", "xpressbees"]
+      },
+      "note": "Prime Paint's public reply identifies this as DPD UK. A numeric shape alone does not identify the service. Tracking numbers can be reused; current history need not belong to the original report."
+    }
+  ]
 }

package/dist/carriers/dpd-uk/parser.d.ts

@@ -0,0 +1,9 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "DPD UK";
+export declare function normalizeDpdUkNumber(raw: string): string;
+/** Resolve one exact parcel, keeping its issued code opaque and lookup-local. */
+export declare function parseDpdUkReference(payload: unknown, number: string): string;
+export declare function isDpdUkReferenceAbsent(payload: unknown): boolean;
+export declare function validateDpdUkParcel(payload: unknown, number: string, code: string): Record<string, unknown>;
+/** Events have no identity field; the adapter reads them under the exact validated detail handle. */
+export declare function parseDpdUkHistory(detailPayload: unknown, historyPayload: unknown, raw: string, code: string): CarrierResult;

package/dist/carriers/dpd-uk/parser.js

@@ -0,0 +1,127 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, SchemaError } from '../../core/errors/index.js';
+import { classifyWording, languageStageStatus } from '../../core/status/index.js';
+import { explicitOffsetTime } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+export const PROVIDER = 'DPD UK';
+export function normalizeDpdUkNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^\d{14}$/.test(number))
+        throw new InvalidInputError(PROVIDER, 'DPD UK requires a fourteen-digit parcel number');
+    return number;
+}
+// The public client displays spaced digits followed by a printed check letter.
+function parcelNumber(value) {
+    if (typeof value !== 'string' || value.length > 64)
+        return null;
+    const match = /^(\d{14})[A-Z]?$/.exec(value.replace(/\s/g, '').toUpperCase());
+    return match?.[1] ?? null;
+}
+/** Resolve one exact parcel, keeping its issued code opaque and lookup-local. */
+export function parseDpdUkReference(payload, number) {
+    if (!isRecord(payload) || !Array.isArray(payload.data) || payload.data.length > 100)
+        throw new SchemaError(PROVIDER);
+    if (!payload.data.length)
+        throw new IndeterminateError(PROVIDER, 'DPD UK returned no matching parcel');
+    if (payload.data.length !== 1 || !isRecord(payload.data[0]) || parcelNumber(payload.data[0].parcelNumber) !== number) {
+        throw new SchemaError(PROVIDER, 'DPD UK returned a different or ambiguous parcel');
+    }
+    const code = payload.data[0].parcelCode;
+    if (typeof code !== 'string' || !/^[A-Za-z0-9*_-]{1,128}$/.test(code))
+        throw new SchemaError(PROVIDER, 'DPD UK returned an invalid parcel handle');
+    return code;
+}
+export function isDpdUkReferenceAbsent(payload) {
+    return isRecord(payload) && !Object.hasOwn(payload, 'data') && isRecord(payload.error)
+        && payload.error.statusCode === 404 && payload.error.error === 'Not Found'
+        && payload.error.message === 'Your reference number could not be found';
+}
+export function validateDpdUkParcel(payload, number, code) {
+    if (!isRecord(payload) || !isRecord(payload.data) || parcelNumber(payload.data.parcelNumber) !== number
+        || payload.data.parcelCode !== code)
+        throw new SchemaError(PROVIDER, 'DPD UK returned a different parcel');
+    return payload.data;
+}
+const VERIFIED_WORDING = {
+    'your parcel has been delivered': 'delivered',
+    'the parcel has been delivered': 'delivered',
+    'your parcel will be with you today': 'out_for_delivery',
+    'the parcel is on the vehicle for delivery': 'out_for_delivery',
+    'your parcel is at our depot': 'in_transit',
+    "we have your parcel and it's on its way to our depot": 'in_transit',
+    "we have your parcel and it's on its way to you": 'in_transit',
+    'we have x-rayed your parcel as part of our normal security procedures': 'in_transit',
+    "we've received your order details, but have not yet received your parcel": 'registered',
+};
+function classify(description) {
+    const wording = description.toLowerCase().replace(/[’‘]/g, "'").replace(/\s+/g, ' ').trim().replace(/[.!]+$/, '');
+    const stage = VERIFIED_WORDING[wording];
+    return stage ? { stage, source: 'carrier_map' } : classifyWording(description);
+}
+function publicDescription(value) {
+    const text = clean(value, 1000);
+    // A sender return is a shipment stage, rather than a recipient's identity.
+    if (/\bdelivered (?:back )?to (?:the )?(?:sender|shipper)\b/i.test(text))
+        return text;
+    return text.replace(/(\bdelivered)\s+(?:to\s+.+|and\s+signed\s+(?:for\s+)?by\s+.+|signed\s+(?:for\s+)?by\s+.+)$/i, '$1');
+}
+function clockFields(clock) {
+    const shape = /^(\d{4}-\d{2}-\d{2})[ T]((?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d)(Z|[+-]\d{2}:?\d{2})?$/.exec(clock);
+    if (!shape)
+        return { provider_time_text: clock };
+    const iso = `${shape[1]}T${shape[2]}${shape[3] ?? ''}`;
+    if (!DateTime.fromISO(iso, { zone: 'UTC', setZone: true }).isValid)
+        return { provider_time_text: clock };
+    if (!shape[3])
+        return { local_time: `${shape[1]}T${shape[2]}` };
+    const offset = /[+-](\d{2}):?(\d{2})$/.exec(iso);
+    if (offset && (Number(offset[1]) > 14 || Number(offset[2]) > 59 || (Number(offset[1]) === 14 && Number(offset[2]) !== 0))) {
+        return { provider_time_text: clock };
+    }
+    const instant = explicitOffsetTime(iso);
+    return instant ? { time: instant.iso } : { provider_time_text: clock };
+}
+/** Events have no identity field; the adapter reads them under the exact validated detail handle. */
+export function parseDpdUkHistory(detailPayload, historyPayload, raw, code) {
+    const number = normalizeDpdUkNumber(raw);
+    const detail = validateDpdUkParcel(detailPayload, number, code);
+    if (!isRecord(historyPayload) || !Array.isArray(historyPayload.data) || historyPayload.data.length > 1000)
+        throw new SchemaError(PROVIDER);
+    if (!historyPayload.data.length)
+        throw new IndeterminateError(PROVIDER, 'DPD UK returned no parcel history');
+    // The official page renders these rows newest first. Do not reorder uncertain clocks.
+    const events = historyPayload.data.map(row => {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER);
+        if ((row.parcelNumber !== undefined && parcelNumber(row.parcelNumber) !== number)
+            || (row.parcelCode !== undefined && row.parcelCode !== code))
+            throw new SchemaError(PROVIDER, 'DPD UK returned a different scan identity');
+        const description = publicDescription(row.eventText);
+        const clock = clean(row.eventDate, 64);
+        if (!description || !clock || typeof row.eventDate !== 'string' || row.eventDate.length > 64)
+            throw new SchemaError(PROVIDER, 'DPD UK returned an incomplete scan');
+        const classification = classify(description);
+        const location = clean(row.eventLocation, 200);
+        return { description, ...clockFields(clock), ...(location ? { location } : {}),
+            ...(classification.source !== 'none' ? { stage: classification.stage, stage_source: classification.source } : {}) };
+    });
+    const seen = new Set();
+    const retained = events.filter(event => {
+        const key = JSON.stringify(event);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).slice(0, 100);
+    const latest = retained[0];
+    const summary = publicDescription(detail.trackingStatusCurrent);
+    const summaryClassification = classify(summary);
+    const current = summary ? summaryClassification : classify(latest.description);
+    return { status: current.source !== 'none' ? languageStageStatus(current.stage) : 'unknown',
+        ...(current.source !== 'none' ? { current_stage: current.stage, current_stage_source: current.source } : {}),
+        last_status_text: summary || latest.description, last_update: latest.time ?? null,
+        ...(latest.local_time ? { last_update_local: latest.local_time } : {}),
+        ...(current.stage === 'delivered' && latest.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}), events: retained };
+}

package/dist/carriers/evri-uk/adapter.d.ts

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class EvriUkTracker {
+    private readonly options;
+    constructor(options?: {
+        executablePath?: string | null;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;