universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/geodis/adapter.js

@@ -0,0 +1,275 @@
+/**
+ * GEODIS: the anonymous recipient lookup behind espace-client.geodis.com.
+ *
+ * One bounded signed POST per lookup ('direct' step). The response describes the
+ * whole consignment: sender and recipient blocks, addresses, per-scan
+ * "complementary information" and links to delivery documents. `parse()` builds
+ * its result from an allowlist of status, timeline and operational-location
+ * fields, so none of that reaches the result or the logs.
+ */
+import { createHash } from 'node:crypto';
+import { IndeterminateError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyStatus, comparableText, includesAny } from './status.js';
+export { classifyStatus } from './status.js';
+const PROVIDER = 'GEODIS';
+const TRACKING_ENDPOINT = 'https://espace-client.geodis.com/services/api/destinataire/recherche-envoi-anonyme';
+const TRACKING_PAGE = 'https://espace-client.geodis.com/services/destinataires/';
+const SIGNED_API_PATH = 'api/destinataire/recherche-envoi-anonyme';
+const PUBLIC_SPA_APP_ID = '$DESTINATAIRE';
+// This is a public client identifier shipped in GEODIS's anonymous recipient SPA,
+// not an account credential. It can rotate when that SPA is deployed.
+const PUBLIC_SPA_APP_KEY = '21aed7a2f03d45ab9cbcd61cd7a2461d'; // gitleaks:allow
+const LANGUAGE = 'fr';
+const TIMEZONE = 'Europe/Paris';
+const MAX_RESPONSE_BYTES = 1_000_000;
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_EVENTS_TO_RETURN = 100;
+/**
+ * The endpoint reports a calendar day per group and a wall clock per scan, both
+ * as display strings and never with an offset. No `core/time` policy fits: the
+ * displayed value is kept verbatim as the event time, and the number below is
+ * only a sort key, built in UTC so ordering never shifts with a DST boundary.
+ */
+function dateTimestamp(value) {
+    let match = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(value);
+    let year;
+    let month;
+    let day;
+    if (match) {
+        day = Number(match[1]);
+        month = Number(match[2]);
+        year = Number(match[3]);
+    }
+    else {
+        match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        if (!match)
+            return null;
+        year = Number(match[1]);
+        month = Number(match[2]);
+        day = Number(match[3]);
+    }
+    const timestamp = Date.UTC(year, month - 1, day);
+    const date = new Date(timestamp);
+    return date.getUTCFullYear() === year
+        && date.getUTCMonth() === month - 1
+        && date.getUTCDate() === day
+        ? timestamp
+        : null;
+}
+function eventTime(dateValue, timeValue) {
+    const date = clean(dateValue, 32);
+    const timestamp = dateTimestamp(date);
+    if (timestamp === null)
+        return null;
+    const clock = clean(timeValue, 16);
+    if (!clock)
+        return { value: date, timestamp };
+    const match = /^([01]\d|2[0-3]):([0-5]\d)(?::([0-5]\d))?$/.exec(clock);
+    if (!match)
+        return { value: date, timestamp };
+    const withClock = timestamp
+        + Number(match[1]) * 3_600_000
+        + Number(match[2]) * 60_000
+        + Number(match[3] ?? 0) * 1_000;
+    return { value: `${date} ${clock}`, timestamp: withClock };
+}
+function expectedDelivery(value) {
+    const raw = clean(value, 32);
+    const french = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(raw);
+    const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+    const date = french
+        ? `${french[3]}-${french[2]}-${french[1]}`
+        : iso
+            ? raw
+            : '';
+    return date && dateTimestamp(date) !== null ? date : null;
+}
+function parseEvents(content) {
+    if (!Array.isArray(content.listJoursSuivis))
+        return [];
+    const parsed = [];
+    const seen = new Set();
+    let index = 0;
+    for (const rawDay of content.listJoursSuivis) {
+        if (!isRecord(rawDay) || !Array.isArray(rawDay.suivis))
+            continue;
+        for (const rawEvent of rawDay.suivis) {
+            const currentIndex = index++;
+            if (!isRecord(rawEvent))
+                continue;
+            const time = eventTime(rawDay.dateSuivi, rawEvent.heureSuivi);
+            const description = clean(rawEvent.libelleSuivi);
+            if (!time || !description)
+                continue;
+            const location = clean(rawEvent.libelleCentre, 160);
+            const identity = JSON.stringify([time.value, location, description]);
+            if (seen.has(identity))
+                continue;
+            seen.add(identity);
+            const classified = classifyStatus(description);
+            parsed.push({
+                event: {
+                    time: time.value,
+                    location,
+                    description,
+                    // Unmapped wording carries no stage: the sync classifies and records it.
+                    ...(classified.stage ? { stage: classified.stage } : {}),
+                },
+                status: classified.status,
+                timestamp: time.timestamp,
+                index: currentIndex,
+            });
+        }
+    }
+    parsed.sort((left, right) => right.timestamp - left.timestamp || left.index - right.index);
+    return parsed.slice(0, MAX_EVENTS_TO_RETURN);
+}
+function activeTimelineLabel(content) {
+    if (!isRecord(content.timeline) || !Array.isArray(content.timeline.listTimesteps))
+        return '';
+    for (const rawStep of content.timeline.listTimesteps) {
+        if (isRecord(rawStep) && rawStep.actif === true)
+            return clean(rawStep.libelle);
+    }
+    return '';
+}
+/**
+ * Kept as a named class because the grouped live suite matches on its name. It
+ * is a plain `NotFoundError`.
+ */
+export class GeodisTrackingError extends NotFoundError {
+    constructor() {
+        super(PROVIDER);
+        this.name = 'GeodisTrackingError';
+    }
+}
+function isNotFoundCode(value) {
+    const code = comparableText(clean(value, 100));
+    return includesAny(code, ['envoi non trouve', 'shipment not found', 'tracking not found']);
+}
+export function normalizeGeodisTrackingNumber(raw) {
+    const trackingNumber = raw.trim().toLocaleUpperCase('en-US');
+    if (!/^1G[A-Z0-9]{10}$/.test(trackingNumber)) {
+        throw new TypeError('GEODIS tracking numbers must start with 1G and contain 12 letters and digits');
+    }
+    return trackingNumber;
+}
+export function geodisTrackingUrl() {
+    return TRACKING_ENDPOINT;
+}
+export function geodisRequestBody(rawTrackingNumber) {
+    return JSON.stringify({ noSuivi: normalizeGeodisTrackingNumber(rawTrackingNumber) });
+}
+export function geodisServiceHeader(rawTrackingNumber, timestamp, language = LANGUAGE) {
+    const trackingNumber = normalizeGeodisTrackingNumber(rawTrackingNumber);
+    if (!Number.isSafeInteger(timestamp) || timestamp <= 0) {
+        throw new TypeError('GEODIS signature timestamp must be a positive integer');
+    }
+    if (!/^[a-z]{2}$/.test(language))
+        throw new TypeError('GEODIS signature language is invalid');
+    const body = geodisRequestBody(trackingNumber);
+    const material = [
+        PUBLIC_SPA_APP_KEY,
+        PUBLIC_SPA_APP_ID,
+        String(timestamp),
+        language,
+        SIGNED_API_PATH,
+        body,
+    ].join(';');
+    const digest = createHash('sha256').update(material).digest('hex');
+    return [PUBLIC_SPA_APP_ID, String(timestamp), language, digest].join(';');
+}
+export function parseGeodisTrackingResponse(payload, rawTrackingNumber) {
+    const trackingNumber = normalizeGeodisTrackingNumber(rawTrackingNumber);
+    if (!isRecord(payload) || typeof payload.ok !== 'boolean') {
+        throw new SchemaError(PROVIDER, 'GEODIS returned an invalid tracking response');
+    }
+    if (!payload.ok) {
+        if (isNotFoundCode(payload.codeErreur))
+            throw new GeodisTrackingError();
+        // A rejection we cannot read proves nothing about the shipment.
+        throw new IndeterminateError(PROVIDER, 'GEODIS tracking is unavailable');
+    }
+    if (!isRecord(payload.contenu)) {
+        throw new SchemaError(PROVIDER, 'GEODIS returned incomplete tracking details');
+    }
+    const content = payload.contenu;
+    const responseNumber = clean(content.noSuivi, 32).toLocaleUpperCase('en-US');
+    if (!/^1G[A-Z0-9]{10}$/.test(responseNumber)) {
+        throw new SchemaError(PROVIDER, 'GEODIS returned an invalid shipment number');
+    }
+    if (responseNumber !== trackingNumber) {
+        throw new SchemaError(PROVIDER, 'GEODIS returned a different shipment');
+    }
+    const parsedEvents = parseEvents(content);
+    const events = parsedEvents.map(({ event }) => event);
+    const timelineLabel = activeTimelineLabel(content);
+    const latestDescription = events[0]?.description ?? '';
+    const currentDescription = timelineLabel || latestDescription || 'Tracking information received';
+    const current = classifyStatus(currentDescription);
+    const latestKnown = parsedEvents.find((event) => event.status !== 'unknown')?.status ?? 'unknown';
+    let status = current.status !== 'unknown' ? current.status : latestKnown;
+    if (content.etatLivre === true || content.etatRetire === true)
+        status = 'delivered';
+    else if (content.finDeVie === true && status !== 'delivered')
+        status = 'exception';
+    const isFinal = content.etatLivre === true
+        || content.etatRetire === true
+        || content.finDeVie === true;
+    return {
+        status,
+        last_status_text: currentDescription,
+        last_update: events[0]?.time ?? null,
+        expected_delivery: isFinal
+            ? null
+            : expectedDelivery(content.dateLivraisonPrevue)
+                ?? expectedDelivery(content.dateLivraisonSouhaitee),
+        timezone: TIMEZONE,
+        events,
+    };
+}
+export class GeodisTracker {
+    timeoutMs;
+    #fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('GEODIS timeout must be positive');
+        }
+        this.#fetcher = options.fetcher;
+    }
+    async fetch(rawTrackingNumber) {
+        const trackingNumber = normalizeGeodisTrackingNumber(rawTrackingNumber);
+        const body = geodisRequestBody(trackingNumber);
+        const timestamp = Date.now();
+        const { bytes } = await fetchBounded(geodisTrackingUrl(), {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Accept-Language': 'fr-FR,fr;q=0.9',
+                'Content-Type': 'application/json',
+                Origin: 'https://espace-client.geodis.com',
+                Referer: TRACKING_PAGE,
+                'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+                'X-GEODIS-Service': geodisServiceHeader(trackingNumber, timestamp),
+            },
+            body,
+        }, {
+            provider: 'GEODIS tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            fetcher: this.#fetcher,
+        });
+        return parseGeodisTrackingResponse(parseJsonBytes(bytes, PROVIDER), trackingNumber);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new GeodisTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'geodis',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

package/dist/carriers/geodis/carrier.json

@@ -0,0 +1,75 @@
+{
+  "id": "geodis",
+  "displayName": "GEODIS",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#00549f"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "geodis",
+    "steps": [
+      "direct"
+    ]
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta"
+  ],
+  "portal": {
+    "url": "https://espace-client.geodis.com/services/destinataires/#/fr/suivi/{trackingNumber}",
+    "canaryUrl": "https://espace-client.geodis.com/services/destinataires/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "delivery_instructions",
+      "proof_of_delivery"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "delivery_instructions",
+      "proof_of_delivery"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "espace-client.geodis.com",
+        "geodis.com"
+      ],
+      "params": [
+        "noSuivi",
+        "trackingNumber"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "geodis-1",
+      "pattern": "^1G[A-Z0-9]{10}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/geodis/numbers.json

@@ -0,0 +1,45 @@
+{
+  "carrier": "geodis",
+  "records": [
+    {
+      "number": "1G123GEODIS0",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "geodis",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "1G25S92Z3AW7",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a114cf1ee0c53c0f1aec420",
+        "date": "2026-05-23"
+      },
+      "expect": {
+        "carrier": "geodis",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "1GWSKFLSKX4Y",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://suivi-colis.org/espacedestinataire-livraison-geodis/",
+        "date": "2023-08-30"
+      },
+      "expect": {
+        "carrier": "geodis",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

package/dist/carriers/geodis/status.d.ts

@@ -0,0 +1,37 @@
+/**
+ * GEODIS wording classifier.
+ *
+ * The anonymous recipient endpoint returns French sentences (`libelleSuivi` per
+ * scan, `libelle` per timeline step) and no status code, so wording is the only
+ * thing to map. Text is compared with accents, case and punctuation removed.
+ *
+ * Order matters and is the whole point of this file: "va être livré" and "en
+ * cours de livraison" both contain "livré", so the future-delivery and
+ * out-for-delivery groups are checked before the delivered group, and the
+ * delivered group itself is anchored (start of sentence, "a été livré", or a
+ * parcel noun immediately before the participle) instead of a bare substring.
+ * Wording that matches nothing stays unmapped: the adapter emits the scan with
+ * no stage and the sync classifies it.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface ClassifiedStatus {
+    status: CarrierStatus;
+    /** Absent when no rule matched: the sync's classifier decides instead. */
+    stage?: Stage;
+}
+/** Lowercase, strip accents, and reduce anything that is not a letter or digit to one space. */
+export declare function comparableText(value: string): string;
+export declare function includesAny(value: string, phrases: readonly string[]): boolean;
+export declare const RETURNED_PHRASES: readonly ["retour a l expediteur", "retourne a l expediteur", "retour expediteur"];
+export declare const FAILED_ATTEMPT_PHRASES: readonly ["non livre", "impossible de livrer", "echec de livraison", "livraison echouee", "destinataire absent"];
+/** Carrier-reported problems that are neither a missed attempt nor a return. */
+export declare const EXCEPTION_PHRASES: readonly ["incident", "anomalie", "avarie", "endommage", "refuse"];
+export declare const READY_FOR_PICKUP_PHRASES: readonly ["pret a etre retire", "disponible pour retrait", "mis a disposition", "a retirer en agence", "retrait disponible"];
+export declare const OUT_FOR_DELIVERY_PHRASES: readonly ["en cours de livraison", "livraison en cours", "en distribution", "tournee de livraison", "conducteur en route"];
+/** Announcements of a delivery still to come; checked before the delivered rules. */
+export declare const FUTURE_DELIVERY_PHRASES: readonly ["va etre livre", "sera livre", "doit etre livre", "pret a etre livre"];
+export declare const DELIVERED_PHRASES: readonly ["livraison effectuee", "remis au destinataire", "retire par le destinataire"];
+export declare const REGISTERED_PHRASES: readonly ["en attente de recuperation", "en attente de prise en charge", "information transmise", "commande recue", "enregistre"];
+export declare const IN_TRANSIT_PHRASES: readonly ["pris en charge", "acheminement", "en transit", "arrive", "depart", "agence", "centre", "transport"];
+export declare function classifyStatus(description: string): ClassifiedStatus;

package/dist/carriers/geodis/status.js

@@ -0,0 +1,105 @@
+import { clean } from '../../core/transport/index.js';
+/** Lowercase, strip accents, and reduce anything that is not a letter or digit to one space. */
+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 const RETURNED_PHRASES = [
+    'retour a l expediteur',
+    'retourne a l expediteur',
+    'retour expediteur',
+];
+export const FAILED_ATTEMPT_PHRASES = [
+    'non livre',
+    'impossible de livrer',
+    'echec de livraison',
+    'livraison echouee',
+    'destinataire absent',
+];
+/** Carrier-reported problems that are neither a missed attempt nor a return. */
+export const EXCEPTION_PHRASES = [
+    'incident',
+    'anomalie',
+    'avarie',
+    'endommage',
+    'refuse',
+];
+export const READY_FOR_PICKUP_PHRASES = [
+    'pret a etre retire',
+    'disponible pour retrait',
+    'mis a disposition',
+    'a retirer en agence',
+    'retrait disponible',
+];
+export const OUT_FOR_DELIVERY_PHRASES = [
+    'en cours de livraison',
+    'livraison en cours',
+    'en distribution',
+    'tournee de livraison',
+    'conducteur en route',
+];
+/** Announcements of a delivery still to come; checked before the delivered rules. */
+export const FUTURE_DELIVERY_PHRASES = [
+    'va etre livre',
+    'sera livre',
+    'doit etre livre',
+    'pret a etre livre',
+];
+export const DELIVERED_PHRASES = [
+    'livraison effectuee',
+    'remis au destinataire',
+    'retire par le destinataire',
+];
+const DELIVERED_PATTERNS = [
+    /^(?:livre|livree|livres|livrees)\b/,
+    /\b(?:a ete|est) (?:livre|livree|livres|livrees)\b/,
+    /\b(?:colis|courrier|envoi|pli) (?:livre|livree|livres|livrees)\b/,
+];
+export const REGISTERED_PHRASES = [
+    'en attente de recuperation',
+    'en attente de prise en charge',
+    'information transmise',
+    'commande recue',
+    'enregistre',
+];
+export const IN_TRANSIT_PHRASES = [
+    'pris en charge',
+    'acheminement',
+    'en transit',
+    'arrive',
+    'depart',
+    'agence',
+    'centre',
+    'transport',
+];
+export function classifyStatus(description) {
+    const value = comparableText(description);
+    if (includesAny(value, RETURNED_PHRASES))
+        return { status: 'exception', stage: 'returned' };
+    if (includesAny(value, EXCEPTION_PHRASES))
+        return { status: 'exception', stage: 'exception' };
+    if (includesAny(value, FAILED_ATTEMPT_PHRASES))
+        return { status: 'exception', stage: 'failed_attempt' };
+    if (includesAny(value, READY_FOR_PICKUP_PHRASES))
+        return { status: 'out_for_delivery', stage: 'ready_for_pickup' };
+    if (includesAny(value, OUT_FOR_DELIVERY_PHRASES))
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    if (includesAny(value, FUTURE_DELIVERY_PHRASES))
+        return { status: 'in_transit', stage: 'in_transit' };
+    if (DELIVERED_PATTERNS.some((pattern) => pattern.test(value)) || includesAny(value, DELIVERED_PHRASES)) {
+        return { status: 'delivered', stage: 'delivered' };
+    }
+    if (includesAny(value, REGISTERED_PHRASES))
+        return { status: 'pending', stage: 'registered' };
+    if (includesAny(value, IN_TRANSIT_PHRASES))
+        return { status: 'in_transit', stage: 'in_transit' };
+    return { status: 'unknown' };
+}

package/dist/carriers/geodis/statuses.json

@@ -0,0 +1,51 @@
+{
+  "carrier": "geodis",
+  "entries": [
+    { "wording": "retour à l'expéditeur", "language": "fr", "stage": "returned", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Matched as a substring, accents and punctuation removed." },
+    { "wording": "retourné à l'expéditeur", "language": "fr", "stage": "returned", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "retour expéditeur", "language": "fr", "stage": "returned", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "non livré", "language": "fr", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Checked before the delivered rules so the negation wins." },
+    { "wording": "impossible de livrer", "language": "fr", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "échec de livraison", "language": "fr", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "livraison échouée", "language": "fr", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "incident", "language": "fr", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Reclassified to exception 2026-09-12." },
+    { "wording": "anomalie", "language": "fr", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Reclassified to exception 2026-09-12." },
+    { "wording": "avarie", "language": "fr", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Reclassified to exception 2026-09-12." },
+    { "wording": "endommagé", "language": "fr", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Reclassified to exception 2026-09-12." },
+    { "wording": "refusé", "language": "fr", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Reclassified to exception 2026-09-12." },
+    { "wording": "destinataire absent", "language": "fr", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "prêt à être retiré", "language": "fr", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "disponible pour retrait", "language": "fr", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as the active timeline label \"Disponible pour retrait en agence\"." },
+    { "wording": "mis à disposition", "language": "fr", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "à retirer en agence", "language": "fr", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "retrait disponible", "language": "fr", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "en cours de livraison", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Also the active timeline label of a shipment on the round." },
+    { "wording": "livraison en cours", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "en distribution", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "tournée de livraison", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "conducteur en route", "language": "fr", "stage": "out_for_delivery", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "va être livré", "language": "fr", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "An announcement, not a delivery; checked before the delivered rules." },
+    { "wording": "sera livré", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "doit être livré", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "prêt à être livré", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "livré (au début du libellé)", "language": "fr", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Anchored rule: the participle starts the sentence, in any of its four written forms." },
+    { "wording": "a été livré / est livré", "language": "fr", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Anchored rule." },
+    { "wording": "colis / courrier / envoi / pli livré", "language": "fr", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Anchored rule: a parcel noun immediately before the participle." },
+    { "wording": "livraison effectuée", "language": "fr", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "remis au destinataire", "language": "fr", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "retiré par le destinataire", "language": "fr", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "en attente de récupération", "language": "fr", "stage": "registered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "en attente de prise en charge", "language": "fr", "stage": "registered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "information transmise", "language": "fr", "stage": "registered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "commande reçue", "language": "fr", "stage": "registered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "enregistré", "language": "fr", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "First timeline step of the shipment." },
+    { "wording": "pris en charge", "language": "fr", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Seen as \"Envoi pris en charge\"." },
+    { "wording": "acheminement", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "en transit", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "wording": "arrivé", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Broad last-resort rule; only reached when no earlier group matched." },
+    { "wording": "départ", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Broad last-resort rule." },
+    { "wording": "agence", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Broad last-resort rule." },
+    { "wording": "centre", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Broad last-resort rule." },
+    { "wording": "transport", "language": "fr", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Broad last-resort rule." }
+  ]
+}

package/dist/carriers/gls-ch/adapter.d.ts

@@ -0,0 +1,39 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import { NotFoundError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type JsonObject } from '../../core/types.js';
+export { glsSwitzerlandStatus } from './status.js';
+export interface GLSSwitzerlandOptions {
+    timeoutMs?: number;
+    now?: () => number;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+}
+/** Kept as a named class: the German folder narrows on it with `instanceof`. */
+export declare class GLSSwitzerlandTrackingError extends NotFoundError {
+    constructor();
+}
+export declare function normalizeGLSSwitzerlandTrackingNumber(raw: string): string;
+export declare function normalizeGLSSwitzerlandPostcode(raw: string, digits?: 4 | 5 | '4,5'): string;
+export declare function glsSwitzerlandTrackingUrl(rawTrackingNumber: string): string;
+export declare function glsSwitzerlandOverviewApiUrl(rawTrackingNumber: string, millis?: number): string;
+export declare function glsSwitzerlandDetailApiUrl(rawParcelNumber: string, rawPostcode: string, millis?: number, ownerCode?: string, postcodeDigits?: 4 | 5 | '4,5'): string;
+export declare function selectGLSParcel(payload: unknown, rawTrackingNumber: string): JsonObject;
+export declare function parseGLSSwitzerlandTrackingResponse(payload: unknown, rawTrackingNumber: string): CarrierResult;
+export declare class GLSSwitzerlandTracker {
+    #private;
+    readonly timeoutMs: number;
+    readonly now: () => number;
+    constructor(options?: number | GLSSwitzerlandOptions);
+    fetch(rawTrackingNumber: string, rawPostcode?: string): Promise<CarrierResult>;
+    /**
+     * Whether GLS knows a number, from the overview alone: no postcode is sent.
+     * Only a 404 whose body carries GLS's `lastError: E000` is a not-found here;
+     * a 400 or 403 can be a challenge, so it stays a failure.
+     */
+    recognizes(rawTrackingNumber: string): Promise<boolean>;
+    private request;
+}
+/** Keep the verified overview's delivery owner when the postcode detail omits it. */
+export declare function glsDeliveryReference(result: CarrierResult): Partial<CarrierResult>;
+export declare const adapter: AdapterFactory;