universal-parcel-scraper 0.34.1-main.381 → 0.35.0-main.384

package/dist/carriers/mondial-relay/adapter.d.ts

@@ -2,22 +2,31 @@ import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.j
 import type { CarrierResult } from '../../core/result/index.js';
 import { type StepRecorder } from '../../core/telemetry/index.js';
 import { TrawlClient } from '../../core/transport/index.js';
+import { MondialRelayAppClient } from './app.js';
 interface MondialRelayCredential {
     shipment: string;
     postcode: string;
     canonicalShipment?: string;
+    /** Read from a checksummed label barcode, which needs no postcode. */
+    barcode?: true;
 }
 export declare function normalizeMondialRelayCredential(rawShipment: string, rawPostcode?: string): MondialRelayCredential;
 export declare function mondialRelayTrackingUrl(rawShipment: string, rawPostcode?: string): string;
 export declare function parseMondialRelayTrackingResponse(payload: unknown, rawShipment: string, rawPostcode?: string): CarrierResult;
 export interface MondialRelayTrackerOptions {
     timeoutMs?: number;
+    /** How long the app step may take before the website is tried. */
     directTimeoutMs?: number;
     /** Legacy configuration seam; `trawl` is preferred. */
     trawlUrl?: string;
     /** The browser service, or null when none is configured. */
     trawl?: TrawlClient | null;
+    /** An InPost account's refresh token for the app step; without one the website answers alone. */
+    appRefreshToken?: string;
+    /** Test seam for the app step; built from `appRefreshToken` when absent. */
+    app?: MondialRelayAppClient | null;
     fetcher?: typeof fetch;
+    userAgent?: string;
     recorder?: StepRecorder;
 }
 export declare class MondialRelayTracker {

package/dist/carriers/mondial-relay/adapter.js

@@ -7,6 +7,7 @@ import { NOOP_RECORDER } from '../../core/telemetry/index.js';
 import { isoTime, zonedTime } from '../../core/time/index.js';
 import { cleanScalar, TRAWL_TRANSPORT_ALLOWANCE_MS, trawlBody, TrawlClient } from '../../core/transport/index.js';
 import { isRecord } from '../../core/types.js';
+import { MondialRelayAppClient } from './app.js';
 import { classifyStatus, milestoneNumberStatus } from './status.js';
 // Protocol provenance (inspected 2026-08-30):
 // https://www.mondialrelay.fr/versioned-assets/2nMAiuVI9Rv9J3kZacblPYCfCABwzS-qZ3m7eFBQn4A/Scripts/vue/tracking/js/app.js
@@ -20,7 +21,8 @@ const TRACKING_API = 'https://www.mondialrelay.fr/api/tracking';
 const MAX_DIRECT_BYTES = 2_000_000;
 const MAX_TRAWL_BYTES = 10_000_000;
 const DEFAULT_TIMEOUT_MS = 90_000;
-const DEFAULT_DIRECT_TIMEOUT_MS = 20_000;
+/** The app answers in about a second; past this the website gets the rest of the budget. */
+const DEFAULT_DIRECT_TIMEOUT_MS = 10_000;
 const ZONE = 'Europe/Paris';
 const CREDENTIAL_MESSAGE = 'Mondial Relay tracking requires an 8-, 10-, or 12-digit shipment number followed by '
     + 'the 5-digit recipient postcode';
@@ -42,7 +44,7 @@ export function normalizeMondialRelayCredential(rawShipment, rawPostcode = '') {
             throw new InvalidInputError('Mondial Relay', 'Invalid Mondial Relay barcode or postcode');
         }
         // The public alias carries brand/shipment/parcel sequence, not a postcode.
-        return { shipment: shipment.slice(0, 12), postcode, canonicalShipment: shipment.slice(2, 10) };
+        return { shipment: shipment.slice(0, 12), postcode, canonicalShipment: shipment.slice(2, 10), barcode: true };
     }
     if (!postcode && /^(?:\d{13}|\d{15}|\d{17})$/.test(shipment)) {
         postcode = shipment.slice(-5);
@@ -264,6 +266,7 @@ export class MondialRelayTracker {
     directTimeoutMs;
     trawlUrl;
     #trawl;
+    #app;
     #fetcher;
     #recorder;
     #serialize = singleFlight();
@@ -272,6 +275,9 @@ export class MondialRelayTracker {
         this.directTimeoutMs = Math.max(1_000, Math.min(this.timeoutMs, options.directTimeoutMs ?? DEFAULT_DIRECT_TIMEOUT_MS));
         this.trawlUrl = (options.trawlUrl ?? '').trim();
         this.#trawl = options.trawl;
+        this.#app = options.app !== undefined ? options.app : options.appRefreshToken?.trim()
+            ? new MondialRelayAppClient({ refreshToken: options.appRefreshToken, fetcher: options.fetcher, userAgent: options.userAgent })
+            : null;
         this.#fetcher = options.fetcher;
         this.#recorder = options.recorder ?? NOOP_RECORDER;
         if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
@@ -286,16 +292,16 @@ export class MondialRelayTracker {
     }
     async fetch(rawShipment, rawPostcode = '', context = {}) {
         // One lookup at a time: the page token and the API call have to stay on the
-        // same solved browser identity.
+        // same solved browser identity, and the app's access token is renewed once.
         return takeTurn(this.#serialize, 'Mondial Relay', context, (left) => this.#lookup(normalizeMondialRelayCredential(rawShipment, rawPostcode), left));
     }
     async #lookup(credential, context) {
-        // Cloudflare blocks every non-browser client with an HTTP 403 WAF block
-        // (verified from multiple networks, 2026-09-10), so a direct attempt only
-        // burns time and reports a fallback on each sync. There is one step, and
-        // it is the browser.
+        // Cloudflare blocks every non-browser client of the website with an HTTP
+        // 403 WAF block (verified from multiple networks, 2026-09-10). The app's
+        // backend answers plain HTTP, but only for a signed-in account.
+        const app = this.#app;
         const trawl = this.#browserService();
-        if (!trawl) {
+        if (!app && !trawl) {
             throw new ChallengeError('Mondial Relay', 'Mondial Relay challenged direct tracking; configure FLARESOLVERR_URL for browser fallback');
         }
         return runSteps({
@@ -304,8 +310,21 @@ export class MondialRelayTracker {
             carrier: 'mondial-relay', budgetMs: context.budgetMs ?? this.timeoutMs + TRAWL_TRANSPORT_ALLOWANCE_MS, signal: context.signal,
             recorder: this.#recorder,
         }, [
+            {
+                id: 'app',
+                enabled: app !== null,
+                run: async ({ remainingMs, signal }) => {
+                    // The app filters on the recipient postcode only; a label barcode is its own proof.
+                    const query = { shipment: credential.shipment, postcode: credential.barcode ? '' : credential.postcode };
+                    const result = await app.track(query, { signal, timeoutMs: Math.min(remainingMs, this.directTimeoutMs) });
+                    return this.#link(result, credential, 'mobile-app-response');
+                },
+            },
             {
                 id: 'trawl',
+                enabled: trawl !== null,
+                // The website is a separate service: no failure of the app settles the lookup.
+                recovers: () => true,
                 run: ({ remainingMs, signal }) => this.#trawlResult(trawl, credential, performance.now() + remainingMs, signal),
             },
         ]);
@@ -338,7 +357,9 @@ export class MondialRelayTracker {
         });
     }
     #finish(payload, credential, trackingSource) {
-        const result = parseTrackingResponse(payload, credential);
+        return this.#link(parseTrackingResponse(payload, credential), credential, trackingSource);
+    }
+    #link(result, credential, trackingSource) {
         const url = new URL(TRACKING_PAGE);
         url.searchParams.set('numeroExpedition', credential.shipment);
         result.tracking_url = url.toString();
@@ -349,13 +370,15 @@ export class MondialRelayTracker {
 export const adapter = (environment) => {
     const tracker = new MondialRelayTracker({
         fetcher: environment.fetcher,
+        userAgent: environment.userAgent,
         trawl: environment.trawl,
+        appRefreshToken: environment.env.MONDIAL_RELAY_REFRESH_TOKEN,
         recorder: environment.recorder,
     });
     return {
         id: 'mondial-relay', recordsSteps: true,
-        // Cloudflare refuses every non-browser client, so there is no direct tier.
-        steps: ['trawl'],
+        // Cloudflare refuses every non-browser client of the website; the app step needs an account.
+        steps: ['app', 'trawl'],
         track: (input, context) => tracker.fetch(input.number, input.postcode ?? '', context),
     };
 };

package/dist/carriers/mondial-relay/app.d.ts

@@ -0,0 +1,42 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const MONDIAL_RELAY_APP_API = "https://mobile-app-bff.mondialrelay.app/api/";
+/**
+ * The backend's bot screen refuses Node's built-in fetch, which offers
+ * HTTP/2, and answers the same request over plain HTTP/1.1.
+ */
+export declare const http1Fetch: typeof fetch;
+/** A normalized credential: 8, 10 or 12 digits, or a barcode's 12-digit alias, and a postcode. */
+export interface MondialRelayAppQuery {
+    shipment: string;
+    postcode: string;
+}
+/**
+ * The app's parcel detail: a headline, milestones and their dated events. It
+ * carries no delivery estimate, and its relay, barcode and contact fields are
+ * never read.
+ */
+export declare function parseMondialRelayApp(payload: unknown, uid: string): CarrierResult;
+/**
+ * The consumer app's backend, signed in as one InPost account. Searching
+ * needs no link between that account and the parcel. Requests carry the
+ * app's shared signature; the account's refresh token renews a two-hour
+ * access token, kept per client.
+ */
+export declare class MondialRelayAppClient {
+    #private;
+    constructor(options: {
+        refreshToken: string;
+        fetcher?: typeof fetch;
+        userAgent?: string;
+        now?: () => number;
+    });
+    /**
+     * One parcel, found by its shipment and the recipient postcode, or by a
+     * barcode's brand and shipment alone. A search that does not single out the
+     * parcel is inconclusive: the website also accepts the sender's postcode.
+     */
+    track(query: MondialRelayAppQuery, options: {
+        signal: AbortSignal;
+        timeoutMs: number;
+    }): Promise<CarrierResult>;
+}

package/dist/carriers/mondial-relay/app.js

@@ -0,0 +1,259 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { request } from 'node:https';
+import { Readable } from 'node:stream';
+import { DateTime } from 'luxon';
+import { CarrierError, ChallengeError, IndeterminateError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { EXPLICIT_OFFSET_PATTERN } from '../../core/time/index.js';
+import { cleanScalar, decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyStatus, milestoneNumberStatus } from './status.js';
+export const MONDIAL_RELAY_APP_API = 'https://mobile-app-bff.mondialrelay.app/api/';
+const TOKEN_URL = 'https://account.inpost-group.com/oauth2/token';
+const CLIENT_ID = 'mondialrelay-mobile';
+// Shared request-signing secret of the public app, distributed with the maintainer's approval.
+const SIGNING_SECRET = 'VCzt4PzS8ynJE2yy7zNBiQbTE3pkncqEyvrUsCDbXupGn8yqRrPDov2FYiAVfuUx';
+const MAX_BYTES = 2_000_000;
+/** An access token this close to its stated expiry is renewed first. */
+const EXPIRY_MARGIN_MS = 60_000;
+const ZONE = 'Europe/Paris';
+/**
+ * The backend's bot screen refuses Node's built-in fetch, which offers
+ * HTTP/2, and answers the same request over plain HTTP/1.1.
+ */
+export const http1Fetch = (input, init = {}) => new Promise((resolve, reject) => {
+    const url = input instanceof Request ? input.url : String(input);
+    const sent = init.body ?? undefined;
+    if (sent !== undefined && typeof sent !== 'string' && !(sent instanceof URLSearchParams))
+        throw new TypeError('Only text bodies are sent');
+    const body = sent?.toString();
+    const headers = Object.fromEntries(new Headers(init.headers));
+    if (body !== undefined)
+        headers['content-length'] = String(Buffer.byteLength(body));
+    const outgoing = request(url, { method: init.method ?? 'GET', headers, signal: init.signal ?? undefined }, (incoming) => {
+        const status = incoming.statusCode ?? 0;
+        const replied = new Headers();
+        for (let index = 0; index + 1 < incoming.rawHeaders.length; index += 2)
+            replied.append(incoming.rawHeaders[index], incoming.rawHeaders[index + 1]);
+        try {
+            const stream = [204, 205, 304].includes(status) ? null : Readable.toWeb(incoming);
+            resolve(new Response(stream, { status, statusText: incoming.statusMessage, headers: replied }));
+        }
+        catch (error) {
+            incoming.destroy();
+            reject(error);
+        }
+    });
+    outgoing.on('error', reject);
+    outgoing.end(body);
+});
+function invalid(message = 'Mondial Relay app returned invalid tracking data') {
+    throw new SchemaError('Mondial Relay', message);
+}
+function json(bytes) {
+    try {
+        return JSON.parse(decodeText(bytes));
+    }
+    catch {
+        return invalid();
+    }
+}
+/** The app sends UTC instants; they are shown on Paris clocks, as the website does. */
+function eventTime(value) {
+    const raw = cleanScalar(value, 64);
+    if (!EXPLICIT_OFFSET_PATTERN.test(raw))
+        return null;
+    const parsed = DateTime.fromISO(raw, { setZone: true }).setZone(ZONE);
+    const iso = parsed.isValid ? parsed.toISO({ suppressMilliseconds: true }) : null;
+    return iso ? { iso, timestamp: parsed.toMillis() } : null;
+}
+/** The highest milestone with a date: its wording, else its position on the app's rail. */
+function milestoneStatus(steps) {
+    const reached = steps
+        .filter((step) => eventTime(step.date) && Number.isFinite(Number(step.number)))
+        .sort((left, right) => Number(right.number) - Number(left.number))[0];
+    if (!reached)
+        return null;
+    const worded = classifyStatus(cleanScalar(reached.status, 200));
+    return worded.status !== 'unknown' ? worded : milestoneNumberStatus(Number(reached.number));
+}
+/**
+ * The app's parcel detail: a headline, milestones and their dated events. It
+ * carries no delivery estimate, and its relay, barcode and contact fields are
+ * never read.
+ */
+export function parseMondialRelayApp(payload, uid) {
+    if (!Array.isArray(payload))
+        invalid();
+    const parcel = payload.find((entry) => isRecord(entry) && isRecord(entry.expedition)
+        && cleanScalar(entry.expedition.shipmentUid, 16) === uid);
+    if (!parcel)
+        invalid('Mondial Relay returned a different shipment');
+    const expedition = parcel.expedition;
+    if (!isRecord(parcel.detail) || !Array.isArray(parcel.detail.steps))
+        invalid();
+    const steps = parcel.detail.steps.filter(isRecord);
+    const parsed = [];
+    const seen = new Set();
+    for (const step of steps) {
+        for (const raw of Array.isArray(step.events) ? step.events : []) {
+            if (!isRecord(raw))
+                continue;
+            const time = eventTime(raw.date);
+            const description = cleanScalar(raw.label, 500);
+            if (!time || !description)
+                continue;
+            const identity = JSON.stringify([time.iso, description]);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            const classified = classifyStatus(description);
+            parsed.push({ event: { time: time.iso, location: '', description, stage: classified.stage }, classified, timestamp: time.timestamp });
+        }
+    }
+    parsed.sort((left, right) => right.timestamp - left.timestamp);
+    const events = parsed.slice(0, 100).map(({ event }) => event);
+    const hint = cleanScalar(expedition.stepHint, 200);
+    const hinted = classifyStatus(hint);
+    const current = hinted.status !== 'unknown'
+        ? hinted
+        : parsed.find(({ classified }) => classified.status !== 'unknown')?.classified ?? milestoneStatus(steps);
+    if (!events.length && !current)
+        throw new IndeterminateError('Mondial Relay', 'Mondial Relay app returned no shipment activity');
+    return {
+        status: current?.status ?? 'unknown',
+        ...(current ? { current_stage: current.stage } : {}),
+        last_status_text: hint || events[0]?.description || 'Tracking information received',
+        last_update: events[0]?.time ?? null,
+        expected_delivery: null,
+        timezone: ZONE,
+        events,
+        source: 'mondial_relay_app',
+    };
+}
+/**
+ * The consumer app's backend, signed in as one InPost account. Searching
+ * needs no link between that account and the parcel. Requests carry the
+ * app's shared signature; the account's refresh token renews a two-hour
+ * access token, kept per client.
+ */
+export class MondialRelayAppClient {
+    #refreshToken;
+    #fetcher;
+    #userAgent;
+    #now;
+    #access = null;
+    #renewing = null;
+    constructor(options) {
+        this.#refreshToken = options.refreshToken.trim();
+        if (!this.#refreshToken)
+            throw new TypeError('Mondial Relay app tracking needs a refresh token');
+        this.#fetcher = options.fetcher ?? http1Fetch;
+        this.#userAgent = userAgentOf(options.userAgent);
+        this.#now = options.now ?? Date.now;
+    }
+    /**
+     * One parcel, found by its shipment and the recipient postcode, or by a
+     * barcode's brand and shipment alone. A search that does not single out the
+     * parcel is inconclusive: the website also accepts the sender's postcode.
+     */
+    async track(query, options) {
+        const { shipment, postcode } = query;
+        if (!/^(?:\d{8}|\d{10}|\d{12})$/.test(shipment))
+            throw new TypeError('Mondial Relay app tracking takes 8, 10 or 12 digits');
+        const deadline = performance.now() + options.timeoutMs;
+        const left = () => Math.max(1, Math.floor(deadline - performance.now()));
+        try {
+            const search = await this.#get('parcels-search', postcode
+                ? { shipmentUid: shipment.length === 8 ? shipment : shipment.slice(2, 10), postcode }
+                : { shipmentUid: shipment.slice(0, 10) }, options.signal, left);
+            if (!isRecord(search) || !Array.isArray(search.list))
+                invalid();
+            const matches = search.list.flatMap((entry) => {
+                const uid = isRecord(entry) && isRecord(entry.expedition) ? cleanScalar(entry.expedition.shipmentUid, 16) : '';
+                // The 10-digit UID is the brand followed by the shipment.
+                return /^\d{10}$/.test(uid) && (shipment.length === 8 ? uid.slice(2) === shipment : uid === shipment.slice(0, 10)) ? [uid] : [];
+            });
+            const uids = [...new Set(matches)];
+            if (uids.length !== 1)
+                throw new IndeterminateError('Mondial Relay', 'Mondial Relay app could not single out the shipment');
+            const detail = await this.#get('parcels-detail', { shipmentUids: uids[0], parcelType: 'received' }, options.signal, left);
+            return parseMondialRelayApp(detail, uids[0]);
+        }
+        catch (error) {
+            options.signal.throwIfAborted();
+            // Transport diagnostics carry the bearer token and the postcode.
+            if (error instanceof CarrierError)
+                throw new CarrierError(error.kind, 'Mondial Relay', `Mondial Relay app tracking failed (${error.kind})`, {
+                    status: error.status, retryAfterMs: error.retryAfterMs, reason: error.reason,
+                });
+            throw new TransportError('Mondial Relay', 'Mondial Relay app request failed');
+        }
+    }
+    /** A signed request; a rejected access token is renewed once. */
+    async #get(path, query, signal, left) {
+        const url = new URL(path, MONDIAL_RELAY_APP_API);
+        for (const [name, value] of Object.entries(query))
+            url.searchParams.set(name, value);
+        for (let attempt = 0;; attempt += 1) {
+            const token = await this.#accessToken(signal, left);
+            const nonce = randomUUID();
+            const clock = String(Math.floor(this.#now() / 1000));
+            const sha256 = (value) => createHash('sha256').update(value).digest('hex');
+            const { response, bytes } = await fetchBounded(url, { signal, headers: {
+                    Accept: 'application/json', 'Accept-Language': 'fr-FR', 'User-Agent': this.#userAgent, 'X-OriginApp': 'MR',
+                    'X-MR-Param1': nonce, 'X-MR-Param2': clock, 'X-MR-API-KEY': sha256(sha256(SIGNING_SECRET + nonce + clock)),
+                    Authorization: `Bearer ${token}`,
+                } }, { provider: 'Mondial Relay', maxBytes: MAX_BYTES, timeoutMs: left(), fetcher: this.#fetcher, allowHttpStatuses: [401, 403, 404] });
+            if (response.status === 401 && !attempt) {
+                if (this.#access?.token === token)
+                    this.#access = null;
+                continue;
+            }
+            if ([401, 403].includes(response.status))
+                throw new ChallengeError('Mondial Relay', 'Mondial Relay refused the app request');
+            // A missing parcel is an empty search; a 404 is a moved route.
+            if (response.status === 404)
+                throw new TransportError('Mondial Relay', 'Mondial Relay app service is unavailable', { status: 404 });
+            if (response.status !== 200)
+                throw new UpstreamHttpError('Mondial Relay', response.status);
+            return json(bytes);
+        }
+    }
+    /** The current access token, renewed by one request at a time. */
+    async #accessToken(signal, left) {
+        if (this.#access && this.#access.expiresAt - EXPIRY_MARGIN_MS > this.#now())
+            return this.#access.token;
+        signal.throwIfAborted();
+        this.#renewing ??= this.#renew(left()).finally(() => { this.#renewing = null; });
+        const renewing = this.#renewing;
+        let leave;
+        const aborted = new Promise((_resolve, reject) => {
+            leave = () => reject(signal.reason);
+            signal.addEventListener('abort', leave, { once: true });
+        });
+        try {
+            return await Promise.race([renewing, aborted]);
+        }
+        finally {
+            signal.removeEventListener('abort', leave);
+        }
+    }
+    async #renew(timeoutMs) {
+        const body = new URLSearchParams({ client_id: CLIENT_ID, grant_type: 'refresh_token', refresh_token: this.#refreshToken });
+        const { response, bytes } = await fetchBounded(TOKEN_URL, { method: 'POST', body, headers: {
+                Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': this.#userAgent,
+            } }, { provider: 'Mondial Relay', maxBytes: 100_000, timeoutMs, fetcher: this.#fetcher, allowHttpStatuses: [400, 401] });
+        // An expired or revoked sign-in needs a new one; the website still answers meanwhile.
+        if (response.status !== 200)
+            throw new ChallengeError('Mondial Relay', 'Mondial Relay refused the account token');
+        const reply = json(bytes);
+        if (!isRecord(reply))
+            invalid();
+        const token = cleanScalar(reply.access_token, 8_192);
+        const lifetime = Number(reply.expires_in);
+        if (!/^[\w-]+\.[\w-]+\.[\w-]+$/.test(token) || !Number.isFinite(lifetime) || lifetime <= 0)
+            invalid();
+        this.#access = { token, expiresAt: this.#now() + lifetime * 1000 };
+        return token;
+    }
+}

package/dist/carriers/mondial-relay/carrier.json

@@ -35,6 +35,7 @@
       }
     ],
     "steps": [
+      "app",
       "trawl"
     ]
   },

package/dist/server/openapi.json

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

package/package.json

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