universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,50 @@
+/**
+ * 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 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 } 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';
+import { type UniversalBrowserOptions } from '../../core/transport/browser.js';
+export declare function normalizeDHLEcommerceNumber(raw: string): string;
+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;
+/**
+ * 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
+ * reports the upstream status for errors named `DHLEcommerceSessionError`.
+ */
+export declare class DHLEcommerceSessionError extends ChallengeError {
+    /** Always present here; narrowed from the optional base field. */
+    readonly status: number;
+    constructor(status: number, options?: CarrierErrorOptions);
+}
+export interface DHLEcommerceTrackerOptions extends UniversalBrowserOptions {
+    budgetMs?: number;
+    recorder?: StepRecorder;
+}
+export declare class DHLEcommerceTracker {
+    readonly options: DHLEcommerceTrackerOptions;
+    private readonly recorder;
+    private readonly serialize;
+    constructor(options?: DHLEcommerceTrackerOptions);
+    /** One browser at a time per instance: a batch must not spawn a Chromium per parcel. */
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+    private browser;
+}
+export declare const adapter: AdapterFactory;

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

@@ -0,0 +1,179 @@
+/**
+ * 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 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, SchemaError } from '../../core/errors/index.js';
+import { runSteps, singleFlight } 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 { 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';
+/** Statuses DHL answers with while its challenge is unsolved. */
+const CHALLENGE_STATUSES = [401, 403, 419, 428];
+/**
+ * UTAPI strings occasionally carry markup. Tags are dropped without a
+ * separator, as this adapter has always done, before the shared cleaner
+ * collapses whitespace and caps the length.
+ */
+function clean(value, limit = 500) {
+    return typeof value === 'string' ? cleanText(value.replace(/<[^>]*>/g, ''), limit) : '';
+}
+export function normalizeDHLEcommerceNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^(?=.*\d)[A-Z0-9]{5,40}$/.test(number))
+        throw new TypeError('DHL eCommerce tracking number is invalid');
+    return number;
+}
+export function dhlEcommerceTrackingUrl(number) {
+    return `https://www.dhl.com/ch-en/home/tracking.html?tracking-id=${normalizeDHLEcommerceNumber(number)}&submit=1`;
+}
+function address(event) {
+    const location = isRecord(event.location) ? event.location : {};
+    return isRecord(location.address) ? location.address : {};
+}
+// UTAPI returns local wall-clock timestamps, sometimes without countryCode.
+// Resolve only unambiguous locations; never treat an unknown local time as UTC.
+const HUB_ZONES = {
+    'melrose park, il, us': 'America/Chicago', 'hebron, ky, us': 'America/New_York',
+    'lahr': 'Europe/Berlin', 'staufenberg': 'Europe/Berlin',
+};
+/**
+ * A local policy rather than one from `core/time`: the zone comes from the
+ * event's own location, and every event is normalized to UTC because the
+ * result declares `timezone: 'UTC'` for a carrier whose legs cross zones.
+ */
+function eventTime(event) {
+    const raw = clean(event.timestamp, 64);
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(raw))
+        return null;
+    const place = address(event);
+    const locality = clean(place.addressLocality, 160);
+    const country = clean(place.countryCode).toUpperCase();
+    const zone = /(?:Z|[+-]\d{2}:\d{2})$/.test(raw) ? 'UTC'
+        : countryTimeZone(country) ?? countryTimeZone(locality) ?? HUB_ZONES[locality.toLowerCase()];
+    if (!zone)
+        return null;
+    const parsed = DateTime.fromISO(raw, { zone, setZone: true });
+    return parsed.isValid ? parsed.toUTC().toISO() : null;
+}
+/** 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 function parseDHLEcommerceResponse(payload) {
+    if (!isRecord(payload) || !Array.isArray(payload.shipments))
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned an invalid tracking response');
+    if (payload.shipments.length !== 1 || !isRecord(payload.shipments[0])) {
+        throw new SchemaError(PROVIDER, 'DHL eCommerce did not return one unambiguous shipment');
+    }
+    const shipment = payload.shipments[0];
+    if (!clean(shipment.id))
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned a shipment without an identifier');
+    if (shipment.service !== 'ecommerce')
+        throw new SchemaError(PROVIDER, 'This shipment is not handled by DHL eCommerce');
+    if (!isRecord(shipment.status) || !clean(shipment.status.description))
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned no tracking status');
+    if (!Array.isArray(shipment.events) || shipment.events.length > 500)
+        throw new SchemaError(PROVIDER, 'DHL eCommerce returned invalid tracking events');
+    const events = shipment.events.filter(isRecord).flatMap((event) => {
+        const time = eventTime(event);
+        const description = clean(event.description);
+        if (!time || !description)
+            return [];
+        const place = address(event);
+        const stage = stageFor(event);
+        return [{ time, description: stage === 'delivered' ? 'Delivered' : description,
+                location: [...new Set([clean(place.addressLocality, 160), clean(place.countryCode, 2)].filter(Boolean))].join(', '),
+                stage }];
+    }).sort((a, b) => b.time.localeCompare(a.time)).slice(0, 100);
+    const stage = shipment.returnFlag === true && shipment.status.statusCode === 'delivered'
+        ? 'returned' : stageFor(shipment.status);
+    const expected = clean(shipment.estimatedTimeOfDelivery, 64).slice(0, 10);
+    const sender = clean(isRecord(shipment.sender) ? shipment.sender.name : shipment.senderName, 200) || null;
+    const deliveredAt = stage === 'delivered' ? eventTime(shipment.status) : null;
+    return {
+        status: statusFor(stage), current_stage: stage,
+        last_status_text: stage === 'delivered' ? 'Delivered' : clean(shipment.status.description),
+        last_update: eventTime(shipment.status),
+        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 } : {}),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+    };
+}
+/**
+ * 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
+ * reports the upstream status for errors named `DHLEcommerceSessionError`.
+ */
+export class DHLEcommerceSessionError extends ChallengeError {
+    constructor(status, options) {
+        super(PROVIDER, `DHL eCommerce rejected the tracking session with HTTP ${status}`, { ...options, status });
+        this.name = 'DHLEcommerceSessionError';
+    }
+}
+function trackingApiUrl(number) {
+    const url = new URL(API);
+    url.search = new URLSearchParams({ trackingNumber: number, language: 'en', requesterCountryCode: 'CH', source: 'tt' }).toString();
+    return url.toString();
+}
+export class DHLEcommerceTracker {
+    options;
+    recorder;
+    serialize = singleFlight();
+    constructor(options = {}) {
+        this.options = options;
+        const timeout = options.timeoutMs;
+        if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0 || timeout > 60_000)) {
+            throw new TypeError('DHL eCommerce timeout must be between 1 and 60000 ms');
+        }
+        this.recorder = options.recorder ?? NOOP_RECORDER;
+    }
+    /** One browser at a time per instance: a batch must not spawn a Chromium per parcel. */
+    async fetch(trackingNumber) {
+        const number = normalizeDHLEcommerceNumber(trackingNumber);
+        const timeoutMs = this.options.timeoutMs ?? 45_000;
+        return this.serialize(() => runSteps({ carrier: 'dhl-ecommerce', budgetMs: this.options.budgetMs ?? timeoutMs + 15_000, recorder: this.recorder }, [{ id: 'browser', run: () => this.browser(number, timeoutMs) }]));
+    }
+    async browser(number, timeoutMs) {
+        try {
+            return await scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs }, {
+                name: PROVIDER, url: dhlEcommerceTrackingUrl(number), responseUrl: trackingApiUrl(number),
+            }, parseDHLEcommerceResponse);
+        }
+        catch (error) {
+            // The challenge can also reach the page itself; name it so the host
+            // records the upstream status rather than a bare transport failure.
+            if (error instanceof UpstreamHttpError && CHALLENGE_STATUSES.includes(error.status)) {
+                throw new DHLEcommerceSessionError(error.status, { cause: error });
+            }
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new DHLEcommerceTracker({
+        executablePath: environment.browserExecutablePath ?? undefined, recorder: environment.recorder,
+    });
+    return {
+        id: 'dhl-ecommerce',
+        steps: ['browser'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

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

@@ -0,0 +1,97 @@
+{
+  "id": "dhl-ecommerce",
+  "displayName": "DHL eCommerce",
+  "aliases": [
+    "DHL eCommerce Solutions",
+    "DHL Global Mail"
+  ],
+  "region": {
+    "countries": [
+      "DE",
+      "NL",
+      "US"
+    ]
+  },
+  "brand": {
+    "color": "#ffcc00"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "dhl-ecommerce",
+    "steps": [
+      "browser"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "sender_name",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://www.dhl.com/ch-en/home/tracking.html?tracking-id={trackingNumber}&submit=1",
+    "canaryUrl": "https://www.dhl.com/ch-en/home/tracking.html",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "delivered_at",
+      "recipient_address",
+      "customer_reference"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "delivered_at"
+    ],
+    "discarded": [
+      "recipient_address",
+      "customer_reference"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "ecommerceportal.dhl.com",
+        "webtrack.dhlglobalmail.com"
+      ],
+      "params": [
+        "tracking-id",
+        "trackingNumber",
+        "tracking",
+        "ID"
+      ]
+    },
+    {
+      "domains": [
+        "dhl.com"
+      ],
+      "pathPattern": "/home/tracking[.]html$",
+      "params": [
+        "tracking-id",
+        "trackingId"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "dhl-ecommerce-1",
+      "pattern": "^GM[0-9]{16,18}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dhl-ecommerce-2",
+      "pattern": "^[0-9]{16,17}$",
+      "confidence": "low"
+    }
+  ]
+}

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

@@ -0,0 +1,130 @@
+{
+  "carrier": "dhl-ecommerce",
+  "records": [
+    {
+      "number": "33870000000000001",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce"
+        ]
+      },
+      "note": "Invented placeholder used as a shape check. Filed under DHL eCommerce, which stays one candidate among several."
+    },
+    {
+      "number": "3387191106122423",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to DHL eCommerce, which stays one candidate among several."
+    },
+    {
+      "number": "GM1234567890123456",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl-ecommerce",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "GM60511234500000001",
+      "role": "shipment",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "expect": {
+        "carrier": "dhl-ecommerce",
+        "confidence": "high"
+      },
+      "note": "Official documentation example, not a real shipment."
+    },
+    {
+      "number": "0031043534391627906195625053434",
+      "role": "full_barcode",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Official documentation example, not a real shipment. Full label barcode rather than the number a user types. The source attributes it to DHL eCommerce; no rule matches this shape."
+    },
+    {
+      "number": "0031043534391640211895625057522",
+      "role": "full_barcode",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Official documentation example, not a real shipment. Full label barcode rather than the number a user types. The source attributes it to DHL eCommerce; no rule matches this shape."
+    },
+    {
+      "number": "9261269903500013618305",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "austrian-post",
+          "usps",
+          "estafeta"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to DHL eCommerce, which no rule claims."
+    },
+    {
+      "number": "9361269903500011492028",
+      "role": "quarantined",
+      "evidence": "official_documentation_example",
+      "source": {
+        "url": "https://developer.dhl.com/api-reference/references-dhl-ecommerce-americas"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "austrian-post",
+          "usps",
+          "estafeta"
+        ]
+      },
+      "note": "Official documentation example, not a real shipment. The source attributes it to DHL eCommerce, which no rule claims."
+    }
+  ]
+}

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

@@ -0,0 +1,13 @@
+/**
+ * DHL eCommerce wording and UTAPI status codes → product stage.
+ *
+ * UTAPI events carry both a free-text `description` and a coarse
+ * `statusCode` (`pre-transit`, `transit`, `failure`, `delivered`). The
+ * wording is the more precise of the two, so it is read first; the code is
+ * the fallback, except for `delivered`, which is terminal and outranks an
+ * intuitive translation of the text.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { JsonObject } from '../../core/types.js';
+export declare function stageFor(event: JsonObject): string;
+export declare function statusFor(stage: string): CarrierStatus;

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

@@ -0,0 +1,57 @@
+import { trackingLanguageStage } from '../../core/status/index.js';
+import { clean as cleanText } from '../../core/transport/index.js';
+/** The same tag-stripping cleaner the projection uses (see adapter.ts). */
+function clean(value, limit = 500) {
+    return typeof value === 'string' ? cleanText(value.replace(/<[^>]*>/g, ''), limit) : '';
+}
+export function stageFor(event) {
+    const text = clean(event.description).toLowerCase();
+    if (/return(?:ed|ing)? to (?:the )?sender/.test(text))
+        return 'returned';
+    if (/not delivered|unable to deliver|delivery attempt|delivery failed/.test(text))
+        return 'failed_attempt';
+    // A carrier-reported problem that is neither a missed attempt nor a return.
+    if (/carrier exception|shipment exception|delivery exception|damaged|refused|address (?:incorrect|incomplete|unknown)|(?:incorrect|incomplete) address|lost in transit/.test(text))
+        return 'exception';
+    // Sender-side drop-off scans (ha-dhl-nl#15) must never read as recipient
+    // pickup: the parcel is entering the network, not awaiting collection.
+    if (/picked.?up at (?:a )?parcel ?shop|drop(?:ped)? ?off at|handed in at/.test(text))
+        return 'accepted';
+    if (/ready for (?:pickup|collection)|available for (?:pickup|collection)/.test(text))
+        return 'ready_for_pickup';
+    if (/out for delivery/.test(text))
+        return 'out_for_delivery';
+    if (/customs.*(?:cleared|released)|clearance completed/.test(text))
+        return 'in_transit';
+    if (/customs|clearance/.test(text))
+        return 'customs';
+    if (/label created|manifest data received|en route to dhl ecommerce or awaiting processing|electronic|information received/.test(text))
+        return 'registered';
+    if (/package received at dhl|picked up|accepted/.test(text))
+        return 'accepted';
+    if (/^(?:close bag|scanned into sack\/container)$/.test(text))
+        return 'in_transit';
+    // A terminal provider code outranks an intuitive translated label.
+    if (event.statusCode === 'delivered')
+        return 'delivered';
+    const translated = trackingLanguageStage(String(event.description ?? ''));
+    if (translated)
+        return translated;
+    switch (event.statusCode) {
+        case 'transit': return 'in_transit';
+        case 'pre-transit': return 'registered';
+        case 'failure': return 'failed_attempt';
+        default: return 'pending';
+    }
+}
+export function statusFor(stage) {
+    if (stage === 'delivered')
+        return 'delivered';
+    if (stage === 'out_for_delivery' || stage === 'ready_for_pickup')
+        return 'out_for_delivery';
+    if (['exception', 'failed_attempt', 'returned'].includes(stage))
+        return 'exception';
+    if (stage === 'registered' || stage === 'pending')
+        return 'pending';
+    return 'in_transit';
+}

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

@@ -0,0 +1,23 @@
+{
+  "carrier": "dhl-ecommerce",
+  "entries": [
+    { "code": "pre-transit", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "UTAPI status code, read only when no wording rule matches." },
+    { "code": "transit", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "failure", "language": "en", "stage": "failed_attempt", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "delivered", "language": "en", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Terminal: this code outranks an intuitive translation of the wording." },
+    { "code": "pre-transit", "wording": "LABEL CREATED", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "MANIFEST DATA RECEIVED", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen without a usable status code." },
+    { "code": "transit", "wording": "EN ROUTE TO DHL ECOMMERCE OR AWAITING PROCESSING", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Announced by the sender; the transit code would overstate progress." },
+    { "code": "transit", "wording": "PACKAGE RECEIVED AT DHL ECOMMERCE DISTRIBUTION CENTER", "language": "en", "stage": "accepted", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Picked up at parcelshop", "language": "en", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Sender-side drop-off (ha-dhl-nl#15): the parcel enters the network, it does not await collection." },
+    { "code": "transit", "wording": "CLOSE BAG", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-12", "note": "Also SCANNED INTO SACK/CONTAINER." },
+    { "code": "transit", "wording": "CUSTOMS CLEARANCE", "language": "en", "stage": "customs", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "transit", "wording": "CUSTOMS CLEARED", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Clearance completed leaves customs." },
+    { "code": "transit", "wording": "OUT FOR DELIVERY", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "transit", "wording": "READY FOR COLLECTION", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "failure", "wording": "DELIVERY ATTEMPT FAILED", "language": "en", "stage": "failed_attempt", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Carrier exception", "language": "en", "stage": "exception", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Wording rule, checked after the failed-attempt rule. Reclassified to exception 2026-09-12." },
+    { "code": "delivered", "wording": "RETURNED TO SENDER", "language": "en", "stage": "returned", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Also reached through returnFlag with the delivered code." },
+    { "code": "delivered", "wording": "DELIVERED - Signed by …", "language": "en", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "The signatory is never retained: a delivered event's description is replaced by \"Delivered\"." }
+  ]
+}

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

@@ -0,0 +1,70 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { ChallengeError, IndeterminateError, NotFoundError, type CarrierErrorOptions } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import type { StepRecorder } from '../../core/telemetry/index.js';
+import { TrawlClient } from '../../core/transport/index.js';
+/** Cloudflare interrupted the consignee page with an interactive challenge. */
+export declare class DPDChallengeError extends ChallengeError {
+    constructor(message?: string, options?: CarrierErrorOptions);
+}
+/**
+ * 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.
+ */
+export declare class DPDAPIError extends IndeterminateError {
+    constructor(message: string, options?: CarrierErrorOptions);
+}
+/** DPD positively reports that it does not know the parcel number. */
+export declare class DPDTrackingError extends NotFoundError {
+    constructor(options?: CarrierErrorOptions);
+}
+export declare function dpdTrackingUrl(trackingNumber: string, language?: string): string;
+export declare function parseDPDTrackingApi(payload: unknown, trackingNumber: string, postcodeVerified?: boolean): CarrierResult;
+export declare function parseDPDTrackingHtml(html: string, trackingNumber: string): CarrierResult;
+export interface DPDTrackerOptions {
+    timeoutMs?: number;
+    /** Whole-lookup budget; defaults to both tiers plus the solver's own allowance. */
+    budgetMs?: number;
+    /** Legacy configuration seam kept for tests; production passes `trawl`. */
+    flaresolverrUrl?: string;
+    firebaseApiKey?: string;
+    fetcher?: typeof fetch;
+    trawl?: TrawlClient | null;
+    recorder?: StepRecorder;
+}
+export declare class DPDTracker {
+    #private;
+    readonly timeoutMs: number;
+    readonly budgetMs: number;
+    readonly flaresolverrUrl: string;
+    readonly firebaseApiKey: string;
+    private readonly fetcher?;
+    private readonly trawl?;
+    private readonly recorder?;
+    constructor(options?: DPDTrackerOptions);
+    /** The browser service, resolved late so a malformed URL fails the page step, not construction. */
+    private browserService;
+    fetch(trackingNumber: string, postcode?: string): Promise<CarrierResult>;
+    /**
+     * Whether DPD knows a 14-digit number, for the host's carrier-detection
+     * route, which promotes the number to `dpd` only when this returns true.
+     * Guest API only, never the page tier. A positive not-found (404) and a
+     * details lookup DPD refuses without the postcode (400, seen for old
+     * parcels) are false; any other failure, a 400 from a token step included,
+     * stays a failure.
+     */
+    recognizes(trackingNumber: string): Promise<boolean>;
+    private apiFetch;
+    private detailsWithFreshToken;
+    private parcelDetails;
+    private accessToken;
+    private refreshAccessToken;
+    private fetchBasicToken;
+    private firebaseInstallation;
+    private firebaseHeaders;
+    private requestJson;
+    private pageFetch;
+    private directGet;
+}
+export declare const adapter: AdapterFactory;