universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/relais-colis/adapter.js

@@ -0,0 +1,242 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import makeFetchCookie from 'fetch-cookie';
+import { CookieJar } from 'tough-cookie';
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { IndeterminateError, NotFoundError, SchemaError, TransportError } from '../../core/errors/index.js';
+import { clean, decodeText, fetchBounded, UpstreamHttpError, UpstreamNetworkError } from '../../core/transport/index.js';
+import { calendarDay, zonedTime } from '../../core/time/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { classifyRelaisColisStatus, comparableText } from './status.js';
+const TRACKING_PAGE = 'https://www.relaiscolis.com/colis/suivre';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 750_000;
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:147.0) Gecko/20100101 Firefox/147.0';
+function eventClock(value) {
+    const match = /^(\d{2})[/-](\d{2})[/-](\d{4})(?:\s+(?:à\s+)?(\d{1,2})[:h](\d{2}))?$/.exec(value);
+    if (!match)
+        return { instant: null, local: null };
+    const day = calendarDay(Number(match[3]), Number(match[2]), Number(match[1]));
+    if (!day)
+        return { instant: null, local: null };
+    if (!match[4])
+        return { instant: null, local: day };
+    const hour = Number(match[4]);
+    const minute = Number(match[5]);
+    if (hour > 23 || minute > 59)
+        return { instant: null, local: null };
+    const local = `${day}T${String(hour).padStart(2, '0')}:${match[5]}:00`;
+    const instant = zonedTime(local, "yyyy-MM-dd'T'HH:mm:ss", 'Europe/Paris');
+    // A nonexistent civil clock can be normalized across a DST transition.
+    const uniqueOffset = DateTime.fromISO(local, { zone: 'Europe/Paris' }).getPossibleOffsets().length === 1;
+    return { instant: instant?.iso.startsWith(local) && uniqueOffset ? instant : null, local };
+}
+/**
+ * Kept so the grouped live canary and existing host callers can still match
+ * this name; the taxonomy kind is `not_found` like any other missing shipment.
+ */
+export class RelaisColisTrackingError extends NotFoundError {
+    constructor() {
+        super('Relais Colis');
+        this.name = 'RelaisColisTrackingError';
+    }
+}
+export function normalizeRelaisColisTrackingNumber(raw) {
+    const trackingNumber = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^[A-Z0-9]{10,16}$/.test(trackingNumber) || !/\d/.test(trackingNumber)) {
+        throw new TypeError('Relais Colis tracking numbers must contain 10 to 16 letters and digits');
+    }
+    return trackingNumber;
+}
+export function relaisColisTrackingUrl() {
+    return TRACKING_PAGE;
+}
+function responseTrackingNumber(page) {
+    // History pages name the parcel once, in a "Votre colis" banner, and have no
+    // search form. Pages without history re-render the form with the searched number.
+    const banners = page('.back-subedtext--sub');
+    const fields = page('#track_package_trackingNumber');
+    if (banners.length > 1 || fields.length > 1)
+        return '';
+    const labelled = banners.filter((_, element) => (page(element).siblings('.back-subedtext').toArray().some((label) => comparableText(page(label).text()) === 'votre colis')));
+    if (labelled.length !== banners.length)
+        return '';
+    // The form value only echoes the request, so it cannot vouch for history alone.
+    if (page('.follow-step').length && !labelled.length)
+        return '';
+    const values = [labelled.text(), fields.attr('value') ?? ''].filter((value) => value.trim());
+    try {
+        const numbers = new Set(values.map(normalizeRelaisColisTrackingNumber));
+        return numbers.size === 1 ? [...numbers][0] : '';
+    }
+    catch {
+        return '';
+    }
+}
+export function parseRelaisColisTrackingHtml(html, rawTrackingNumber) {
+    const trackingNumber = normalizeRelaisColisTrackingNumber(rawTrackingNumber);
+    if (!html.trim())
+        throw new IndeterminateError('Relais Colis', 'Relais Colis returned an empty tracking response');
+    const $ = load(html);
+    $('.follow-address, .follow-address-box, [data-recipient], [data-delivery-address], script, style, noscript').remove();
+    const errorText = comparableText($('.field-error, .follow-text--error, .error').text());
+    if (errorText.includes('jeton csrf est invalide')) {
+        throw new IndeterminateError('Relais Colis', 'Relais Colis rejected the tracking session');
+    }
+    const returnedNumber = responseTrackingNumber($);
+    if (!returnedNumber)
+        throw new SchemaError('Relais Colis', 'Relais Colis did not return a shipment identifier');
+    if (returnedNumber !== trackingNumber)
+        throw new SchemaError('Relais Colis', 'Relais Colis returned a different shipment');
+    if (errorText && !$('.follow-step').length) {
+        if (errorText === 'aucune donnee de suivi pour votre colis veuillez reessayer plus tard')
+            throw new RelaisColisTrackingError();
+        throw new IndeterminateError('Relais Colis', 'Relais Colis returned an unrecognized form error');
+    }
+    const parsed = [];
+    const seen = new Set();
+    const add = (description, time) => {
+        if (!description)
+            throw new SchemaError('Relais Colis', 'Relais Colis returned a scan without a status');
+        const identity = `${time}\u0000${description}`;
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const clock = eventClock(time);
+        const classified = classifyRelaisColisStatus(description);
+        if (parsed.length >= 500)
+            throw new SchemaError('Relais Colis', 'Relais Colis returned excessive tracking history');
+        parsed.push({ event: {
+                ...(clock.instant ? { time: clock.instant.iso } : clock.local ? { local_time: clock.local } : {}),
+                ...(!clock.instant && time ? { provider_time_text: time } : {}),
+                location: '', description, stage: classified.stage,
+            }, status: classified.status, local: clock.instant ? null : clock.local });
+    };
+    if ($('.follow-step').length > 250)
+        throw new SchemaError('Relais Colis', 'Relais Colis returned excessive tracking history');
+    $('.follow-step').each((_, element) => {
+        const row = $(element);
+        const heading = clean(row.find('.follow-step-text').first().text());
+        const groups = row.find('.box').filter((_, box) => $(box).children('.follow-step-date').length > 0);
+        if (groups.length) {
+            groups.each((_, box) => {
+                const values = $(box).children('.follow-step-date');
+                if (values.length !== 2 || !clean(values.eq(1).text()))
+                    throw new SchemaError('Relais Colis', 'Relais Colis returned an ambiguous scan group');
+                add(clean(values.eq(1).text()), clean(values.eq(0).text(), 64));
+            });
+        }
+        else {
+            add(heading, clean(row.find('.follow-step-date').first().text(), 64));
+        }
+    });
+    const limited = parsed.slice(0, 100);
+    const latest = limited[0];
+    if (!latest)
+        throw new SchemaError('Relais Colis', 'Relais Colis did not return tracking history');
+    // Both groups and scans are displayed newest first. Unresolved current clocks
+    // and unfamiliar current wording must not borrow an older delivery's state.
+    return { status: latest.status, last_status_text: latest.event.description,
+        last_update: latest.event.time ?? null, ...(latest.local ? { last_update_local: latest.local } : {}),
+        expected_delivery: null, timezone: 'Europe/Paris', events: limited.map(({ event }) => event) };
+}
+function csrfToken(html) {
+    const token = clean(load(html)('#track_package__token').first().attr('value'), 512);
+    if (!token)
+        throw new SchemaError('Relais Colis', 'Relais Colis did not return a CSRF token');
+    return token;
+}
+function responseError(provider, status) {
+    const cause = new UpstreamHttpError(provider, status);
+    return [404, 410].includes(status)
+        ? new TransportError('Relais Colis', 'Relais Colis tracking page is unavailable', { status, cause }) : cause;
+}
+function pageHeaders() {
+    return {
+        Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+        'Accept-Language': 'fr-FR,fr;q=0.9',
+        'User-Agent': USER_AGENT,
+    };
+}
+export class RelaisColisTracker {
+    timeoutMs;
+    fetcher;
+    recorder;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.fetcher = options.fetcher;
+        this.recorder = options.recorder ?? NOOP_RECORDER;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('Relais Colis timeout must be positive');
+        }
+    }
+    async fetch(rawTrackingNumber, context = {}) {
+        const trackingNumber = normalizeRelaisColisTrackingNumber(rawTrackingNumber);
+        return runSteps({ carrier: 'relais-colis', budgetMs: context.budgetMs ?? this.timeoutMs,
+            signal: context.signal, recorder: this.recorder }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    try {
+                        // One cookie jar per lookup: the CSRF token is bound to the session it was
+                        // issued for, and nothing is shared between concurrent lookups.
+                        const sessionFetch = makeFetchCookie(this.fetcher ?? fetch, new CookieJar());
+                        const bootstrap = await fetchBounded(TRACKING_PAGE, {
+                            headers: pageHeaders(), signal,
+                        }, {
+                            provider: 'Relais Colis tracking page',
+                            timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                            maxBytes: MAX_RESPONSE_BYTES,
+                            redirect: 'manual',
+                            fetcher: sessionFetch,
+                            allowHttpError: true,
+                        });
+                        if (!bootstrap.response.ok) {
+                            throw responseError('Relais Colis tracking page', bootstrap.response.status);
+                        }
+                        const body = new URLSearchParams({
+                            'track_package[trackingNumber]': trackingNumber,
+                            'track_package[searchPackage]': '',
+                            'track_package[_token]': csrfToken(decodeText(bootstrap.bytes)),
+                        });
+                        const result = await fetchBounded(TRACKING_PAGE, {
+                            method: 'POST', signal,
+                            headers: {
+                                ...pageHeaders(),
+                                'Content-Type': 'application/x-www-form-urlencoded',
+                                Origin: 'https://www.relaiscolis.com',
+                                Referer: TRACKING_PAGE,
+                            },
+                            body,
+                        }, {
+                            provider: 'Relais Colis tracking',
+                            timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                            maxBytes: MAX_RESPONSE_BYTES,
+                            redirect: 'manual',
+                            fetcher: sessionFetch,
+                            allowHttpError: true,
+                        });
+                        if (!result.response.ok) {
+                            throw responseError('Relais Colis tracking', result.response.status);
+                        }
+                        const parsed = parseRelaisColisTrackingHtml(decodeText(result.bytes), trackingNumber);
+                        parsed.tracking_url = TRACKING_PAGE;
+                        parsed.tracking_source = 'rendered-page';
+                        return parsed;
+                    }
+                    catch (error) {
+                        // Session cookies and the posted token must not survive as diagnostics.
+                        if (error instanceof UpstreamNetworkError)
+                            throw new UpstreamNetworkError(error.provider, error.cause);
+                        throw error;
+                    }
+                } }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new RelaisColisTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return {
+        id: 'relais-colis', recordsSteps: true,
+        steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeRelaisColisTrackingNumber(number))),
+    };
+};

package/dist/carriers/relais-colis/carrier.json

@@ -0,0 +1,77 @@
+{
+  "id": "relais-colis",
+  "displayName": "Relais Colis",
+  "aliases": [
+    "Relais Colis (Groupe Ducros)"
+  ],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#7bb928"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "relais-colis",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 25
+    },
+    "localClocks": true
+  },
+  "capabilities": [
+    "history"
+  ],
+  "portal": {
+    "url": "https://www.relaiscolis.com/colis/suivre?tracking_number={trackingNumber}",
+    "canaryUrl": "https://www.relaiscolis.com/colis/suivre",
+    "shows": [
+      "status",
+      "history",
+      "recipient_name",
+      "recipient_address",
+      "pickup_point"
+    ],
+    "scraped": [
+      "status",
+      "history"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "pickup_point"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "relaiscolis.com"
+      ],
+      "params": [
+        "tracking_number",
+        "trackingNumber",
+        "numeroColis",
+        "numColis"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "relais-colis-1",
+      "pattern": "^CC\\d{10,14}$",
+      "confidence": "high"
+    },
+    {
+      "id": "relais-colis-2",
+      "pattern": "^\\d{10}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/relais-colis/numbers.json

@@ -0,0 +1,64 @@
+{
+  "carrier": "relais-colis",
+  "records": [
+    {
+      "number": "338 0000 318",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://forum.quechoisir.org/attitude-inadmissible-de-relais-colis-fuyez-t216835.html",
+        "date": "2019-05-03"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Relais Colis, which stays one candidate among several."
+    },
+    {
+      "number": "CC109000006501",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a0790884a72dd12fbe83e46",
+        "date": "2026-05-15"
+      },
+      "expect": {
+        "carrier": "relais-colis",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "CC200000000401",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "relais-colis",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "CC999999999901",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "relais-colis",
+        "confidence": "high"
+      },
+      "note": "Invented number following the published Relais Colis format."
+    }
+  ]
+}

package/dist/carriers/relais-colis/status.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Relais Colis step wording → product stage.
+ *
+ * The recipient page prints a French sentence per step and no status code, so
+ * the map is phrase-based. Phrases are compared after lower-casing, stripping
+ * diacritics and collapsing everything that is not a letter or a digit, which
+ * makes the upper-case banner wording and the sentence-case timeline wording
+ * the same key.
+ *
+ * Order matters: return and failure sentences are tested first, then the two
+ * pickup states, and only then delivery, because the network's vocabulary
+ * reuses "relais" across several stages. Unlike the other French adapters this
+ * one keeps the provider's own sentence as the event description, so the map
+ * only decides the stage. Sentences it does not recognize get no carrier
+ * stage assignment beyond the transit default and are left to the sync's
+ * wording classifier.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface ClassifiedRelaisColisStatus {
+    status: CarrierStatus;
+    stage: Stage;
+}
+/** Lower-case, unaccent and reduce a French sentence to letters, digits and single spaces. */
+export declare function comparableText(value: string): string;
+export declare function classifyRelaisColisStatus(description: string): ClassifiedRelaisColisStatus;

package/dist/carriers/relais-colis/status.js

@@ -0,0 +1,91 @@
+import { clean } from '../../core/transport/index.js';
+/** Lower-case, unaccent and reduce a French sentence to letters, digits and single spaces. */
+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();
+}
+function includesAny(value, phrases) {
+    return phrases.some((phrase) => value.includes(phrase));
+}
+export function classifyRelaisColisStatus(description) {
+    const value = comparableText(description);
+    if (/\bretour/.test(value)) {
+        if (/\b(?:en cours de|en cours d acheminement|achemine vers)\b/.test(value)) {
+            return { status: 'in_transit', stage: 'in_transit' };
+        }
+        if (/\b(?:sera|va etre|doit etre)\b/.test(value))
+            return { status: 'unknown', stage: 'in_transit' };
+    }
+    if (includesAny(value, [
+        'retour a l expediteur',
+        'retourne a l expediteur',
+        'retourne a votre vendeur',
+        'retour a votre vendeur',
+        'retour vendeur',
+    ]))
+        return { status: 'exception', stage: 'returned' };
+    if (includesAny(value, [
+        'adresse incorrecte',
+        'colis endommage',
+        'colis refuse',
+        'colis perdu',
+    ]))
+        return { status: 'exception', stage: 'exception' };
+    if (includesAny(value, [
+        'livraison impossible',
+        'echec de livraison',
+        'incident de livraison',
+        'destinataire absent',
+        'n a pas pu etre livre',
+    ]))
+        return { status: 'exception', stage: 'failed_attempt' };
+    if (includesAny(value, [
+        'disponible dans votre relais',
+        'disponible au relais',
+        'disponible en relais',
+        'mis a disposition dans votre relais',
+        'vous attend dans votre relais',
+        'a retirer dans votre relais',
+    ]))
+        return { status: 'out_for_delivery', stage: 'ready_for_pickup' };
+    if (includesAny(value, [
+        'en cours de livraison',
+        'en cours de distribution',
+        'livraison dans votre relais',
+    ]))
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    if (includesAny(value, [
+        'retire par le destinataire',
+        'remis au destinataire',
+        'remis a son destinataire',
+        'livraison effectuee',
+    ]) || /\b(?:colis|commande) (?:a ete|est) livre\b/.test(value)) {
+        return { status: 'delivered', stage: 'delivered' };
+    }
+    if (includesAny(value, [
+        'commande enregistree',
+        'colis annonce',
+        'colis a ete annonce',
+        'information transmise',
+        'en attente de prise en charge',
+        'sera prochainement confie',
+    ]))
+        return { status: 'pending', stage: 'registered' };
+    if (includesAny(value, [
+        'pris en charge',
+        'en cours d acheminement',
+        'en transit',
+        'arrive dans notre agence',
+        'arrive sur notre agence',
+        'a quitte notre agence',
+        'achemine vers',
+        'expedie vers',
+    ]))
+        return { status: 'in_transit', stage: 'in_transit' };
+    return { status: 'unknown', stage: 'in_transit' };
+}