universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/dhl/adapter.js

@@ -0,0 +1,308 @@
+/**
+ * DHL Paket and tracked mail, through the public recipient endpoint behind
+ * www.dhl.de (`/int-verfolgen/data`).
+ *
+ * The lookup establishes a cookie and CSRF session on `/config`, then reads
+ * `/search` with the same `verfolgen-CSRF-token` and `verfolgen-wg` headers
+ * DHL's own recipient page sends. Cookies stay in memory. A rejected or
+ * expired session, and an interrupted read, get one fresh HTTP session inside
+ * the `direct` step; only then does the `trawl` step ask the private browser
+ * service for a solved session, whose cookies and user agent seed a new HTTP
+ * session. Rate limits and server errors stay errors: they are never routed
+ * through a browser.
+ *
+ * DHL's business API credentials are not needed for this public flow.
+ */
+import makeFetchCookie from 'fetch-cookie';
+import { Cookie, CookieJar } from 'tough-cookie';
+import { ChallengeError, IndeterminateError, InputRequiredError, RateLimitedError, SchemaError, } from '../../core/errors/index.js';
+import { carrierIdFromPartnerLinks } from '../../core/catalog/hints.js';
+import { runSteps, singleFlight } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { isoTime } from '../../core/time/index.js';
+import { clean as cleanText, fetchBounded, parseJsonBytes, TrawlClient, UpstreamHttpError, UpstreamNetworkError, } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { stageForText, statusForStage } from './status.js';
+const PROVIDER = 'DHL';
+const TIMEZONE = 'Europe/Berlin';
+const ORIGIN = 'https://www.dhl.de';
+const DATA_PATH = '/int-verfolgen/data';
+const CONFIG_URL = `${ORIGIN}${DATA_PATH}/config?domain=de&language=en`;
+const TRACKING_PAGE = `${ORIGIN}/en/privatkunden/dhl-sendungsverfolgung.html`;
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36';
+const MAX_BYTES = 2_000_000;
+/**
+ * DHL status wording occasionally carries 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 normalizeDHLTrackingNumber(raw) {
+    const value = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^[A-Z0-9]{5,40}$/.test(value))
+        throw new TypeError('DHL tracking number is invalid');
+    return value;
+}
+export function dhlTrackingUrl(number) {
+    const url = new URL(TRACKING_PAGE);
+    url.searchParams.set('piececode', normalizeDHLTrackingNumber(number));
+    return url.toString();
+}
+/**
+ * DHL timestamps carry their own offset and its delivery window is a calendar
+ * day; both are kept verbatim rather than normalized, so `core/time` is used
+ * to validate them in the German zone only.
+ */
+function date(value) {
+    const raw = clean(value, 64);
+    if (!/^\d{4}-\d{2}-\d{2}(?:T[\d:.+-]+Z?)?$/.test(raw))
+        return '';
+    return isoTime(raw, TIMEZONE) ? raw : '';
+}
+function millis(value) {
+    return isoTime(value, TIMEZONE)?.timestamp ?? 0;
+}
+function noData() {
+    return { status: 'unknown', last_status_text: 'DHL has not published tracking information for this shipment yet', last_update: null, expected_delivery: null, events: [] };
+}
+/** Parse only public status fields: never persist recipient, address, signature or service data. */
+export function parseDHLTrackingResponse(payload, trackingNumber) {
+    const requested = normalizeDHLTrackingNumber(trackingNumber);
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER, 'DHL returned an invalid tracking response');
+    if (payload.rateLimited === true || payload.isRateLimited === true)
+        throw new RateLimitedError(PROVIDER);
+    if (!Array.isArray(payload.sendungen))
+        throw new SchemaError(PROVIDER, 'DHL returned an invalid tracking response');
+    if (payload.sendungen.length === 0)
+        throw new SchemaError(PROVIDER, 'DHL returned an empty tracking response');
+    const matches = payload.sendungen.filter(isRecord).filter((shipment) => {
+        const info = isRecord(shipment.sendungsinfo) ? shipment.sendungsinfo : {};
+        const details = isRecord(shipment.sendungsdetails) ? shipment.sendungsdetails : {};
+        const numbers = isRecord(details.sendungsnummern) ? details.sendungsnummern : {};
+        return [shipment.id, info.gesuchteSendungsnummer, numbers.sendungsnummer]
+            .some((value) => clean(value, 64).toUpperCase() === requested);
+    });
+    if (matches.length !== 1)
+        throw new SchemaError(PROVIDER, 'DHL did not return one matching shipment');
+    const shipment = matches[0];
+    if (shipment.plzBenoetigt === true || shipment.versandDatumBenoetigt === true) {
+        throw new InputRequiredError(PROVIDER, 'a postcode or shipping date', 'DHL requires additional verification on its tracking website');
+    }
+    const missing = isRecord(shipment.sendungNichtGefunden) ? shipment.sendungNichtGefunden : {};
+    if (missing.keineDhlPaketSendung === true || missing.sendungsnummerNichtSuchbar === true) {
+        throw new IndeterminateError(PROVIDER, 'This DHL service needs its own tracking website');
+    }
+    const details = isRecord(shipment.sendungsdetails) ? shipment.sendungsdetails : {};
+    const timeline = isRecord(details.sendungsverlauf) ? details.sendungsverlauf : {};
+    if (timeline.events !== undefined && !Array.isArray(timeline.events))
+        throw new SchemaError(PROVIDER, 'DHL returned invalid tracking events');
+    const events = (Array.isArray(timeline.events) ? timeline.events : []).filter(isRecord).flatMap((event) => {
+        const description = clean(event.status);
+        if (!description)
+            return [];
+        return [{ time: date(event.datum), location: clean(event.ort, 160), description, stage: stageForText(description) }];
+    }).sort((left, right) => millis(right.time) - millis(left.time)).slice(0, 100);
+    // Arrival notices link to the delivery operator. The catalog resolves its
+    // identity; the host still confirms progress through that operator's adapter.
+    const deliveryCarrier = carrierIdFromPartnerLinks(events.map((event) => event.description), 'dhl');
+    const summary = clean(timeline.status);
+    if (!events.length && !summary && details.istZugestellt !== true) {
+        if (Object.values(missing).some((flag) => flag === true))
+            return noData();
+        throw new SchemaError(PROVIDER, 'DHL returned no usable tracking status');
+    }
+    const currentText = summary || events[0]?.description || 'Delivered';
+    const fallback = Number(timeline.fortschritt) <= 1 ? 'registered' : String(events[0]?.stage || 'in_transit');
+    const stage = details.istZugestellt === true
+        ? details.ruecksendung === true ? 'returned' : 'delivered'
+        : stageForText(currentText, fallback);
+    const delivery = isRecord(details.zustellung) ? details.zustellung : {};
+    const expected = date(delivery.zustellzeitfensterVon) || date(delivery.zustellzeitfensterBis);
+    return {
+        status: statusForStage(stage), current_stage: stage,
+        last_status_text: currentText,
+        last_update: date(timeline.datumAktuellerStatus) || events[0]?.time || null,
+        expected_delivery: ['delivered', 'returned'].includes(stage) ? null : expected.slice(0, 10) || null,
+        timezone: TIMEZONE, events,
+        ...(deliveryCarrier ? { delivery_carrier: deliveryCarrier } : {}),
+    };
+}
+/**
+ * DHL answered with a redirect, an unauthorized status or a non-JSON body:
+ * the session is no longer accepted and has to be established again, from a
+ * browser when plain HTTP keeps being refused.
+ */
+export class DHLSessionError extends ChallengeError {
+    constructor(options) {
+        super(PROVIDER, 'DHL rejected the tracking session', options);
+        this.name = 'DHLSessionError';
+    }
+}
+/** A rejected session or an interrupted read may be retried; anything else is an answer. */
+/**
+ * DHL's edge stops answering a session about two hours after it was opened. It
+ * does not reject it: the request hangs until the timeout, and only then does
+ * the renewal below succeed in well under a second. Replace the session before
+ * that age so the refresh that crosses it does not wait out the timeout first.
+ */
+const SESSION_MAX_AGE_MS = 100 * 60_000;
+function renewable(error) {
+    return error instanceof DHLSessionError || error instanceof UpstreamNetworkError;
+}
+class DHLSession {
+    timeoutMs;
+    jar = new CookieJar();
+    fetcher;
+    userAgent = USER_AGENT;
+    token = '';
+    wg = '0';
+    constructor(timeoutMs, fetcher) {
+        this.timeoutMs = timeoutMs;
+        this.fetcher = makeFetchCookie(fetcher ?? fetch, this.jar);
+    }
+    async seed(cookies, userAgent) {
+        this.userAgent = clean(userAgent, 1_024) || USER_AGENT;
+        for (const value of cookies) {
+            if (!isRecord(value))
+                continue;
+            const domain = clean(value.domain).toLowerCase().replace(/^\./, '');
+            if (domain !== 'dhl.de' && !domain.endsWith('.dhl.de'))
+                continue;
+            const name = clean(value.name);
+            if (!name || typeof value.value !== 'string')
+                continue;
+            const path = clean(value.path).startsWith('/') ? clean(value.path) : '/';
+            await this.jar.setCookie(new Cookie({
+                key: name, value: value.value, domain, path,
+                secure: value.secure === true, httpOnly: value.httpOnly === true,
+                expires: typeof value.expires === 'number' && value.expires > 0 ? new Date(value.expires * 1_000) : 'Infinity',
+            }), `https://${domain}${path}`);
+        }
+    }
+    async fetch(number) {
+        if (!this.token) {
+            const config = await this.request(CONFIG_URL);
+            if (typeof config.verfolgenCsrfToken !== 'string' || !config.verfolgenCsrfToken)
+                throw new DHLSessionError();
+            this.token = config.verfolgenCsrfToken;
+            this.wg = typeof config.initialWG === 'number' ? String(config.initialWG) : '0';
+        }
+        const url = new URL(`${ORIGIN}${DATA_PATH}/search`);
+        url.search = new URLSearchParams({ piececode: number, noRedirect: 'true', language: 'en' }).toString();
+        return parseDHLTrackingResponse(await this.request(url), number);
+    }
+    async request(url) {
+        const { response, bytes } = await fetchBounded(url, { headers: {
+                Accept: 'application/json, text/plain, */*', 'Accept-Language': 'en-US,en;q=0.9',
+                'User-Agent': this.userAgent, Referer: TRACKING_PAGE,
+                'Sec-Fetch-Site': 'same-origin', 'Sec-Fetch-Mode': 'cors', 'Sec-Fetch-Dest': 'empty',
+                ...(this.token ? { 'verfolgen-CSRF-token': this.token, 'verfolgen-wg': this.wg } : {}),
+            } }, {
+            provider: PROVIDER, timeoutMs: this.timeoutMs, maxBytes: MAX_BYTES,
+            fetcher: this.fetcher, redirect: 'manual', allowHttpError: true,
+        });
+        if ([301, 302, 303, 307, 308, 401, 403, 419].includes(response.status))
+            throw new DHLSessionError();
+        if (!response.ok)
+            throw new UpstreamHttpError(PROVIDER, response.status);
+        if (!response.headers.get('content-type')?.includes('application/json'))
+            throw new DHLSessionError();
+        const value = parseJsonBytes(bytes, PROVIDER);
+        if (!isRecord(value))
+            throw new SchemaError(PROVIDER, 'DHL returned an invalid tracking response');
+        const token = response.headers.get('verfolgen-CSRF-token');
+        if (token)
+            this.token = token;
+        return value;
+    }
+}
+export class DHLTracker {
+    timeoutMs;
+    directTimeoutMs;
+    budgetMs;
+    trawlUrl;
+    trawl;
+    fetcher;
+    recorder;
+    serialize = singleFlight();
+    now;
+    session = null;
+    sessionOpenedAt = 0;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.directTimeoutMs = options.directTimeoutMs ?? 15_000;
+        // Two direct sessions (config plus search each) and a browser solve
+        // followed by the session it seeds, with room for the transport itself.
+        this.budgetMs = options.budgetMs ?? this.timeoutMs + 4 * this.directTimeoutMs + 30_000;
+        this.trawl = options.trawl ?? null;
+        this.trawlUrl = (options.trawlUrl ?? '').trim();
+        this.fetcher = options.fetcher;
+        this.recorder = options.recorder ?? NOOP_RECORDER;
+        this.now = options.now ?? Date.now;
+    }
+    open(session) {
+        this.session = session;
+        this.sessionOpenedAt = this.now();
+        return session;
+    }
+    /** Lookups share one session, so two parcels never renew it at the same time. */
+    async fetch(trackingNumber) {
+        const number = normalizeDHLTrackingNumber(trackingNumber);
+        return this.serialize(() => this.lookup(number));
+    }
+    async lookup(number) {
+        try {
+            return await runSteps({ carrier: 'dhl', budgetMs: this.budgetMs, recorder: this.recorder }, [
+                { id: 'direct', run: () => this.direct(number) },
+                { id: 'trawl', enabled: this.trawl !== null || this.trawlUrl !== '', recovers: renewable, run: () => this.browser(number) },
+            ]);
+        }
+        catch (error) {
+            // A session that ended the lookup is never reused by the next one.
+            if (renewable(error))
+                this.session = null;
+            throw error;
+        }
+    }
+    /** The direct session, renewing a stale one or an interrupted read once. */
+    async direct(number) {
+        if (this.session !== null && this.now() - this.sessionOpenedAt >= SESSION_MAX_AGE_MS)
+            this.session = null;
+        const cached = this.session !== null;
+        const session = this.session ?? this.open(new DHLSession(this.directTimeoutMs, this.fetcher));
+        try {
+            return await session.fetch(number);
+        }
+        catch (error) {
+            // A fresh session that was rejected outright needs a browser, not a
+            // second identical attempt; a cached one may simply have expired.
+            if (!renewable(error) || (!cached && !(error instanceof UpstreamNetworkError)))
+                throw error;
+            return await this.open(new DHLSession(this.directTimeoutMs, this.fetcher)).fetch(number);
+        }
+    }
+    /** A solved browser session, replayed over HTTP with its cookies and user agent. */
+    async browser(number) {
+        this.session = null;
+        const trawl = this.trawl ?? new TrawlClient(this.trawlUrl, this.fetcher);
+        const solved = await trawl.scrape({ url: dhlTrackingUrl(number), skipHttp: true, maxTier: 3, maxTimeout: this.timeoutMs }, { provider: `TRAWL while fetching ${PROVIDER}`, timeoutMs: this.timeoutMs, maxBytes: 10_000_000, fetcher: this.fetcher });
+        const session = new DHLSession(this.directTimeoutMs, this.fetcher);
+        await session.seed(solved.cookies, solved.userAgent);
+        const result = await session.fetch(number);
+        this.open(session);
+        return result;
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new DHLTracker({
+        fetcher: environment.fetcher, trawl: environment.trawl, trawlUrl: '', recorder: environment.recorder,
+    });
+    return {
+        id: 'dhl',
+        steps: ['direct', 'trawl'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/dhl/carrier.json

@@ -0,0 +1,98 @@
+{
+  "id": "dhl",
+  "displayName": "DHL",
+  "aliases": [
+    "DHL Paket",
+    "Deutsche Post DHL"
+  ],
+  "region": {
+    "countries": [
+      "DE"
+    ]
+  },
+  "brand": {
+    "color": "#ffcc00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Berlin",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "dhl",
+    "steps": [
+      "direct",
+      "trawl"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode={trackingNumber}",
+    "canaryUrl": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "dhl.com",
+        "dhl.de",
+        "deutschepost.de"
+      ],
+      "params": [
+        "tracking-id",
+        "trackingId",
+        "piececode"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "dhl-1",
+      "pattern": "^[CL][A-Z]\\d{9}DE$",
+      "confidence": "high",
+      "checksum": "s10"
+    },
+    {
+      "id": "dhl-2",
+      "pattern": "^(JJD|JVGL)[A-Z0-9]{8,}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dhl-3",
+      "pattern": "^\\d{10}$",
+      "confidence": "low"
+    },
+    {
+      "id": "dhl-4",
+      "pattern": "^JD\\d{18}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dhl-5",
+      "pattern": "^00340434\\d{12}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/dhl/numbers.json

@@ -0,0 +1,153 @@
+{
+  "carrier": "dhl",
+  "records": [
+    {
+      "number": "00340434633751428115",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.paketda.de/fragen-antworten",
+        "date": "2026-04-10"
+      },
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "8449089972",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://marketplace.fnacdarty.com/s/article/Dois-je-obligatoirement-renseigner-un-num%C3%A9ro-de-suivi-tracking-pour-ma-commande?language=fr_BE"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Published integration example, not a real shipment. The source attributes it to DHL, which stays one candidate among several."
+    },
+    {
+      "number": "CG738165082DE",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://fr.trustpilot.com/review/www.dhl.fr",
+        "date": "2026-08-31"
+      },
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "CY123456785DE",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "JD014600011678034918",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://marketplace.fnacdarty.com/s/article/Dois-je-obligatoirement-renseigner-un-num%C3%A9ro-de-suivi-tracking-pour-ma-commande?language=fr_BE"
+      },
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Published integration example, not a real shipment."
+    },
+    {
+      "number": "JJD0099999999",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "JVGL0099999999",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "LF123456785DE",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "LF123456785US",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format. Filed under DHL; detection falls back to the generic postal rule."
+    },
+    {
+      "number": "LF123456789DE",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "invented",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "chronopost"
+        ]
+      },
+      "note": "Invented placeholder used as a shape check. Filed under DHL, which no rule claims."
+    },
+    {
+      "number": "LX123456785DE",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dhl",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+/**
+ * DHL wording → product stage.
+ *
+ * DHL's public `/int-verfolgen/data` payload carries no status code: the
+ * shipment history is free text in the language the page was requested in
+ * (English here, with German wording still returned for domestic scans), so
+ * this map is a wording classifier rather than a code table. Rules are
+ * ordered so that a negative, a forecast or a handoff wins before the broad
+ * delivery words, and anything unrecognized keeps the caller's fallback
+ * instead of inventing progress.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+export declare function stageForText(text: string, fallback?: string): string;
+export declare function statusForStage(stage: string): CarrierStatus;

package/dist/carriers/dhl/status.js

@@ -0,0 +1,45 @@
+import { trackingLanguageStage } from '../../core/status/index.js';
+export function stageForText(text, fallback = 'in_transit') {
+    const value = text.toLowerCase();
+    if (/return(?:ed|ing)? to (?:the )?sender|zurück.*absender|rücksendung|retour/.test(value))
+        return 'returned';
+    if (/not delivered|could not be delivered|unable to deliver|delivery attempt|nicht.*zugestellt|zustellversuch|nicht angetroffen/.test(value))
+        return 'failed_attempt';
+    // GENERATED equivalents of DHL's existing forecast behavior: a forecast retains
+    // the structured progress fallback; it cannot establish delivery or pre-advice.
+    if (/will be delivered|sera livr[ée]|wird\s+(?!zugestellt\b).+zugestellt|sar[àa] consegnat/.test(value))
+        return fallback;
+    const translated = trackingLanguageStage(text);
+    if (translated)
+        return translated;
+    if (/ready for (?:pickup|collection)|ready to (?:collect|pick up)|awaiting collection|abholbereit|zur abholung bereit/.test(value))
+        return 'ready_for_pickup';
+    if (/has been delivered|was delivered|successfully delivered|^delivered\b|erfolgreich zugestellt|wurde.*zugestellt/.test(value))
+        return 'delivered';
+    if (/^being delivered[.!]?$|out for delivery|loaded (?:into|onto).*delivery vehicle|in das zustellfahrzeug geladen|in zustellung/.test(value))
+        return 'out_for_delivery';
+    if (/customs clearance process\b[^.]*\bhas been completed\b/.test(value))
+        return 'in_transit';
+    if (/customs|zoll/.test(value))
+        return 'customs';
+    if (/electronically|elektronisch|label created|shipment information|instruction data/.test(value))
+        return 'registered';
+    if (/will be transported to the destination country/.test(value))
+        return 'in_transit';
+    if (/pick-up was successful|accepted|handed (?:over|to)|eingeliefert|übergeben/.test(value))
+        return 'accepted';
+    if (/processed|sorted|sorting|sortierung|bearbeitet|briefzentrum|paketzentrum|transit|transport|arrived|departed/.test(value))
+        return 'in_transit';
+    return fallback;
+}
+export function statusForStage(stage) {
+    if (stage === 'registered' || stage === 'pending')
+        return 'pending';
+    if (stage === 'delivered')
+        return 'delivered';
+    if (stage === 'out_for_delivery' || stage === 'ready_for_pickup')
+        return 'out_for_delivery';
+    if (stage === 'failed_attempt' || stage === 'returned')
+        return 'exception';
+    return 'in_transit';
+}

package/dist/carriers/dhl/statuses.json

@@ -0,0 +1,27 @@
+{
+  "carrier": "dhl",
+  "entries": [
+    { "wording": "The instruction data for this shipment have been provided by the sender to DHL electronically", "language": "en", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Pre-advice; matched on \"electronically\"." },
+    { "wording": "Die Sendung wurde vom Absender elektronisch angekündigt.", "language": "de", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "German pre-advice; matched on \"elektronisch\"." },
+    { "wording": "The shipment was handed over to DHL.", "language": "en", "stage": "accepted", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung wurde im Briefzentrum bearbeitet.", "language": "de", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Mail-centre processing scan." },
+    { "wording": "The shipment has been processed in the parcel center", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "The shipment will be transported to the destination country/destination area and, from there, handed over to the delivery organization.", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Explicitly transit, never the handover it announces." },
+    { "wording": "The shipment has arrived in the destination country/destination area.", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Carries the destination operator's link; an exact post.ch host marks a Swiss Post last mile." },
+    { "wording": "The shipment is being processed by customs", "language": "en", "stage": "customs", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "The customs clearance process for import into the destination country/region has been completed.", "language": "en", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Completion leaves customs; the started variant stays in customs." },
+    { "wording": "The shipment has been loaded into the delivery vehicle", "language": "en", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung wurde in das Zustellfahrzeug geladen.", "language": "de", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "The shipment is ready for collection", "language": "en", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung liegt zur Abholung bereit.", "language": "de", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "The shipment has been delivered", "language": "en", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung wurde erfolgreich zugestellt.", "language": "de", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "The negated form maps to failed_attempt, not delivery." },
+    { "wording": "The shipment could not be delivered", "language": "en", "stage": "failed_attempt", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung konnte nicht zugestellt werden.", "language": "de", "stage": "failed_attempt", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "Die Sendung wurde nicht erfolgreich zugestellt.", "language": "de", "stage": "failed_attempt", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Negation is matched before the delivery wording." },
+    { "wording": "The shipment is returning to sender", "language": "en", "stage": "returned", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "The shipment will be delivered tomorrow", "language": "en", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Forecast: deliberately unmapped. It keeps the structured progress fallback rather than announcing delivery or pre-advice." },
+    { "code": "istZugestellt=true", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Structured completion flag; outranks the wording." },
+    { "code": "istZugestellt=true,ruecksendung=true", "stage": "returned", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "A completed return, not a delivery." }
+  ]
+}