universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/dpd/adapter.js

@@ -0,0 +1,809 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { randomBytes } from 'node:crypto';
+import { load } from 'cheerio';
+import { ChallengeError, IndeterminateError, NotFoundError, SchemaError, carrierErrorKind, } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { isoTime, explicitOffsetTime, zonedTime } from '../../core/time/index.js';
+import { TrawlClient, decodeText, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { API_LABELS, PROOF_OF_DELIVERY_SCAN, apiStage, apiStatus, scanStage, wordingStatus, } from './status.js';
+// Protocol provenance:
+// - The myDPD Android application talks to a guest JSON API: a Firebase
+//   installation identifies the app, Remote Config hands out the guest Basic
+//   credential, that credential buys a client-credentials access token, and the
+//   token reads `/v10/parcels/details/<number>`. Every value below is shipped
+//   publicly in the application; none of it is an account secret.
+// - The delivery postcode is optional. With it, DPD unlocks verified scans and
+//   the delivery window; without it the lookup continues with
+//   `continueWithoutVerification=true`. A rejected postcode (HTTP 400) is
+//   retried once without verification and reported as unverified rather than
+//   failing the lookup.
+// - The consignee web page is the fallback when the guest API is inconclusive.
+//   It sits behind Cloudflare, so it is fetched through the browser service's
+//   legacy command API when one is configured and directly otherwise.
+const TRACKING_BASE = 'https://www.dpdgroup.com/ch/mydpd/my-parcels/incoming';
+const FETCH_BASE = 'https://www.dpdgroup.com/ch/mydpd/my-parcels/track';
+const API_BASE = 'https://www.dpdgroup.com/concept/webservice';
+const OAUTH_URL = `${API_BASE}/oauth/token?grant_type=client_credentials`;
+const DETAILS_BASE = `${API_BASE}/v10/parcels/details`;
+const FIREBASE_PROJECT = 'consignee-portal';
+const FIREBASE_PROJECT_NUMBER = '959401347543';
+const FIREBASE_APP_ID = '1:959401347543:android:8d1a84133332291109e392';
+// Public, app-restricted identifier shipped in the myDPD Android application.
+const FIREBASE_API_KEY = 'AIzaSyDHMkUNUyUwFrQzKJhdC_J-L7QEwNUzwrc'; // gitleaks:allow
+const ANDROID_PACKAGE = 'com.dpdgroup.chatbot.lemny.prod';
+const ANDROID_CERT = '3872ACD98DE975F69C68CAF5119A5A1B2024B873';
+const CLIENT_VERSION = '3.79.14';
+const INSTALLATIONS_URL = `https://firebaseinstallations.googleapis.com/v1/projects/${FIREBASE_PROJECT}/installations`;
+const REMOTE_CONFIG_URL = `https://firebaseremoteconfig.googleapis.com/v1/projects/${FIREBASE_PROJECT_NUMBER}/namespaces/firebase:fetch`;
+const TIMEZONE = 'Europe/Zurich';
+const DEFAULT_TIMEOUT_MS = 90_000;
+/** How long a failed guest login answers new lookups before the next attempt. */
+const TOKEN_FAILURE_MEMORY_MS = 30_000;
+/** The browser service may spend the whole request timeout plus its own transport allowance. */
+const SOLVER_ALLOWANCE_MS = 15_000;
+const MAX_BYTES = 10_000_000;
+/** Cloudflare interrupted the consignee page with an interactive challenge. */
+export class DPDChallengeError extends ChallengeError {
+    constructor(message = 'DPD returned a Cloudflare browser challenge', options) {
+        super('DPD', message, options);
+        this.name = 'DPDChallengeError';
+    }
+}
+/**
+ * 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 class DPDAPIError extends IndeterminateError {
+    constructor(message, options) {
+        super('DPD guest API', message, options);
+        this.name = 'DPDAPIError';
+    }
+}
+/** DPD positively reports that it does not know the parcel number. */
+export class DPDTrackingError extends NotFoundError {
+    constructor(options) {
+        super('DPD', 'DPD could not locate the shipment', options);
+        this.name = 'DPDTrackingError';
+    }
+}
+class DPDAPIHttpError extends DPDAPIError {
+    constructor(status) {
+        super(`DPD guest API returned HTTP ${status}`, { status });
+        this.name = 'DPDAPIHttpError';
+    }
+}
+/** The parcel-details call itself refused the lookup (HTTP 400), not a token step. */
+class DPDDetailsRefusedError extends DPDAPIHttpError {
+    constructor() {
+        super(400);
+        this.name = 'DPDDetailsRefusedError';
+    }
+}
+/**
+ * The rendered page recovers exactly what the guest API path used to hand it:
+ * an inconclusive answer, a transport failure, or a payload that did not match
+ * the request. A positive "unknown parcel" ends the lookup instead.
+ */
+const PAGE_RECOVERS = new Set(['indeterminate', 'transport', 'schema']);
+/**
+ * Local to this adapter: the guest API mixes strings and numbers in the fields
+ * we project, and its labels are not length-capped here (they are capped at the
+ * projection site instead), so `core/transport`'s string-only `clean` would
+ * change what a numeric city or code normalizes to. Anything else (objects,
+ * arrays, booleans) is empty: `String()` of an object is "[object Object]".
+ */
+function clean(value) {
+    const text = textual(value);
+    return text === undefined ? '' : String(text).trim().split(/\s+/).filter(Boolean).join(' ');
+}
+/**
+ * The value when `clean` can read it, otherwise undefined, so a `??` chain
+ * passes over an object as it does over null. An empty string still stops the
+ * chain: stored events are keyed on what that chain produced.
+ */
+function textual(value) {
+    return typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value))
+        ? value
+        : undefined;
+}
+/** What DPD writes where it has no value, e.g. `country: "UNDEFINED"` on customs scans. */
+const PLACEHOLDERS = new Set(['UNDEFINED', 'UNKNOWN', 'NULL', 'NONE', 'N/A', '-']);
+/** Provider text with DPD's placeholders read as empty. */
+function known(value) {
+    const text = clean(value);
+    return PLACEHOLDERS.has(text.toUpperCase()) ? '' : text;
+}
+/** The first candidate that carries real text. */
+function firstText(...candidates) {
+    for (const candidate of candidates) {
+        const text = known(candidate);
+        if (text)
+            return text;
+    }
+    return '';
+}
+function optionalText(value) {
+    return clean(value) || null;
+}
+/** A guest API code (`DEY`, `PARCEL_HANDED`) fit to travel as `provider_code`, or ''. */
+function scanCode(value) {
+    const code = known(value).toUpperCase().replaceAll(' ', '_');
+    return /^[A-Z0-9_]{1,40}$/.test(code) ? code : '';
+}
+export function dpdTrackingUrl(trackingNumber, language) {
+    const url = new URL(TRACKING_BASE);
+    url.searchParams.set('parcelNumber', trackingNumber);
+    if (language)
+        url.searchParams.set('lang', language);
+    return url.toString();
+}
+/** Page timestamps are Swiss wall-clock without an offset; unparsable values stay raw. */
+function eventTime(date, clock) {
+    const value = `${date} ${clock}`.trim();
+    const formats = clock
+        ? ['dd.MM.yyyy HH:mm:ss', 'dd.MM.yyyy HH:mm', 'dd.MM.yyyy']
+        : ['dd.MM.yyyy'];
+    for (const format of formats) {
+        const parsed = zonedTime(value, format, TIMEZONE);
+        if (parsed)
+            return parsed.iso;
+    }
+    return value;
+}
+function apiDescription(value) {
+    const key = clean(value).toUpperCase().replaceAll(' ', '_');
+    return API_LABELS[key] ?? key.toLocaleLowerCase('en-US')
+        .replaceAll('_', ' ')
+        .replace(/\b\w/g, (character) => character.toUpperCase());
+}
+function apiSender(payload, current) {
+    // Webshop sender only; recipient names stay out. A verified lookup sends
+    // `sender` as an object with a company, a name, an id and a postal address:
+    // only the company, then the name, is read. The `receiver` block never is.
+    const sender = isRecord(payload.sender) ? payload.sender : {};
+    const value = firstText(sender.companyName, sender.name, payload.senderName, payload.sender, current.senderName);
+    return value ? value.slice(0, 200) : null;
+}
+function apiPickupPoint(payload, current, stage) {
+    if (stage !== 'ready_for_pickup')
+        return null;
+    // ParcelShop collection points are operational locations, not private
+    // addresses. `receiverName` is the last fallback and is only read as text.
+    const value = firstText(...[current.pickupPoint, current.parcelShop, payload.pickupPoint, payload.parcelShop]
+        .map((candidate) => (isRecord(candidate) ? firstText(candidate.name, candidate.shopName) : candidate)), current.receiverName, payload.receiverName);
+    return value ? value.slice(0, 200) : null;
+}
+function apiLocation(event) {
+    const city = known(event.city);
+    // A scan's own `country` wins even when it is a placeholder: `depotCountry`
+    // names the business unit's depot on every scan, customs and paperwork scans
+    // included. It stays the last fallback for a scan that names no country at
+    // all, as it always was, so places stored from such scans keep their identity.
+    const country = known(textual(event.country) ?? textual(event.countryCode) ?? textual(event.depotCountry));
+    return city && country && city.toLocaleLowerCase('en-US') !== country.toLocaleLowerCase('en-US')
+        ? `${city}, ${country}`
+        : city || country;
+}
+/**
+ * A scan's `eventDateAndTimeZoneId` as a zone luxon reads. DPD sends "+02:00"
+ * and "Europe/Zurich"; "+0200", "UTC+2", "Z", "UTC" and "GMT" are accepted
+ * too. Anything else passes through, and an unreadable zone means Swiss time.
+ */
+function scanZone(value) {
+    const text = clean(value);
+    if (/^(?:Z|UTC|GMT)$/i.test(text))
+        return 'UTC';
+    const offset = /^(?:UTC|GMT)?([+-])(\d{1,2}):?(\d{2})?$/i.exec(text);
+    if (!offset)
+        return text;
+    const [, sign, hours, minutes = '00'] = offset;
+    return Number(hours) <= 14 && Number(minutes) < 60 ? `UTC${sign}${hours.padStart(2, '0')}:${minutes}` : '';
+}
+/** How this adapter read a zone id before `scanZone`; stored events carry its spelling. */
+function storedTime(value, zoneId) {
+    const zoneText = clean(zoneId);
+    const zone = /^[+-]\d{2}:\d{2}$/.test(zoneText) ? `UTC${zoneText}` : zoneText || TIMEZONE;
+    return isoTime(value, zone) ?? (zoneText ? isoTime(value, TIMEZONE) : null);
+}
+/**
+ * Guest API timestamps: an explicit offset wins, then the zone DPD names for
+ * that scan, then Swiss time. Unparsable values keep their raw text.
+ *
+ * The sync keys stored events on this exact string. When the instant is the
+ * one the adapter read before (with `storedZoneId`, Swiss time for
+ * `parcelEvents`), the earlier spelling is returned so no stored scan is
+ * duplicated.
+ */
+function apiEventTime(date, clock = '', zoneId = null, storedZoneId = zoneId) {
+    const dateText = clean(date);
+    const clockText = clean(clock);
+    const value = clockText ? `${dateText}T${clockText}` : dateText;
+    if (!value)
+        return '';
+    const offsetParsed = explicitOffsetTime(value);
+    if (offsetParsed)
+        return offsetParsed.iso;
+    const zone = scanZone(zoneId);
+    const parsed = (zone ? isoTime(value, zone) : null) ?? isoTime(value, TIMEZONE);
+    const stored = storedTime(value, storedZoneId);
+    return (stored && stored.timestamp === parsed?.timestamp ? stored : parsed)?.iso
+        ?? clean(`${dateText} ${clockText}`);
+}
+/** The parcel weight in kilograms; absent, zero and implausible values are dropped. */
+function apiWeight(value) {
+    const text = clean(value).replace(',', '.');
+    const weight = /^\d+(?:\.\d+)?$/.test(text) ? Number(text) : Number.NaN;
+    return Number.isFinite(weight) && weight > 0 && weight < 10_000 ? weight : null;
+}
+function expectedDelivery(payload) {
+    const rawDate = clean(payload.deliveryDate);
+    if (!rawDate)
+        return null;
+    const date = /^\d{4}-\d{2}-\d{2}/.exec(rawDate)?.[0] ?? rawDate;
+    const shortTime = (value) => /^(\d{2}:\d{2})/.exec(clean(value))?.[1] ?? '';
+    const from = shortTime(payload.deliveryTimeFrom);
+    const to = shortTime(payload.deliveryTimeTo);
+    if (from && to)
+        return `${date} ${from}–${to}`;
+    return from || to ? `${date} ${from || to}` : date;
+}
+/**
+ * Newest scan first. The guest API has listed a parcel's scans oldest first,
+ * and the summary and freshness watermark read the first event. Equal or
+ * unreadable times keep the payload's order.
+ */
+function newestFirst(events) {
+    return events
+        .map((event, index) => ({ event, index, timestamp: Date.parse(event.time ?? '') || 0 }))
+        .sort((left, right) => right.timestamp - left.timestamp || left.index - right.index)
+        .map(({ event }) => event);
+}
+export function parseDPDTrackingApi(payload, trackingNumber, postcodeVerified) {
+    if (!isRecord(payload))
+        throw new DPDAPIError('DPD guest API returned an invalid response');
+    if (clean(payload.parcelNumber ?? payload.shipmentId) !== trackingNumber) {
+        throw new SchemaError('DPD', 'DPD did not return the requested parcel');
+    }
+    const history = Array.isArray(payload.parcelHistory) ? payload.parcelHistory.filter(isRecord) : [];
+    // A verified lookup lists each movement twice: in `parcelEvents` with its
+    // wording, place and scan code but a bare Swiss wall clock, and in
+    // `parcelHistory` with the enumeration and DPD's offset for that scan. A
+    // scan takes the offset of the history entry at the same wall clock, so the
+    // repeated autumn hour keeps its instant; without one it is read in Swiss time.
+    // Only a scan alone at its wall clock with a single entry there is paired
+    // and lent that entry's stage. Otherwise nothing says which entry is whose:
+    // the scans share an offset only when every entry there names the same zone.
+    const parcelEvents = Array.isArray(payload.parcelEvents) ? payload.parcelEvents.filter(isRecord) : [];
+    const scanWallClock = (raw) => `${clean(raw.date)}T${clean(raw.time)}`;
+    const entriesAt = new Map();
+    for (const raw of history) {
+        const wallClock = clean(raw.eventDateAndTime).slice(0, 19);
+        if (wallClock)
+            entriesAt.set(wallClock, [...(entriesAt.get(wallClock) ?? []), raw]);
+    }
+    const scansAt = new Map();
+    for (const raw of parcelEvents) {
+        const wallClock = scanWallClock(raw);
+        scansAt.set(wallClock, (scansAt.get(wallClock) ?? 0) + 1);
+    }
+    const scans = [];
+    const seen = new Set();
+    const append = (event) => {
+        const key = JSON.stringify([event.time ?? '', event.location ?? '', event.description ?? '']);
+        if (!seen.has(key)) {
+            seen.add(key);
+            scans.push(event);
+        }
+    };
+    // Only the fields below leave a scan. `podUrl` embeds the parcel number, and
+    // `pudoId`, `buShortName` and `depotCountry` are DPD's own routing data.
+    for (const raw of parcelEvents) {
+        const code = scanCode(raw.eventType);
+        const wallClock = scanWallClock(raw);
+        const entries = entriesAt.get(wallClock) ?? [];
+        const twin = entries.length === 1 && scansAt.get(wallClock) === 1 ? entries[0] : undefined;
+        const zoneId = new Set(entries.map((entry) => clean(entry.eventDateAndTimeZoneId))).size === 1
+            ? entries[0]?.eventDateAndTimeZoneId
+            : null;
+        const stage = scanStage(code) ?? apiStage(code) ?? (twin ? apiStage(twin.description) : null);
+        append({
+            time: apiEventTime(raw.date, raw.time, zoneId, null),
+            location: apiLocation(raw),
+            description: clean(textual(raw.translation) ?? textual(raw.eventTypeText) ?? apiDescription(raw.eventType))
+                || 'Tracking update',
+            ...(stage ? { stage } : {}),
+            ...(code ? { provider_code: code } : {}),
+        });
+    }
+    if (scans.length === 0) {
+        for (const raw of history) {
+            const code = scanCode(raw.description);
+            const stage = apiStage(code);
+            append({
+                time: apiEventTime(raw.eventDateAndTime, '', raw.eventDateAndTimeZoneId),
+                location: apiLocation(raw),
+                description: apiDescription(raw.description),
+                ...(stage ? { stage } : {}),
+                ...(code ? { provider_code: code } : {}),
+            });
+        }
+    }
+    const current = isRecord(payload.status) ? payload.status : {};
+    const currentDescription = current.description;
+    const stage = apiStage(currentDescription);
+    // The proof-of-delivery scan follows the delivery scan by minutes, with no
+    // place. Next to it the paperwork adds nothing, and as the newest event its
+    // wording, which no rule maps, would become the summary and the apps'
+    // current stage. Alone it proves the delivery only when the enumeration
+    // says delivered; otherwise (a return, say) it would hide the real state.
+    const deliveryScanned = scans.some((event) => (event.stage === 'delivered' && event.provider_code !== PROOF_OF_DELIVERY_SCAN));
+    const events = newestFirst(scans.flatMap((event) => {
+        if (event.provider_code !== PROOF_OF_DELIVERY_SCAN)
+            return [event];
+        return deliveryScanned || stage !== 'delivered' ? [] : [{ ...event, stage: 'delivered' }];
+    }));
+    const statusText = events[0]?.description || apiDescription(currentDescription)
+        || 'Tracking information received';
+    const status = apiStatus(currentDescription, statusText, events.length > 0);
+    const sender = apiSender(payload, current);
+    const pickupPoint = apiPickupPoint(payload, current, stage);
+    const weight = apiWeight(payload.weight);
+    const deliveredAt = status === 'delivered'
+        ? events.find((event) => event.stage === 'delivered')?.time
+        : undefined;
+    // Never projected: `receiver` (name, contact, address, geoPosition), the
+    // sender's id and address, `customerReference1/2`, `gttsZipCode`, `podUrl`
+    // and `product`, which holds the recipient's delivery preference.
+    const result = {
+        status,
+        ...(stage ? { current_stage: stage } : {}),
+        last_status_text: statusText,
+        last_update: events[0]?.time || apiEventTime(current.eventDateAndTime, '', current.eventDateAndTimeZoneId) || null,
+        expected_delivery: status === 'delivered' || status === 'exception' ? null : expectedDelivery(payload),
+        events,
+        source: 'mydpd_guest_api',
+        delivery_date: optionalText(payload.deliveryDate),
+        delivery_time_from: optionalText(payload.deliveryTimeFrom),
+        delivery_time_to: optionalText(payload.deliveryTimeTo),
+        is_predictive_date: Boolean(payload.isPredictiveDate),
+        ...(sender ? { sender_name: sender } : {}),
+        ...(pickupPoint ? { pickup_point: pickupPoint } : {}),
+        ...(weight !== null ? { weight_kg: weight } : {}),
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+    };
+    if (postcodeVerified !== undefined)
+        result.dpd_postcode_verified = postcodeVerified;
+    return result;
+}
+export function parseDPDTrackingHtml(html, trackingNumber) {
+    if (/Just a moment|cf-mitigated|Enable JavaScript and cookies/i.test(html)) {
+        throw new DPDChallengeError();
+    }
+    const $ = load(html);
+    $('script, style').remove();
+    const visible = clean($('body').text());
+    if (!visible.includes(trackingNumber)) {
+        throw new SchemaError('DPD', 'DPD did not return the requested parcel');
+    }
+    if (/no parcel|not found|nicht gefunden|aucun colis/i.test(visible)) {
+        return {
+            status: 'unknown',
+            last_status_text: 'No parcel found',
+            last_update: null,
+            expected_delivery: null,
+            events: [],
+        };
+    }
+    const events = [];
+    $('li.content-item-track').each((_, element) => {
+        const row = $(element);
+        const description = clean(row.find('.entry-body').text());
+        if (!description)
+            return;
+        events.push({
+            time: eventTime(clean(row.find('.entry-date').text()), clean(row.find('.entry-time').text())),
+            location: clean(row.find('.place-track').text()),
+            description,
+        });
+    });
+    if (events.length === 0) {
+        const summary = [];
+        $('.parcelStatus .row').each((_, element) => {
+            const row = $(element);
+            const date = /\d{2}\.\d{2}\.\d{4}/.exec(clean(row.text()))?.[0] ?? '';
+            const description = clean(row.find('.col-xs-7').text())
+                || clean(row.text()).replace(date, '').trim();
+            if (date && description)
+                summary.push({ date, description });
+        });
+        const offsets = new Map();
+        for (const item of summary) {
+            const offset = offsets.get(item.date) ?? 0;
+            offsets.set(item.date, offset + 1);
+            events.push({
+                time: eventTime(item.date, `00:${String(Math.floor(offset / 60)).padStart(2, '0')}:${String(offset % 60).padStart(2, '0')}`),
+                location: '',
+                description: item.description,
+            });
+        }
+        events.reverse();
+    }
+    const labels = $('.gray-out').map((_, element) => clean($(element).text())).get().filter(Boolean);
+    const statusText = events[0]?.description ?? labels.at(-1) ?? 'Tracking information received';
+    return {
+        status: wordingStatus(statusText, events.length > 0),
+        last_status_text: statusText,
+        last_update: events[0]?.time || null,
+        expected_delivery: null,
+        events,
+    };
+}
+function durationSeconds(value, fallback) {
+    const match = /^(\d+)s?$/.exec(String(value ?? ''));
+    return match ? Number(match[1]) : fallback;
+}
+export class DPDTracker {
+    timeoutMs;
+    budgetMs;
+    flaresolverrUrl;
+    firebaseApiKey;
+    fetcher;
+    trawl;
+    recorder;
+    #accessToken = '';
+    #accessTokenExpiresAt = 0;
+    #basicToken = '';
+    #installationFid = '';
+    #installationToken = '';
+    #installationExpiresAt = 0;
+    #tokenRefresh = null;
+    #tokenFailure = null;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.budgetMs = options.budgetMs ?? this.timeoutMs * 2 + SOLVER_ALLOWANCE_MS;
+        this.flaresolverrUrl = (options.flaresolverrUrl ?? '').trim();
+        this.firebaseApiKey = (options.firebaseApiKey ?? FIREBASE_API_KEY).trim();
+        this.fetcher = options.fetcher;
+        this.trawl = options.trawl;
+        this.recorder = options.recorder;
+    }
+    /** The browser service, resolved late so a malformed URL fails the page step, not construction. */
+    browserService() {
+        if (this.trawl !== undefined)
+            return this.trawl;
+        return this.flaresolverrUrl ? new TrawlClient(this.flaresolverrUrl, this.fetcher) : null;
+    }
+    async fetch(trackingNumber, postcode = '') {
+        if (!/^\d{14}$/.test(trackingNumber)) {
+            throw new TypeError('DPD tracking numbers must contain 14 digits');
+        }
+        const resolvedPostcode = postcode.trim();
+        if (resolvedPostcode && !/^\d{4}$/.test(resolvedPostcode)) {
+            throw new TypeError('DPD postcode must contain exactly 4 digits');
+        }
+        const result = await runSteps({
+            carrier: 'dpd', budgetMs: this.budgetMs, recorder: this.recorder,
+        }, [
+            { id: 'direct', run: () => this.apiFetch(trackingNumber, resolvedPostcode) },
+            {
+                id: 'page',
+                recovers: (error) => {
+                    const kind = carrierErrorKind(error);
+                    return kind !== null && PAGE_RECOVERS.has(kind);
+                },
+                run: ({ previousError }) => this.pageFetch(trackingNumber, previousError !== undefined),
+            },
+        ]);
+        result.tracking_url = dpdTrackingUrl(trackingNumber);
+        return result;
+    }
+    /**
+     * 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.
+     */
+    async recognizes(trackingNumber) {
+        if (!/^\d{14}$/.test(trackingNumber))
+            return false;
+        try {
+            const payload = await this.detailsWithFreshToken(trackingNumber);
+            return clean(payload.parcelNumber ?? payload.shipmentId) === trackingNumber;
+        }
+        catch (error) {
+            if (error instanceof DPDTrackingError)
+                return false;
+            if (error instanceof DPDDetailsRefusedError)
+                return false;
+            throw error;
+        }
+    }
+    async apiFetch(trackingNumber, postcode) {
+        let postcodeVerified;
+        let payload;
+        try {
+            payload = await this.detailsWithFreshToken(trackingNumber, postcode || undefined);
+            if (postcode)
+                postcodeVerified = true;
+        }
+        catch (error) {
+            if (!(error instanceof DPDAPIHttpError) || !postcode || error.status !== 400)
+                throw error;
+            payload = await this.detailsWithFreshToken(trackingNumber);
+            postcodeVerified = false;
+        }
+        return parseDPDTrackingApi(payload, trackingNumber, postcodeVerified);
+    }
+    async detailsWithFreshToken(trackingNumber, postcode) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const token = await this.accessToken();
+            try {
+                return await this.parcelDetails(trackingNumber, postcode, token);
+            }
+            catch (error) {
+                if (!(error instanceof DPDAPIHttpError) || error.status !== 401 || attempt > 0)
+                    throw error;
+                this.#accessToken = '';
+                this.#accessTokenExpiresAt = 0;
+            }
+        }
+        throw new DPDAPIError('DPD guest API authentication failed');
+    }
+    async parcelDetails(trackingNumber, postcode, token) {
+        const url = new URL(`${DETAILS_BASE}/${encodeURIComponent(trackingNumber)}`);
+        url.searchParams.set('parcelType', 'INCOMING');
+        url.searchParams.set('businessUnit', 'DPD-CH');
+        url.searchParams.set('lang', 'en');
+        url.searchParams.set('continueWithoutVerification', postcode ? 'false' : 'true');
+        if (postcode)
+            url.searchParams.set('dataForVerification', postcode);
+        try {
+            return await this.requestJson(url, '', {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+                'Content-Type': 'application/json',
+                'User-Agent': `myDPD/${CLIENT_VERSION} (Android)`,
+            }, true);
+        }
+        catch (error) {
+            if (error instanceof DPDAPIHttpError && error.status === 404) {
+                throw new DPDTrackingError();
+            }
+            if (error instanceof DPDAPIHttpError && error.status === 400)
+                throw new DPDDetailsRefusedError();
+            throw error;
+        }
+    }
+    async accessToken() {
+        if (this.#accessToken && Date.now() < this.#accessTokenExpiresAt)
+            return this.#accessToken;
+        // Concurrent lookups share one refresh and its outcome. A failed guest
+        // login is answered from memory for a short while, so a queue of lookups
+        // during an outage does not replay the whole token chain one by one.
+        if (this.#tokenRefresh)
+            return await this.#tokenRefresh;
+        if (this.#tokenFailure && Date.now() < this.#tokenFailure.until)
+            throw this.#tokenFailure.error;
+        this.#tokenRefresh = this.refreshAccessToken().then((token) => {
+            this.#tokenFailure = null;
+            return token;
+        }, (error) => {
+            this.#tokenFailure = { error, until: Date.now() + TOKEN_FAILURE_MEMORY_MS };
+            throw error;
+        }).finally(() => { this.#tokenRefresh = null; });
+        return await this.#tokenRefresh;
+    }
+    async refreshAccessToken() {
+        let payload = null;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const basicToken = this.#basicToken || await this.fetchBasicToken();
+            try {
+                payload = await this.requestJson(OAUTH_URL, '', {
+                    Authorization: `Basic ${basicToken}`,
+                    Accept: 'application/json',
+                    'Content-Type': 'application/json',
+                    'User-Agent': `myDPD/${CLIENT_VERSION} (Android)`,
+                });
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof DPDAPIHttpError)
+                    || ![400, 401].includes(error.status)
+                    || attempt > 0)
+                    throw error;
+                this.#basicToken = '';
+            }
+        }
+        const token = clean(payload?.access_token);
+        if (!token)
+            throw new DPDAPIError('DPD guest API did not issue an access token');
+        this.#accessToken = token;
+        this.#accessTokenExpiresAt = Date.now()
+            + Math.max(1, durationSeconds(payload?.expires_in, 3_600) - 60) * 1_000;
+        return token;
+    }
+    async fetchBasicToken() {
+        if (!this.firebaseApiKey)
+            throw new DPDAPIError('DPD Firebase client configuration is missing');
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const [fid, installationToken] = await this.firebaseInstallation();
+            try {
+                const payload = await this.requestJson(REMOTE_CONFIG_URL, {
+                    appId: FIREBASE_APP_ID,
+                    appInstanceId: fid,
+                    appInstanceIdToken: installationToken,
+                    languageCode: 'en-US',
+                    countryCode: 'CH',
+                    platformVersion: '36',
+                    appVersion: CLIENT_VERSION,
+                    packageName: ANDROID_PACKAGE,
+                    sdkVersion: '22.1.2',
+                    analyticsUserProperties: {},
+                }, this.firebaseHeaders({ 'X-Goog-Firebase-Installations-Auth': installationToken }));
+                const entries = isRecord(payload.entries) ? payload.entries : {};
+                const token = clean(entries.basic_dpd_token);
+                if (!token)
+                    throw new DPDAPIError('myDPD Remote Config omitted its guest credential');
+                this.#basicToken = token;
+                return token;
+            }
+            catch (error) {
+                if (!(error instanceof DPDAPIHttpError)
+                    || ![401, 403].includes(error.status)
+                    || attempt > 0)
+                    throw error;
+                this.#installationFid = '';
+                this.#installationToken = '';
+                this.#installationExpiresAt = 0;
+            }
+        }
+        throw new DPDAPIError('myDPD Remote Config authentication failed');
+    }
+    async firebaseInstallation() {
+        if (this.#installationFid
+            && this.#installationToken
+            && Date.now() < this.#installationExpiresAt) {
+            return [this.#installationFid, this.#installationToken];
+        }
+        const bytes = randomBytes(17);
+        bytes[0] = 0x70 | (bytes[0] & 0x0f);
+        const fid = bytes.toString('base64url').slice(0, 22);
+        const payload = await this.requestJson(INSTALLATIONS_URL, {
+            fid,
+            appId: FIREBASE_APP_ID,
+            authVersion: 'FIS_v2',
+            sdkVersion: 'a:18.0.0',
+        }, this.firebaseHeaders());
+        const auth = isRecord(payload.authToken) ? payload.authToken : {};
+        const token = clean(auth.token);
+        if (!token)
+            throw new DPDAPIError('Firebase did not issue a myDPD installation token');
+        this.#installationFid = clean(payload.fid) || fid;
+        this.#installationToken = token;
+        this.#installationExpiresAt = Date.now()
+            + Math.max(1, durationSeconds(auth.expiresIn, 604_800) - 300) * 1_000;
+        return [this.#installationFid, token];
+    }
+    firebaseHeaders(extra = {}) {
+        return {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'X-Goog-Api-Key': this.firebaseApiKey,
+            'X-Android-Package': ANDROID_PACKAGE,
+            'X-Android-Cert': ANDROID_CERT,
+            ...extra,
+        };
+    }
+    async requestJson(url, data, headers, retryRead = false) {
+        const deadline = performance.now() + this.timeoutMs;
+        let result;
+        try {
+            for (let attempt = 0;; attempt++) {
+                result = await fetchBounded(url, {
+                    method: 'POST',
+                    headers,
+                    body: typeof data === 'string' ? data : JSON.stringify(data),
+                }, {
+                    provider: 'DPD guest API',
+                    timeoutMs: Math.max(1, Math.floor(deadline - performance.now())),
+                    maxBytes: MAX_BYTES,
+                    allowHttpError: true,
+                    fetcher: this.fetcher,
+                });
+                // Only the read-only parcel-details POST is replayed; auth requests are not.
+                const pause = 1_000 + Math.floor(Math.random() * 2_000);
+                const retryAfter = result.response.headers.get('retry-after');
+                if (!retryRead || attempt > 0 || ![502, 503, 504].includes(result.response.status)
+                    || retryAfter !== null || deadline - performance.now() < pause + 1_000)
+                    break;
+                await delay(pause);
+            }
+        }
+        catch (error) {
+            throw new DPDAPIError('DPD guest API is unreachable', { cause: error });
+        }
+        if (!result.response.ok)
+            throw new DPDAPIHttpError(result.response.status);
+        let payload;
+        try {
+            payload = parseJsonBytes(result.bytes, 'DPD guest API');
+        }
+        catch (error) {
+            throw new DPDAPIError('DPD guest API returned invalid JSON', { cause: error });
+        }
+        if (!isRecord(payload))
+            throw new DPDAPIError('DPD guest API returned an invalid response');
+        return payload;
+    }
+    async pageFetch(trackingNumber, apiFailed) {
+        const url = new URL(FETCH_BASE);
+        url.searchParams.set('lang', 'en');
+        url.searchParams.set('parcelNumber', trackingNumber);
+        const trawl = this.browserService();
+        let html;
+        if (trawl) {
+            html = await trawl.solve(url.toString(), {
+                provider: 'The browser challenge solver',
+                timeoutMs: this.timeoutMs,
+                maxBytes: MAX_BYTES,
+                fetcher: this.fetcher,
+            });
+        }
+        else {
+            try {
+                html = await this.directGet(url);
+            }
+            catch (error) {
+                if (!(error instanceof DPDChallengeError))
+                    throw error;
+                const prefix = apiFailed ? 'DPD guest API is unavailable and ' : 'DPD ';
+                throw new DPDChallengeError(`${prefix}the web fallback requires a browser challenge solver; configure FLARESOLVERR_URL`, { cause: error });
+            }
+        }
+        return parseDPDTrackingHtml(html, trackingNumber);
+    }
+    async directGet(url) {
+        const result = await fetchBounded(url, {
+            headers: {
+                Accept: 'text/html,application/xhtml+xml',
+                'Accept-Language': 'en-CH,en;q=0.9',
+                'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/140 Safari/537.36',
+            },
+        }, {
+            provider: 'DPD',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_BYTES,
+            redirect: 'follow',
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        const html = decodeText(result.bytes);
+        if (result.response.status === 403
+            && (result.response.headers.get('cf-mitigated') === 'challenge'
+                || /Just a moment|Enable JavaScript and cookies/i.test(html))) {
+            throw new DPDChallengeError();
+        }
+        if (!result.response.ok)
+            throw new IndeterminateError('DPD', `DPD returned HTTP ${result.response.status}`);
+        return html;
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new DPDTracker({
+        fetcher: environment.fetcher,
+        trawl: environment.trawl,
+        recorder: environment.recorder,
+    });
+    return {
+        id: 'dpd',
+        // The guest JSON protocol first; the Cloudflare-protected consignee page,
+        // solved by the browser service when one is configured, second.
+        steps: ['direct', 'page'],
+        track: (input) => tracker.fetch(input.number, input.postcode ?? ''),
+        recognize: async (number) => ({ known: await tracker.recognizes(number) }),
+    };
+};