universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,288 @@
+import { load } from 'cheerio';
+import { ChallengeError, IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { eventPoint } from '../../core/result/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { zonedTime } from '../../core/time/index.js';
+import { TrawlClient, clean, decodeText, fetchBounded } from '../../core/transport/index.js';
+import { classifyStatus, comparableText, includesAny } from './status.js';
+// Protocol provenance:
+// - DPD France publishes a server-rendered recipient page rather than a
+//   reusable JSON feed, so the timeline is read out of `#tableTrace`: one row
+//   per scan, four cells (date, clock, wording, operational location), plus a
+//   details block per leg (`#infos1` outbound, `#infos2` return).
+// - One page can describe two parcels: an outbound number and its return
+//   number. The requested number decides which leg is read; the other leg's
+//   rows never enter the result.
+// - Cloudflare normally challenges anonymous direct requests, so the page is
+//   fetched directly first and through the private browser service's native
+//   scrape API when that request is challenged.
+const TRACKING_BASE = 'https://trace.dpd.fr/fr/trace';
+const TIMEZONE = 'Europe/Paris';
+const DEFAULT_TIMEOUT_MS = 90_000;
+const DIRECT_TIMEOUT_MS = 20_000;
+/** The browser service keeps its own transport allowance on top of this budget. */
+const SOLVER_ALLOWANCE_MS = 15_000;
+const MAX_RESPONSE_BYTES = 2_000_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+/** Cloudflare interrupted the trace page with an interactive challenge. */
+export class DPDFranceChallengeError extends ChallengeError {
+    constructor(message = 'DPD France returned a Cloudflare browser challenge') {
+        super('DPD France', message);
+        this.name = 'DPDFranceChallengeError';
+    }
+}
+/** DPD France positively reports that it does not know the parcel number. */
+export class DPDFranceTrackingError extends NotFoundError {
+    constructor() {
+        super('DPD France', 'DPD France could not locate the shipment');
+        this.name = 'DPDFranceTrackingError';
+    }
+}
+function challenged(status, headers, html) {
+    return (status === 403 && headers.get('cf-mitigated') === 'challenge')
+        || /Just a moment|Performing security verification|Enable JavaScript and cookies/i.test(html);
+}
+/** Trace rows carry naive Paris wall-clock times in two separate cells. */
+function parsedEventTime(date, clock) {
+    return zonedTime(`${date} ${clock}`, 'dd/MM/yyyy HH:mm', TIMEZONE);
+}
+/** The details block prints a plain calendar day; only the day is retained. */
+function expectedDeliveryDate(value) {
+    const parsed = zonedTime(value, 'dd/MM/yyyy', TIMEZONE, { maxLength: 32 });
+    return parsed ? parsed.iso.slice(0, 10) : null;
+}
+export function normalizeDPDFranceTrackingNumber(raw) {
+    const value = raw.replace(/[\s.-]/g, '');
+    if (!/^(?:[01]\d{11,14}|250\d{9,12})$/.test(value)) {
+        throw new TypeError('DPD France tracking numbers must start with 0, 1, or 250 and contain 12 to 15 digits');
+    }
+    return value;
+}
+export function dpdFranceTrackingUrl(raw) {
+    const number = normalizeDPDFranceTrackingNumber(raw);
+    return `${TRACKING_BASE}/${encodeURIComponent(number)}`;
+}
+/**
+ * The delivering depot's number and map marker, from the page's depot tab
+ * ("DPD France SAS Etablissement 067"). Scan rows name depots by the same
+ * number: "Agence DPD de Strasbourg (67)". Its street address is never read.
+ */
+function deliveringDepot($) {
+    const depot = $('#agence');
+    // Only the first line, which names the depot: <br> carries no text, so .text() would join it to the street.
+    const heading = (depot.find('.agInfos').first().html() ?? '').split(/<br\s*\/?>/i)[0];
+    const number = /\bEtablissement\s+(\d{1,4})\s*$/i.exec(clean(load(heading).text(), 200))?.[1];
+    const marker = depot.find('.marker-default').first();
+    const point = eventPoint(marker.attr('data-lat'), marker.attr('data-lng'));
+    // Mainland France and Corsica: DPD France's depots.
+    if (!number || !point || point.latitude < 41 || point.latitude > 51.5 || point.longitude < -5.5 || point.longitude > 10) {
+        return null;
+    }
+    return { number: Number(number), point };
+}
+export function parseDPDFranceTrackingHtml(html, rawTrackingNumber) {
+    const trackingNumber = normalizeDPDFranceTrackingNumber(rawTrackingNumber);
+    if (!html.trim())
+        throw new SchemaError('DPD France', 'DPD France returned an empty tracking response');
+    if (/Just a moment|Performing security verification|Enable JavaScript and cookies/i.test(html)) {
+        throw new DPDFranceChallengeError();
+    }
+    const $ = load(html);
+    const displayedNumbers = (selector) => $(selector).map((_, element) => (clean($(element).text(), 64).replace(/\D/g, ''))).get().filter(Boolean);
+    const detailsNumbers = (selector) => $(`${selector} .tableInfosAR`).map((_, element) => {
+        const row = $(element);
+        return comparableText(row.find('strong').text()) === 'n colis'
+            ? clean(row.find('.tdInfos').text(), 64).replace(/\D/g, '')
+            : '';
+    }).get().filter(Boolean);
+    const outboundNumbers = [
+        ...displayedNumbers('.parcelNumberAller'),
+        ...detailsNumbers('#infos1'),
+    ];
+    const returnNumbers = [
+        ...displayedNumbers('.parcelNumberRetour'),
+        ...detailsNumbers('#infos2'),
+    ];
+    const responseNumbers = [...new Set([...outboundNumbers, ...returnNumbers])];
+    if (responseNumbers.length === 0) {
+        if (/pas en mesure de retrouver le num[eé]ro de colis|num[eé]ro de colis inconnu/i.test(html)) {
+            throw new DPDFranceTrackingError();
+        }
+        throw new SchemaError('DPD France', 'DPD France did not return tracking details');
+    }
+    if (!responseNumbers.includes(trackingNumber)) {
+        throw new SchemaError('DPD France', 'DPD France returned a different shipment');
+    }
+    const isReturn = !outboundNumbers.includes(trackingNumber) && returnNumbers.includes(trackingNumber);
+    const eventSelector = isReturn
+        ? '#tableTrace tr.tabTraceColisRetour'
+        : '#tableTrace tr.tabTraceColisAller';
+    const detailsSelector = isReturn ? '#infos2' : '#infos1';
+    const depot = deliveringDepot($);
+    const parsedEvents = [];
+    const seen = new Set();
+    $(eventSelector).slice(0, MAX_EVENTS_TO_INSPECT).each((sourceIndex, element) => {
+        const row = $(element);
+        const cells = row.children('td');
+        const date = clean(cells.eq(0).text(), 32);
+        const clock = clean(cells.eq(1).text(), 32);
+        const description = clean(cells.eq(2).text());
+        const location = clean(cells.eq(3).text());
+        const time = parsedEventTime(date, clock);
+        if (!time || !description)
+            return;
+        const identity = JSON.stringify([time.iso, location, description]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = classifyStatus(description);
+        // Wording the map does not recognize carries no stage: the sync's
+        // classifier decides, and the row still stays visible in the history.
+        const mapped = classified.status !== 'unknown';
+        const depotNumber = /\((\d{1,4})\)$/.exec(location)?.[1];
+        const point = depot && depotNumber && Number(depotNumber) === depot.number ? depot.point : null;
+        parsedEvents.push({
+            event: {
+                time: time.iso,
+                location,
+                description,
+                ...(mapped ? { stage: classified.stage } : {}),
+                ...(point ? { point } : {}),
+            },
+            status: classified.status,
+            timestamp: time.timestamp,
+            sourceIndex,
+        });
+    });
+    parsedEvents.sort((left, right) => (right.timestamp - left.timestamp || left.sourceIndex - right.sourceIndex));
+    const events = parsedEvents.slice(0, MAX_EVENTS_TO_RETURN).map(({ event }) => event);
+    const latest = parsedEvents.find((event) => event.status !== 'unknown');
+    const status = latest?.status ?? 'unknown';
+    const lastStatusText = events[0]?.description ?? 'Tracking information received';
+    let expectedDelivery = null;
+    $(`${detailsSelector} .tableInfosAR`).each((_, element) => {
+        if (expectedDelivery)
+            return;
+        const row = $(element);
+        const label = comparableText(row.find('strong').text());
+        if (includesAny(label, ['livraison prevue', 'date de livraison prevue'])) {
+            expectedDelivery = expectedDeliveryDate(row.find('.tdInfos').text());
+        }
+    });
+    return {
+        status,
+        last_status_text: lastStatusText,
+        last_update: events[0]?.time ?? null,
+        expected_delivery: ['delivered', 'exception'].includes(status) ? null : expectedDelivery,
+        timezone: TIMEZONE,
+        events,
+    };
+}
+export class DPDFranceTracker {
+    timeoutMs;
+    directTimeoutMs;
+    budgetMs;
+    trawlUrl;
+    fetcher;
+    configuredTrawl;
+    recorder;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.directTimeoutMs = Math.max(1_000, Math.min(this.timeoutMs, options.directTimeoutMs ?? DIRECT_TIMEOUT_MS));
+        this.budgetMs = options.budgetMs
+            ?? this.directTimeoutMs + this.timeoutMs + SOLVER_ALLOWANCE_MS;
+        this.trawlUrl = (options.trawlUrl ?? '').trim();
+        this.fetcher = options.fetcher;
+        this.configuredTrawl = options.trawl;
+        this.recorder = options.recorder;
+    }
+    /** The browser service, resolved late so a malformed URL fails the tier, not construction. */
+    browserService() {
+        if (this.configuredTrawl !== undefined)
+            return this.configuredTrawl;
+        return this.trawlUrl ? new TrawlClient(this.trawlUrl, this.fetcher) : null;
+    }
+    async fetch(rawTrackingNumber) {
+        const number = normalizeDPDFranceTrackingNumber(rawTrackingNumber);
+        const url = dpdFranceTrackingUrl(number);
+        const trawl = this.browserService();
+        const html = await runSteps({
+            carrier: 'dpd-fr', budgetMs: this.budgetMs, recorder: this.recorder,
+        }, [
+            {
+                id: 'direct',
+                run: async () => {
+                    try {
+                        return await this.directGet(url);
+                    }
+                    catch (error) {
+                        // Without a browser service there is no second tier, so the
+                        // challenge has to carry the operator's next step itself.
+                        if (trawl || !(error instanceof DPDFranceChallengeError))
+                            throw error;
+                        throw new DPDFranceChallengeError('DPD France requires a browser challenge solver; configure FLARESOLVERR_URL');
+                    }
+                },
+            },
+            {
+                id: 'trawl',
+                enabled: trawl !== null,
+                recovers: (error) => error instanceof DPDFranceChallengeError,
+                run: async () => (await trawl.scrape({
+                    url,
+                    skipHttp: true,
+                    maxTier: 3,
+                    maxTimeout: this.timeoutMs,
+                }, {
+                    provider: 'TRAWL while fetching DPD France',
+                    timeoutMs: this.timeoutMs,
+                    maxBytes: MAX_RESPONSE_BYTES,
+                    fetcher: this.fetcher,
+                })).html,
+            },
+        ]);
+        const result = parseDPDFranceTrackingHtml(html, number);
+        result.tracking_url = url;
+        result.tracking_source = 'rendered-page';
+        return result;
+    }
+    async directGet(url) {
+        const result = await fetchBounded(url, {
+            headers: {
+                Accept: 'text/html,application/xhtml+xml',
+                'Accept-Language': 'fr-FR,fr;q=0.9',
+                'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/140 Safari/537.36',
+            },
+        }, {
+            provider: 'DPD France tracking',
+            timeoutMs: this.directTimeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            redirect: 'follow',
+            allowHttpError: true,
+            fetcher: this.fetcher,
+        });
+        const html = decodeText(result.bytes);
+        if (challenged(result.response.status, result.response.headers, html)) {
+            throw new DPDFranceChallengeError();
+        }
+        if (!result.response.ok) {
+            throw new IndeterminateError('DPD France', `DPD France tracking returned HTTP ${result.response.status}`);
+        }
+        return html;
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new DPDFranceTracker({
+        fetcher: environment.fetcher,
+        trawl: environment.trawl,
+        recorder: environment.recorder,
+    });
+    return {
+        id: 'dpd-fr',
+        // One direct HTML GET, then the browser service's native scrape API when
+        // Cloudflare challenges it.
+        steps: ['direct', 'trawl'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

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

@@ -0,0 +1,83 @@
+{
+  "id": "dpd-fr",
+  "displayName": "DPD France",
+  "aliases": [
+    "Exapaq"
+  ],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#dc0032"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "dpd-fr",
+    "steps": [
+      "direct",
+      "trawl"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://trace.dpd.fr/fr/trace/{trackingNumber}",
+    "canaryUrl": "https://trace.dpd.fr/fr/trace",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "customer_reference"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "signature",
+      "customer_reference"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "trace.dpd.fr"
+      ],
+      "path": "^/(?:fr/trace|trace-particuliers)/([^/?#]+)/?$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "dpd-fr-1",
+      "pattern": "^250\\d{12}$",
+      "confidence": "high"
+    },
+    {
+      "id": "dpd-fr-3",
+      "pattern": "^10\\d{12}$",
+      "confidence": "low",
+      "preferred": true
+    },
+    {
+      "id": "dpd-fr-2",
+      "pattern": "^(?:[01]\\d{11,14}|250\\d{9,11})$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/dpd-fr/numbers.json

@@ -0,0 +1,80 @@
+{
+  "carrier": "dpd-fr",
+  "records": [
+    {
+      "number": "10084004615036",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a8eff71916b1b8a60cbc2b4",
+        "date": "2026-08-26"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to DPD France, which stays one candidate among several."
+    },
+    {
+      "number": "10764000276716",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://marketplace.fnacdarty.com/s/article/Dois-je-obligatoirement-renseigner-un-num%C3%A9ro-de-suivi-tracking-pour-ma-commande?language=fr_BE"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "dpd",
+          "ciblex",
+          "seur",
+          "brt",
+          "delhivery"
+        ]
+      },
+      "note": "Published integration example, not a real shipment. The source attributes it to DPD France, which stays one candidate among several."
+    },
+    {
+      "number": "1595193512495",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://marketplace.fnacdarty.com/s/article/Dois-je-obligatoirement-renseigner-un-num%C3%A9ro-de-suivi-tracking-pour-ma-commande?language=fr_BE"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Published integration example, not a real shipment. The source attributes it to DPD France, which stays one candidate among several."
+    },
+    {
+      "number": "250123456789012",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "dpd-fr",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    }
+  ]
+}

package/dist/carriers/dpd-fr/status.d.ts

@@ -0,0 +1,21 @@
+/**
+ * DPD France status vocabulary.
+ *
+ * The recipient trace page carries no status codes at all: every row is French
+ * prose in a `<td>`, so the only key available is the wording itself. Matching
+ * is done on a diacritic- and punctuation-free form of the sentence
+ * (`comparableText`) because DPD France varies accents, apostrophes and
+ * trailing punctuation between rows.
+ *
+ * Order matters: returns and incidents are checked before the delivery
+ * wording, because "votre colis sera retourné à l'expéditeur" contains neither
+ * a delivery verb nor an incident noun on its own.
+ *
+ * Provenance: wording observed on https://trace.dpd.fr/fr/trace/<number> for
+ * outbound and return legs.
+ */
+import type { ClassifiedStatus } from '../../core/status/index.js';
+/** Lowercase, accent-free, punctuation-free form used for every wording comparison. */
+export declare function comparableText(value: string): string;
+export declare function includesAny(value: string, phrases: string[]): boolean;
+export declare function classifyStatus(description: string): ClassifiedStatus;

package/dist/carriers/dpd-fr/status.js

@@ -0,0 +1,93 @@
+import { clean } from '../../core/transport/index.js';
+/** Lowercase, accent-free, punctuation-free form used for every wording comparison. */
+export function comparableText(value) {
+    return clean(value)
+        .toLocaleLowerCase('fr-FR')
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export function includesAny(value, phrases) {
+    return phrases.some((phrase) => value.includes(phrase));
+}
+export function classifyStatus(description) {
+    const value = comparableText(description);
+    if (includesAny(value, [
+        'retour a l expediteur',
+        'retourne a l expediteur',
+        'sera retourne a l expediteur',
+    ]))
+        return { status: 'exception', stage: 'returned' };
+    if (includesAny(value, [
+        'reclamation',
+        'enquete est ouverte',
+        'incident',
+        'anomalie',
+        'endommage',
+        'refuse',
+        'perdu',
+    ]))
+        return { status: 'exception', stage: 'exception' };
+    if (includesAny(value, [
+        'echec de livraison',
+        'livraison impossible',
+        'n a pas pu etre livre',
+        'tentative de livraison',
+        'retard',
+    ]))
+        return { status: 'exception', stage: 'failed_attempt' };
+    if (includesAny(value, [
+        'votre colis est livre',
+        'votre colis a ete livre',
+        'remis au destinataire',
+        'livraison effectuee',
+    ]))
+        return { status: 'delivered', stage: 'delivered' };
+    if (includesAny(value, [
+        'disponible en relais',
+        'disponible au relais',
+        'disponible en agence',
+        'disponible en consigne',
+        'attend en relais',
+    ]))
+        return { status: 'out_for_delivery', stage: 'ready_for_pickup' };
+    // The same-day notices ("le destinataire est informé par SMS de la livraison
+    // de son colis ce jour") follow the delivery-round scan; read as plain
+    // movement they would pull the parcel back to "in transit" on delivery day.
+    if (includesAny(value, [
+        'en cours de livraison',
+        'en tournee de livraison',
+        'chauffeur a pris en charge',
+        'de la livraison de son colis ce jour',
+    ]))
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    if (includesAny(value, [
+        'en preparation chez l expediteur',
+        'informations concernant votre colis ont ete transmises',
+        'donnees du colis transmises',
+    ]))
+        return { status: 'pending', stage: 'registered' };
+    // Acceptance into the network, and the notices that report it to the recipient.
+    if (includesAny(value, [
+        'pris en charge dans notre reseau',
+        'de la prise en charge de son colis',
+    ]))
+        return { status: 'in_transit', stage: 'accepted' };
+    if (includesAny(value, [
+        'remis a dpd',
+        'pris en charge par dpd',
+        'en transit',
+        'arrive en france',
+        'arrive dans notre agence',
+        'prochaine agence',
+        'centre de tri',
+    ]))
+        return { status: 'in_transit', stage: 'in_transit' };
+    // Wording this map does not recognize keeps the row visible without claiming
+    // a milestone: the result status stays `unknown` so the lookup falls back to
+    // the newest recognized row. The `in_transit` stage kept here predates the
+    // package's "omit the stage when it is not mapped" rule; the adapter drops it.
+    return { status: 'unknown', stage: 'in_transit' };
+}