universal-parcel-scraper 0.31.0-main.374 → 0.32.0-main.376

package/README.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 2,188 such statuses, each filed under one stage.
+The carrier folders record 2,204 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

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

@@ -35,6 +35,15 @@ export interface DPDTrackerOptions {
     trawl?: TrawlClient | null;
     recorder?: StepRecorder;
     userAgent?: string;
+    /** A further German tier, and the failures of the guest tier it may answer after. */
+    app?: DPDAppTier;
+}
+export interface DPDAppTier {
+    run(number: string, context: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<CarrierResult>;
+    recovers(error: unknown): boolean;
 }
 export declare class DPDTracker {
     #private;
@@ -47,6 +56,7 @@ export declare class DPDTracker {
     private readonly trawl?;
     private readonly recorder?;
     private readonly userAgent;
+    private readonly app?;
     constructor(options?: DPDTrackerOptions);
     /** The browser service, resolved late so a malformed URL fails the page step, not construction. */
     private browserService;

package/dist/carriers/dpd/adapter.js

@@ -501,6 +501,7 @@ export class DPDTracker {
     trawl;
     recorder;
     userAgent;
+    app;
     #accessToken = '';
     #accessTokenExpiresAt = 0;
     #basicToken = '';
@@ -519,6 +520,7 @@ export class DPDTracker {
         this.trawl = options.trawl;
         this.recorder = options.recorder;
         this.userAgent = userAgentOf(options.userAgent);
+        this.app = options.app;
     }
     /** The browser service, resolved late so a malformed URL fails the page step, not construction. */
     browserService() {
@@ -567,6 +569,10 @@ export class DPDTracker {
                     id: 'page',
                     recovers: pageRecovers,
                     run: ({ previousError }) => this.pageFetch(trackingNumber, previousError !== undefined, lookup),
+                }] : this.app ? [{
+                    id: 'app',
+                    recovers: (error) => !context.signal?.aborted && this.app.recovers(error),
+                    run: ({ signal, remainingMs }) => this.app.run(trackingNumber, { signal, timeoutMs: remainingMs }),
                 }] : []),
         ]);
         result.tracking_url = this.country === 'DE'
@@ -629,7 +635,7 @@ export class DPDTracker {
         if (this.country === 'DE' && isRecord(payload.status)) {
             const country = known(payload.status.countryCode).toUpperCase();
             if (/^[A-Z]{2}$/.test(country) && country !== 'DE') {
-                throw new IndeterminateError('DPD Germany', 'DPD returned activity in another country');
+                throw new IndeterminateError('DPD Germany', 'DPD returned activity in another country', { reason: 'other_country' });
             }
         }
         if (this.country === 'DE')

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

@@ -1,3 +1,3 @@
 import type { AdapterFactory } from '../../core/adapter/index.js';
-/** Germany uses the same guest protocol, with its own business-unit selector. */
+/** Germany uses the same guest protocol, with its own business-unit selector, then the German app's service. */
 export declare const adapter: AdapterFactory;

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

@@ -1,15 +1,25 @@
+import { CarrierError, carrierErrorKind } from '../../core/errors/index.js';
+import { recoverableByDefault } from '../../core/runner/index.js';
 import { DPDTracker } from '../dpd/adapter.js';
-/** Germany uses the same guest protocol, with its own business-unit selector. */
+import { DPD_DE_OTHER_COUNTRY, DpdDeAppClient } from './app.js';
+/** Germany uses the same guest protocol, with its own business-unit selector, then the German app's service. */
 export const adapter = (environment) => {
+    const app = new DpdDeAppClient({ fetcher: environment.fetcher, userAgent: environment.userAgent });
     const tracker = new DPDTracker({
         country: 'DE',
         fetcher: environment.fetcher,
         firebaseApiKey: environment.env.DPD_FIREBASE_API_KEY,
         recorder: environment.recorder,
         userAgent: environment.userAgent,
+        app: {
+            run: (number, context) => app.track(number, context),
+            // The app reads the same parcel, so it cannot place another country's delivery in Germany.
+            recovers: error => (recoverableByDefault(error) || carrierErrorKind(error) === 'schema')
+                && !(error instanceof CarrierError && error.reason === DPD_DE_OTHER_COUNTRY),
+        },
     });
     return {
-        id: 'dpd-de', recordsSteps: true, steps: ['direct'],
+        id: 'dpd-de', recordsSteps: true, steps: ['direct', 'app'],
         track: (input, context) => tracker.fetch(input.number, input.postcode ?? '', context),
     };
 };

package/dist/carriers/dpd-de/app.d.ts

@@ -0,0 +1,37 @@
+import type { CarrierResult } from '../../core/result/index.js';
+import type { ClassifiedStatus, Stage } from '../../core/status/index.js';
+import { type XmlNode } from '../../core/transport/xml.js';
+export declare const DPD_DE_APP_API = "https://api.paketnavigator.de/services/v1/Navigator3Service.asmx";
+/** Activity the service places outside Germany; the app tier would read the same parcel. */
+export declare const DPD_DE_OTHER_COUNTRY = "other_country";
+export interface DpdDePartner {
+    name: string;
+    token: string;
+    password: string;
+}
+/** The app's progress rail: one coarse state for the whole parcel. */
+export declare const DPD_DE_APP_RAIL: Readonly<Record<string, ClassifiedStatus>>;
+/** Scans carry wording only. The shared classifier misreads several of these, so each is mapped whole. */
+export declare const DPD_DE_APP_SCANS: Readonly<Record<string, Stage>>;
+/** Scans arrive oldest first, with a facility's wall clock and no offset. */
+export declare function parseDpdDeApp(data: XmlNode, scans: XmlNode, number: string): CarrierResult;
+/**
+ * The German app's SOAP service. Tracking needs an anonymous device session, which the
+ * service takes tens of seconds to open and then accepts for hours: one is kept per client.
+ */
+export declare class DpdDeAppClient {
+    #private;
+    constructor(options?: {
+        partner?: DpdDePartner;
+        fetcher?: typeof fetch;
+        userAgent?: string;
+        now?: () => number;
+    });
+    track(number: string, options: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<CarrierResult>;
+    /** One session for every lookup; the lookup that opens it lends its signal, the others only wait. */
+    private session;
+    private call;
+}

package/dist/carriers/dpd-de/app.js

@@ -0,0 +1,229 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { CarrierError, ChallengeError, IndeterminateError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { clean, decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { xmlDocument } from '../../core/transport/xml.js';
+export const DPD_DE_APP_API = 'https://api.paketnavigator.de/services/v1/Navigator3Service.asmx';
+/** Activity the service places outside Germany; the app tier would read the same parcel. */
+export const DPD_DE_OTHER_COUNTRY = 'other_country';
+const SOAP = 'http://schemas.xmlsoap.org/soap/envelope/';
+const SERVICE = 'https://cloud.dpd.com/';
+const MAX_BYTES = 2_000_000;
+// Shared partner credentials of the public app, distributed with the maintainer's approval.
+const PARTNER = { name: 'Android Paketnavigator3', token: 'A33363237662F5945576', password: '272 WetFd2mpXrgD' };
+/** The app's progress rail: one coarse state for the whole parcel. */
+export const DPD_DE_APP_RAIL = {
+    ACCEPTED: { status: 'pending', stage: 'registered' },
+    ON_THE_ROAD: { status: 'in_transit', stage: 'in_transit' },
+    AT_DELIVERY_DEPOT: { status: 'in_transit', stage: 'in_transit' },
+    OUT_FOR_DELIVERY: { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    DELIVERED: { status: 'delivered', stage: 'delivered' },
+};
+/** Scans carry wording only. The shared classifier misreads several of these, so each is mapped whole. */
+export const DPD_DE_APP_SCANS = {
+    'Order information has been transmitted to DPD.': 'registered',
+    'Parcel handed to Pickup parcelshop by consignor.': 'accepted',
+    'In transit.': 'in_transit',
+    'At parcel delivery centre.': 'in_transit',
+    'Transfer to DPD Pickup station by DPD driver.': 'in_transit',
+    'Out for delivery.': 'out_for_delivery',
+    'Unfortunately we have not been able to deliver your parcel.': 'failed_attempt',
+    "We're sorry but your parcel couldn't be delivered as arranged.": 'exception',
+    'Delivered by driver to DPD Pickup parcelshop/ station.': 'ready_for_pickup',
+    'Picked up from DPD Pickup station by consignee.': 'delivered',
+    'Delivered.': 'delivered',
+};
+function invalid() { throw new SchemaError('DPD Germany', 'DPD Germany returned invalid tracking XML'); }
+function children(node, name, uri = SERVICE) {
+    return node.children.filter(child => child.name === name && child.uri === uri);
+}
+function one(node, name, uri = SERVICE) {
+    const matches = children(node, name, uri);
+    return matches.length === 1 ? matches[0] : invalid();
+}
+function scalar(node, name, max = 200) {
+    const matches = children(node, name);
+    if (matches.length > 1 || matches[0]?.children.length)
+        invalid();
+    return clean(matches[0]?.text ?? '', max);
+}
+const escaped = (value) => value.replace(/[<>&"']/g, character => `&#${character.charCodeAt(0)};`);
+const elements = (fields) => Object.entries(fields)
+    .map(([name, value]) => `<${name}>${typeof value === 'string' ? escaped(value) : elements(value)}</${name}>`).join('');
+class SessionExpired extends Error {
+}
+function statusOf(stage) {
+    if (stage === 'delivered' || stage === 'out_for_delivery' || stage === 'exception')
+        return stage;
+    if (stage === 'registered')
+        return 'pending';
+    return stage ? 'in_transit' : 'unknown';
+}
+/** Scans arrive oldest first, with a facility's wall clock and no offset. */
+export function parseDpdDeApp(data, scans, number) {
+    const tracking = one(data, 'TrackingData');
+    if (scalar(tracking, 'ParcelNo', 40) !== number)
+        throw new SchemaError('DPD Germany', 'DPD Germany returned a different parcel');
+    // The service also answers for parcels delivered elsewhere in the group.
+    const destination = scalar(one(tracking, 'ShipAddress'), 'Country', 8);
+    if (/^[A-Z]{2}$/.test(destination) && destination !== 'DE') {
+        throw new IndeterminateError('DPD Germany', 'DPD returned activity in another country', { reason: DPD_DE_OTHER_COUNTRY });
+    }
+    const rows = children(one(scans, 'TrackingScanList'), 'TrackingScan');
+    if (rows.length > 500)
+        invalid();
+    const events = [];
+    const seen = new Set();
+    for (const row of rows) {
+        const wording = scalar(row, 'StatusText', 500);
+        const day = scalar(row, 'ScanDate', 16);
+        const time = scalar(row, 'ScanTime', 16);
+        if (!wording || !/^\d{2}\.\d{2}\.\d{4}$/.test(day) || !/^\d{2}:\d{2}$/.test(time))
+            invalid();
+        // An announced delivery day is not a scan.
+        if (/^Your parcel is estimated to be delivered\b/i.test(wording))
+            continue;
+        const place = /^(.{1,120}) \(([A-Z]{2})\)$/.exec(scalar(row, 'Location'));
+        // German facilities keep German civil time; a clock elsewhere has no established zone.
+        const clock = zonedTime(`${day} ${time}`, 'dd.MM.yyyy HH:mm', place?.[2] === 'DE' ? 'Europe/Berlin' : 'UTC');
+        if (!clock)
+            invalid();
+        const stage = DPD_DE_APP_SCANS[wording];
+        const event = {
+            ...(place?.[2] === 'DE' ? { time: clock.iso } : { local_time: clock.iso.slice(0, 19), provider_time_text: `${day} ${time}` }),
+            ...(place ? { location: `${place[1]}, ${place[2]}` } : {}),
+            description: /\b(?:delivered to|signed (?:for )?by|received by)\b/i.test(wording) ? 'Delivery update' : wording,
+            ...(stage ? { stage, stage_source: 'carrier_map' } : {}),
+        };
+        // Reason codes, shop names and service descriptions are not projected.
+        const identity = JSON.stringify(event);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        events.push(event);
+    }
+    if (!events.length)
+        throw new IndeterminateError('DPD Germany', 'DPD Germany returned no parcel scans');
+    events.reverse();
+    const current = events[0];
+    const rail = DPD_DE_APP_RAIL[scalar(one(tracking, 'LastStatusInfo'), 'StatusID', 64)];
+    const stage = current.stage ?? rail?.stage;
+    const kilograms = Number(scalar(one(tracking, 'OrderInfo'), 'Weight', 16).replace(',', '.'));
+    return {
+        status: rail?.status ?? statusOf(current.stage), ...(stage ? { current_stage: stage, current_stage_source: 'carrier_map' } : {}),
+        last_status_text: current.description ?? null, last_update: current.time ?? null,
+        ...(current.time ? {} : { last_update_local: current.local_time }),
+        ...(Number.isFinite(kilograms) && kilograms > 0 ? { weight_kg: kilograms } : {}),
+        events: events.slice(0, 100),
+    };
+}
+/**
+ * The German app's SOAP service. Tracking needs an anonymous device session, which the
+ * service takes tens of seconds to open and then accepts for hours: one is kept per client.
+ */
+export class DpdDeAppClient {
+    #partner;
+    #fetcher;
+    #userAgent;
+    #now;
+    #device = randomBytes(8).toString('hex');
+    #session = '';
+    #opening = null;
+    constructor(options = {}) {
+        this.#partner = options.partner ?? PARTNER;
+        this.#fetcher = options.fetcher;
+        this.#userAgent = userAgentOf(options.userAgent);
+        this.#now = options.now ?? Date.now;
+    }
+    async track(number, options) {
+        if (!/^\d{14}$/.test(number))
+            throw new TypeError('DPD Germany app tracking takes 14 digits');
+        const deadline = performance.now() + options.timeoutMs;
+        const left = () => Math.max(1, Math.floor(deadline - performance.now()));
+        try {
+            for (let attempt = 0;; attempt += 1) {
+                const session = await this.session(options.signal, left());
+                try {
+                    const data = await this.call('getTrackingData', { SessionToken: session, ParcelNo: number, DeliveryZipCode: '',
+                        UpdateNewDeliveryData: 'false', addParcelIfNoTrackingdataAvailable: 'false', ParcelFlowTypeID: 'receiving' }, options.signal, left());
+                    const scans = await this.call('getTrackingScanList', { SessionToken: session, ParcelNo: number, DeliveryZipCode: '' }, options.signal, left());
+                    return parseDpdDeApp(data, scans, number);
+                }
+                catch (error) {
+                    if (!(error instanceof SessionExpired) || attempt)
+                        throw error;
+                    if (this.#session === session)
+                        this.#session = '';
+                }
+            }
+        }
+        catch (error) {
+            options.signal.throwIfAborted();
+            // Transport diagnostics include the credentials, the session and recipient XML.
+            // Preserve the failure contract without forwarding request or body data.
+            if (error instanceof CarrierError)
+                throw new CarrierError(error.kind, 'DPD Germany', `DPD Germany app tracking failed (${error.kind})`, {
+                    status: error.status, retryAfterMs: error.retryAfterMs, reason: error.reason,
+                });
+            throw new TransportError('DPD Germany', 'DPD Germany app request failed');
+        }
+    }
+    /** One session for every lookup; the lookup that opens it lends its signal, the others only wait. */
+    async session(signal, timeoutMs) {
+        if (this.#session)
+            return this.#session;
+        if (!this.#opening) {
+            const opening = this.call('getSessionFullState', { SessionToken: '', DeviceData: {
+                    HardwareID: this.#device, BootSystemID: 'Android_Phone', Version: '15', AppVersion: '4.2.0',
+                } }, signal, timeoutMs).then(result => {
+                const token = scalar(one(result, 'SessionFullState'), 'SessionToken', 600);
+                if (!/^[A-Za-z0-9+/=]{16,512}$/.test(token))
+                    invalid();
+                return this.#session = token;
+            });
+            this.#opening = opening;
+            void opening.catch(() => undefined).finally(() => { if (this.#opening === opening)
+                this.#opening = null; });
+        }
+        const shared = this.#opening;
+        signal.throwIfAborted();
+        let leave;
+        const left = new Promise((_resolve, reject) => { leave = () => reject(signal.reason); });
+        signal.addEventListener('abort', leave, { once: true });
+        try {
+            return await Promise.race([shared, left]);
+        }
+        finally {
+            signal.removeEventListener('abort', leave);
+        }
+    }
+    async call(operation, fields, signal, timeoutMs) {
+        // The service checks a key derived from the minute of the UTC day.
+        const now = new Date(this.#now());
+        const phase = String((now.getUTCHours() * 60 + now.getUTCMinutes() + 1000) * 3);
+        const key = phase + createHash('md5').update(`${phase}${this.#partner.name}0${operation}${this.#partner.password}`).digest('base64').slice(0, 16);
+        const body = `<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="${SOAP}"><soap:Body><${operation} xmlns="${SERVICE}"><${operation}Request>${elements({
+            Version: '100', Language: 'de_EN', PartnerCredentials: { Name: this.#partner.name, Token: this.#partner.token, KeyPhase: key }, ...fields,
+        })}</${operation}Request></${operation}></soap:Body></soap:Envelope>`;
+        const { response, bytes } = await fetchBounded(DPD_DE_APP_API, { method: 'POST', signal, body,
+            headers: { 'Content-Type': 'text/xml; charset=utf-8', SOAPAction: `"${SERVICE}${operation}"`, Accept: 'text/xml', 'User-Agent': this.#userAgent } }, {
+            provider: 'DPD Germany', maxBytes: MAX_BYTES, timeoutMs, fetcher: this.#fetcher, allowHttpStatuses: [404, 410],
+        });
+        if (response.status !== 200)
+            throw new TransportError('DPD Germany', 'DPD Germany app service is unavailable', { status: response.status });
+        const root = xmlDocument(decodeText(bytes), MAX_BYTES) ?? invalid();
+        if (root.name !== 'Envelope' || root.uri !== SOAP)
+            invalid();
+        const result = one(one(one(root, 'Body', SOAP), `${operation}Response`), `${operation}Result`);
+        const codes = children(result, 'ErrorDataList').flatMap(list => children(list, 'ErrorData')).map(error => scalar(error, 'ErrorCode', 80));
+        if (codes.some(code => code === 'ERROR_PARTNER' || code === 'ERROR_KEYPHASE')) {
+            throw new ChallengeError('DPD Germany', 'DPD Germany refused the app credential');
+        }
+        if (codes.includes('ERROR_SESSION_NOT_VALID'))
+            throw new SessionExpired();
+        // "No tracking data" also answers for parcels the scan list still knows: it proves no absence.
+        if (scalar(result, 'Ack', 8) !== 'true')
+            throw new IndeterminateError('DPD Germany', 'DPD Germany returned no confirmed parcel');
+        return result;
+    }
+}

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

@@ -18,7 +18,8 @@
     "mode": "automatic",
     "adapter": "dpd-de",
     "steps": [
-      "direct"
+      "direct",
+      "app"
     ],
     "requirements": [
       {

package/dist/carriers/dpd-de/statuses.json

@@ -33,6 +33,139 @@
       "confirmedBy": "live",
       "firstSeen": "2026-10-05",
       "note": "A retry, not a terminal state: the result status stays in_transit."
+    },
+    {
+      "wording": "Order information has been transmitted to DPD.",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "Parcel handed to Pickup parcelshop by consignor.",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "In transit.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "At parcel delivery centre.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "Transfer to DPD Pickup station by DPD driver.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "Out for delivery.",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "wording": "Unfortunately we have not been able to deliver your parcel.",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only. Matches the guest API's UNSUCCESSFUL_DELIVERY_ATTEMPT at the same minute."
+    },
+    {
+      "wording": "We're sorry but your parcel couldn't be delivered as arranged.",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only. Mapped whole because the shared classifier reads it as a delivery."
+    },
+    {
+      "wording": "Delivered by driver to DPD Pickup parcelshop/ station.",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only. Mapped whole because the shared classifier reads it as a delivery."
+    },
+    {
+      "wording": "Picked up from DPD Pickup station by consignee.",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only. Mapped whole because the shared classifier reads it as an acceptance."
+    },
+    {
+      "wording": "Delivered.",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "Seen in the German app's scan list, which carries wording only."
+    },
+    {
+      "code": "ACCEPTED",
+      "wording": "Paketinfo an DPD übergeben",
+      "language": "de",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "The German app's progress rail, one state for the whole parcel."
+    },
+    {
+      "code": "ON_THE_ROAD",
+      "wording": "Paket unterwegs",
+      "language": "de",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "The German app's progress rail, one state for the whole parcel."
+    },
+    {
+      "code": "AT_DELIVERY_DEPOT",
+      "wording": "At parcel delivery centre",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "The German app's progress rail, one state for the whole parcel."
+    },
+    {
+      "code": "DELIVERED",
+      "wording": "Parcel delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "The German app's progress rail, one state for the whole parcel."
+    },
+    {
+      "code": "OUT_FOR_DELIVERY",
+      "wording": "In Zustellung",
+      "language": "de",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-10-07",
+      "note": "The German app's progress rail, one state for the whole parcel. Seen as a state the parcel had not reached."
     }
   ]
 }

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

@@ -5,6 +5,10 @@ export declare class EvriUkTracker {
     constructor(options?: {
         executablePath?: string | null;
         recorder?: StepRecorder;
+        fetcher?: typeof fetch;
+        userAgent?: string;
+        /** Guest API key. Omit for the included key; null or blank leaves the page as the only tier. */
+        key?: string | null;
     });
     fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
 }

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

@@ -1,9 +1,12 @@
-import { carrierErrorKind, ChallengeError, IndeterminateError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
-import { runSteps } from '../../core/runner/index.js';
+import { CarrierError, carrierErrorKind, ChallengeError, IndeterminateError, RateLimitedError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { recoverableByDefault, runSteps } from '../../core/runner/index.js';
 import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { withLocalBrowser } from '../../core/transport/localBrowser.js';
 import { requestEvriUkInPage } from './browser.js';
+import { EVRI_UK_UNCONFIRMED, readEvriUkMobile } from './mobile.js';
 import { normalizeEvriUkNumber, parseEvriUk } from './parser.js';
+/** How long the guest API may take while the page can still answer. */
+const DIRECT_TIMEOUT_MS = 10_000;
 export class EvriUkTracker {
     options;
     constructor(options = {}) {
@@ -14,10 +17,20 @@ export class EvriUkTracker {
         const budgetMs = context.budgetMs ?? 45_000;
         if (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > 60_000)
             throw new TypeError('Evri UK budget must be between 1 and 60000 ms');
-        if (!this.options.executablePath)
+        const direct = this.options.key === undefined || Boolean(this.options.key?.trim());
+        const browser = Boolean(this.options.executablePath);
+        if (!direct && !browser)
             throw new ChallengeError('Evri UK', 'Evri UK requires TRACKING_CHROMIUM_PATH');
         return runSteps({ carrier: 'evri-uk', budgetMs, signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [{
-                id: 'browser', run: ({ signal, remainingMs: remaining }) => withLocalBrowser({ provider: 'Evri UK',
+                id: 'direct', enabled: direct, run: ({ signal, remainingMs }) => readEvriUkMobile(number, {
+                    key: this.options.key, fetcher: this.options.fetcher, userAgent: this.options.userAgent, signal,
+                    timeoutMs: browser ? Math.min(remainingMs, DIRECT_TIMEOUT_MS) : remainingMs,
+                }),
+            }, {
+                id: 'browser', enabled: browser,
+                // The page reads the same history service, so its answer about the parcel would not differ.
+                recovers: error => recoverableByDefault(error) && !(error instanceof CarrierError && error.reason === EVRI_UK_UNCONFIRMED),
+                run: ({ signal, remainingMs: remaining }) => withLocalBrowser({ provider: 'Evri UK',
                     executablePath: this.options.executablePath, signal, timeoutMs: Math.max(1, Math.floor(remaining)),
                     args: ['--disable-blink-features=AutomationControlled'], }, async ({ browser, signal: session, remainingMs }) => {
                     try {
@@ -75,6 +88,9 @@ export class EvriUkTracker {
     }
 }
 export const adapter = environment => {
-    const tracker = new EvriUkTracker({ executablePath: environment.browserExecutablePath, recorder: environment.recorder });
-    return { id: 'evri-uk', recordsSteps: true, steps: ['browser'], track: (input, context) => tracker.fetch(input.number, context) };
+    const tracker = new EvriUkTracker({
+        executablePath: environment.browserExecutablePath, recorder: environment.recorder, fetcher: environment.fetcher,
+        userAgent: environment.userAgent, key: environment.env.EVRI_UK_TRACKING_KEY,
+    });
+    return { id: 'evri-uk', recordsSteps: true, steps: ['direct', 'browser'], track: (input, context) => tracker.fetch(input.number, context) };
 };

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

@@ -20,6 +20,7 @@
     "mode": "automatic",
     "adapter": "evri-uk",
     "steps": [
+      "direct",
       "browser"
     ]
   },

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

@@ -0,0 +1,11 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const EVRI_UK_MOBILE_API = "https://tracking.platform-apis.evri.com/v1";
+/** The history service answered and confirmed no domestic parcel activity; the page asks the same service. */
+export declare const EVRI_UK_UNCONFIRMED = "parcel_unconfirmed";
+export declare function readEvriUkMobile(raw: string, options: {
+    key?: string | null;
+    fetcher?: typeof fetch;
+    userAgent?: string;
+    signal: AbortSignal;
+    timeoutMs: number;
+}): Promise<CarrierResult>;

package/dist/carriers/evri-uk/mobile.js

@@ -0,0 +1,84 @@
+import { CarrierError, ChallengeError, IndeterminateError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { normalizeEvriUkNumber, parseEvriUk } from './parser.js';
+export const EVRI_UK_MOBILE_API = 'https://tracking.platform-apis.evri.com/v1';
+/** The history service answered and confirmed no domestic parcel activity; the page asks the same service. */
+export const EVRI_UK_UNCONFIRMED = 'parcel_unconfirmed';
+const MAX_BYTES = 2_000_000;
+// Shared guest-tracking application key, distributed with the maintainer's approval.
+const APPLICATION_KEY = 'NpxtibhIgliySB4JRfjAQq2vytmiWGUQ';
+function unconfirmed() {
+    throw new IndeterminateError('Evri UK', 'Evri UK could not confirm a domestic parcel', { reason: EVRI_UK_UNCONFIRMED });
+}
+export async function readEvriUkMobile(raw, options) {
+    const number = normalizeEvriUkNumber(raw);
+    const key = options.key === undefined ? APPLICATION_KEY : options.key?.trim();
+    if (!key || !/^[\w.~+/=-]{8,512}$/.test(key))
+        throw new ChallengeError('Evri UK', 'Evri UK tracking API key is unavailable');
+    const deadline = performance.now() + options.timeoutMs;
+    const read = async (url) => {
+        const { response, bytes } = await fetchBounded(url, { signal: options.signal,
+            headers: { Accept: 'application/json', apiKey: key, 'User-Agent': userAgentOf(options.userAgent) } }, {
+            provider: 'Evri UK', maxBytes: MAX_BYTES, timeoutMs: Math.max(1, Math.floor(deadline - performance.now())),
+            fetcher: options.fetcher, allowHttpStatuses: [400, 401, 403, 404, 410],
+        });
+        if ([401, 403].includes(response.status))
+            throw new ChallengeError('Evri UK', 'Evri UK refused the tracking API key');
+        let payload;
+        try {
+            payload = JSON.parse(decodeText(bytes));
+        }
+        catch {
+            payload = undefined;
+        }
+        // The service reports a reference it rejects as JSON; a bare status is the endpoint's.
+        if (response.status !== 200 && !(isRecord(payload) && Array.isArray(payload.errors) && payload.errors.length)) {
+            if ([404, 410].includes(response.status))
+                throw new TransportError('Evri UK', 'Evri UK tracking API is unavailable', { status: response.status });
+            throw new UpstreamHttpError('Evri UK', response.status);
+        }
+        if (response.status === 200 && payload === undefined)
+            throw new SchemaError('Evri UK', 'Evri UK returned invalid tracking data');
+        return { status: response.status, payload };
+    };
+    try {
+        const reference = await read(new URL(`${EVRI_UK_MOBILE_API}/parcels/reference/${number}`));
+        if (reference.status !== 200)
+            unconfirmed();
+        const identifiers = isRecord(reference.payload) ? reference.payload.parcelIdentifiers : undefined;
+        if (!Array.isArray(identifiers) || identifiers.length > 50)
+            throw new SchemaError('Evri UK', 'Evri UK returned invalid parcel identifiers');
+        // Several parcels or an international redirect do not settle one domestic parcel.
+        const identifier = identifiers.length === 1 ? identifiers[0] : undefined;
+        if (identifiers.length !== 1 || (isRecord(identifier) && identifier.redirectUrl))
+            unconfirmed();
+        const urn = isRecord(identifier) ? identifier.urn : undefined;
+        if (typeof urn !== 'string' || !new RegExp(`^urn:parcel_id:barcode:date:\\d{1,30}:${number}:\\d{4}-\\d{2}-\\d{2}$`).test(urn)) {
+            throw new SchemaError('Evri UK', 'Evri UK did not return the requested parcel');
+        }
+        const endpoint = new URL(`${EVRI_UK_MOBILE_API}/parcels/`);
+        endpoint.searchParams.set('uniqueIds', urn);
+        const history = await read(endpoint);
+        if (history.status !== 200)
+            unconfirmed();
+        try {
+            return parseEvriUk(history.payload, number, urn);
+        }
+        catch (error) {
+            if (error instanceof IndeterminateError)
+                unconfirmed();
+            throw error;
+        }
+    }
+    catch (error) {
+        options.signal.throwIfAborted();
+        // Transport diagnostics include the key, the barcode and recipient fields.
+        // Preserve the failure contract without forwarding request or body data.
+        if (error instanceof CarrierError)
+            throw new CarrierError(error.kind, 'Evri UK', `Evri UK tracking failed (${error.kind})`, {
+                status: error.status, retryAfterMs: error.retryAfterMs, reason: error.reason,
+            });
+        throw new TransportError('Evri UK', 'Evri UK tracking API request failed');
+    }
+}

package/dist/carriers/lbc-express/mobile.js

@@ -1,7 +1,7 @@
 import { DateTime } from 'luxon';
-import { SaxesParser } from 'saxes';
 import { CarrierError, ChallengeError, IndeterminateError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
 import { clean, decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { xmlDocument } from '../../core/transport/xml.js';
 import { normalizeLbcNumber } from './parser.js';
 export const LBC_MOBILE_API = 'https://lbcapigateway.lbcapps.com/lbctrackingapi2/v2';
 const SOAP = 'http://schemas.xmlsoap.org/soap/envelope/';
@@ -10,42 +10,6 @@ const MAX_BYTES = 1_000_000;
 // Shared guest-tracking application key, distributed with the maintainer's approval.
 const APPLICATION_KEY = '4dc2cebad70043c79346dc66d5a94fa8';
 function invalidXml() { throw new SchemaError('lbc-express', 'LBC returned invalid tracking XML'); }
-function document(xml) {
-    if (new TextEncoder().encode(xml).byteLength > MAX_BYTES)
-        invalidXml();
-    const parser = new SaxesParser({ xmlns: true });
-    const stack = [];
-    let root;
-    let count = 0;
-    parser.on('error', invalidXml);
-    parser.on('doctype', invalidXml);
-    parser.on('opentag', tag => {
-        if (++count > 20_000 || stack.length > 24)
-            invalidXml();
-        const node = { name: tag.local, uri: tag.uri, text: '', children: [] };
-        if (stack.length)
-            stack.at(-1).children.push(node);
-        else if (root)
-            invalidXml();
-        else
-            root = node;
-        stack.push(node);
-    });
-    const text = (value) => { if (stack.length)
-        stack.at(-1).text += value; };
-    parser.on('text', text);
-    parser.on('cdata', text);
-    parser.on('closetag', () => { stack.pop(); });
-    try {
-        parser.write(xml).close();
-    }
-    catch {
-        invalidXml();
-    }
-    if (!root || stack.length)
-        invalidXml();
-    return root;
-}
 function children(node, name, uri = SERVICE) {
     return node.children.filter(child => child.name === name && child.uri === uri);
 }
@@ -90,7 +54,7 @@ function scanClock(day, time) {
 }
 export function parseLbcMobile(xml, raw) {
     const number = normalizeLbcNumber(raw);
-    const root = document(xml);
+    const root = xmlDocument(xml, MAX_BYTES) ?? invalidXml();
     if (root.name !== 'Envelope' || root.uri !== SOAP)
         invalidXml();
     const body = one(root, 'Body', SOAP);

package/dist/core/transport/xml.d.ts

@@ -0,0 +1,8 @@
+export interface XmlNode {
+    name: string;
+    uri: string;
+    text: string;
+    children: XmlNode[];
+}
+/** The root element, or null when `xml` is not one well-formed document within the limits. */
+export declare function xmlDocument(xml: string, maxBytes: number): XmlNode | null;

package/dist/core/transport/xml.js

@@ -0,0 +1,43 @@
+/**
+ * A bounded element tree for a provider's XML reply. Namespaces are resolved,
+ * attributes are not kept, and a document type declaration is refused.
+ */
+import { SaxesParser } from 'saxes';
+const MAX_NODES = 20_000;
+const MAX_DEPTH = 24;
+/** The root element, or null when `xml` is not one well-formed document within the limits. */
+export function xmlDocument(xml, maxBytes) {
+    if (new TextEncoder().encode(xml).byteLength > maxBytes)
+        return null;
+    const invalid = () => { throw new SyntaxError('invalid XML'); };
+    const parser = new SaxesParser({ xmlns: true });
+    const stack = [];
+    let root;
+    let count = 0;
+    parser.on('error', invalid);
+    parser.on('doctype', invalid);
+    parser.on('opentag', tag => {
+        if (++count > MAX_NODES || stack.length > MAX_DEPTH)
+            invalid();
+        const node = { name: tag.local, uri: tag.uri, text: '', children: [] };
+        if (stack.length)
+            stack.at(-1).children.push(node);
+        else if (root)
+            invalid();
+        else
+            root = node;
+        stack.push(node);
+    });
+    const text = (value) => { if (stack.length)
+        stack.at(-1).text += value; };
+    parser.on('text', text);
+    parser.on('cdata', text);
+    parser.on('closetag', () => { stack.pop(); });
+    try {
+        parser.write(xml).close();
+    }
+    catch {
+        return null;
+    }
+    return root && !stack.length ? root : null;
+}

package/dist/server/openapi.json

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

package/package.json

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