universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/gls-ch/adapter.js

@@ -0,0 +1,405 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { InputRequiredError, NotFoundError, SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { cleanScalar, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { classifyDescription, GLS_STATUSES, statusCode } from './status.js';
+// Protocol provenance (inspected 2026-08-30):
+// https://gls-group.eu/EU/en/parcel-tracking
+// https://gls-group.eu/media/gls_group_resources/gls_group_witt002_js.js
+// The current official frontend uses rstt029 for an anonymous overview, then
+// rstt028/<parcel> with the recipient postcode for the detailed event history.
+const TRACKING_PAGE = 'https://gls-group.eu/EU/en/parcel-tracking';
+const TRACKING_API = 'https://gls-group.eu/app/service/open/rest/GROUP/en';
+const PROVIDER = 'GLS Switzerland';
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+export { glsSwitzerlandStatus } from './status.js';
+/** Kept as a named class: the German folder narrows on it with `instanceof`. */
+export class GLSSwitzerlandTrackingError extends NotFoundError {
+    constructor() {
+        super(PROVIDER);
+        this.name = 'GLSSwitzerlandTrackingError';
+    }
+}
+function text(value, maxLength = 500) {
+    return cleanScalar(value, maxLength);
+}
+/** Provider strings can carry markup; render them to text before they are shown. */
+function plainText(value, maxLength = 500) {
+    const raw = text(value, Math.max(maxLength * 10, 5_000));
+    return raw ? text(load(raw).text(), maxLength) : '';
+}
+function isReturnParcel(parcel) {
+    // retourFlag marks an uncollected/returning parcel regardless of heading.
+    for (const key of ['retourFlag', 'returnFlag', 'retour']) {
+        const value = parcel[key];
+        if (value === true || text(value, 8).toLocaleLowerCase('en-US') === 'true')
+            return true;
+    }
+    return false;
+}
+export function normalizeGLSSwitzerlandTrackingNumber(raw) {
+    const value = raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+    if (!/^(?:(?=[A-Z0-9]{8}$)(?=.*[A-Z])(?=.*\d)[A-Z0-9]{8}|\d{11,14})$/.test(value)) {
+        throw new InputRequiredError('GLS', 'an 8-character Track ID or an 11-to-14-digit parcel number', 'GLS tracking requires an 8-character Track ID or an 11-to-14-digit parcel number');
+    }
+    return value;
+}
+export function normalizeGLSSwitzerlandPostcode(raw, digits = 4) {
+    const value = raw.trim();
+    if (!new RegExp(`^\\d{${digits}}$`).test(value)) {
+        const shape = `${digits === '4,5' ? '4- or 5' : digits}-digit recipient postcode`;
+        throw new InputRequiredError('GLS', `the ${shape}`, `GLS detailed tracking requires the ${shape}`);
+    }
+    return value;
+}
+export function glsSwitzerlandTrackingUrl(rawTrackingNumber) {
+    const url = new URL(TRACKING_PAGE);
+    url.searchParams.set('match', normalizeGLSSwitzerlandTrackingNumber(rawTrackingNumber));
+    return url.toString();
+}
+export function glsSwitzerlandOverviewApiUrl(rawTrackingNumber, millis = Date.now()) {
+    const url = new URL(`${TRACKING_API}/rstt029`);
+    url.searchParams.set('match', normalizeGLSSwitzerlandTrackingNumber(rawTrackingNumber));
+    url.searchParams.set('type', '');
+    url.searchParams.set('caller', 'witt002');
+    url.searchParams.set('millis', String(millis));
+    return url.toString();
+}
+export function glsSwitzerlandDetailApiUrl(rawParcelNumber, rawPostcode, millis = Date.now(), ownerCode = '', postcodeDigits = 4) {
+    const parcelNumber = normalizeGLSSwitzerlandTrackingNumber(rawParcelNumber);
+    if (!/^\d{11,14}$/.test(parcelNumber)) {
+        throw new InputRequiredError('GLS', 'the numeric parcel number', 'GLS details require the numeric parcel number');
+    }
+    const url = new URL(`${TRACKING_API}/rstt028/${encodeURIComponent(parcelNumber)}`);
+    url.searchParams.set('caller', 'witt002');
+    url.searchParams.set('millis', String(millis));
+    url.searchParams.set('postalCode', normalizeGLSSwitzerlandPostcode(rawPostcode, postcodeDigits));
+    const owner = text(ownerCode, 32);
+    if (owner && /^[A-Z0-9_-]+$/i.test(owner))
+        url.searchParams.set('tuOwnerCode', owner);
+    return url.toString();
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function normalizedResponseIdentifier(value) {
+    try {
+        return normalizeGLSSwitzerlandTrackingNumber(text(value, 32));
+    }
+    catch {
+        return '';
+    }
+}
+function referenceIdentifiers(parcel) {
+    return records(parcel.references)
+        .filter((reference) => ['TRACKID', 'TRACK ID', 'PARCELNUMBER', 'TU'].includes(`${text(reference.type, 32)} ${text(reference.name, 32)}`.trim().toLocaleUpperCase('en-US')) || /track|parcel|paket/i.test(`${text(reference.type)} ${text(reference.name)}`))
+        .map((reference) => normalizedResponseIdentifier(reference.value))
+        .filter(Boolean);
+}
+function responseIdentifiers(parcel) {
+    return [
+        normalizedResponseIdentifier(parcel.tuNo),
+        normalizedResponseIdentifier(parcel.trackId),
+        normalizedResponseIdentifier(parcel.trackingId),
+        ...referenceIdentifiers(parcel),
+    ].filter(Boolean);
+}
+function parcelRows(payload) {
+    if (!isRecord(payload))
+        throw new SchemaError(PROVIDER, 'GLS returned an invalid tracking response');
+    if (Array.isArray(payload.tuStatus))
+        return records(payload.tuStatus);
+    if (payload.tuNo)
+        return [payload];
+    throw new SchemaError(PROVIDER, 'GLS did not return tracking details');
+}
+export function selectGLSParcel(payload, rawTrackingNumber) {
+    const trackingNumber = normalizeGLSSwitzerlandTrackingNumber(rawTrackingNumber);
+    const parcels = parcelRows(payload);
+    if (parcels.length === 0)
+        throw new GLSSwitzerlandTrackingError();
+    // GLS accepts an 11-digit parcel ID or its 12-digit printed form. Its
+    // recipient API can return the first 11 digits for the latter (ShipIT docs:
+    // https://gls-shipit.gls-group.eu/webservices/5_0_15/doxygen/WS-REST-API/rest_tracking.html).
+    // Bind that alias to the exact prefix; never accept an unrelated numeric ID.
+    const matching = parcels.filter((parcel) => responseIdentifiers(parcel).some((identifier) => (identifier === trackingNumber
+        || (/^\d{12}$/.test(trackingNumber) && /^\d{11}$/.test(identifier)
+            && trackingNumber.slice(0, 11) === identifier))));
+    if (matching.length === 1)
+        return matching[0];
+    // An eight-character Track ID is translated by the overview endpoint to its
+    // numeric parcel number and is not echoed. A single result is unambiguous.
+    if (/^[A-Z0-9]{8}$/.test(trackingNumber) && parcels.length === 1)
+        return parcels[0];
+    if (matching.length > 1)
+        throw new SchemaError(PROVIDER, 'GLS returned an ambiguous shipment');
+    throw new SchemaError(PROVIDER, 'GLS returned a different shipment');
+}
+/**
+ * Local time policy: the service splits a scan into a `date` and a `time`
+ * field, neither carrying an offset, in a list of formats that includes
+ * `dd-MMM-yyyy`. They are wall-clock values at the scan facility and are read
+ * in Europe/Zurich; the German folder relabels the result's timezone only.
+ */
+function parseEventTime(dateValue, timeValue) {
+    const date = text(dateValue, 64);
+    const time = text(timeValue, 32);
+    const joined = `${date} ${time}`.trim();
+    if (!joined)
+        return null;
+    let parsed = DateTime.fromISO(joined, { zone: 'Europe/Zurich' });
+    if (!parsed.isValid) {
+        for (const format of [
+            'yyyy-MM-dd HH:mm:ss',
+            'yyyy-MM-dd HH:mm',
+            'dd-MMM-yyyy HH:mm:ss',
+            'dd-MMM-yyyy HH:mm',
+            'dd/MM/yyyy HH:mm',
+            'dd.MM.yyyy HH:mm',
+            'dd/MM/yyyy',
+            'dd.MM.yyyy',
+        ]) {
+            parsed = DateTime.fromFormat(joined, format, { zone: 'Europe/Zurich', locale: 'en' });
+            if (parsed.isValid)
+                break;
+        }
+    }
+    const iso = parsed.toISO({ suppressMilliseconds: true });
+    return parsed.isValid && iso ? { iso, timestamp: parsed.toMillis() } : null;
+}
+function eventLocation(raw) {
+    if (!isRecord(raw.address))
+        return '';
+    // Retain coarse operational scan locations (city/country) plus the
+    // ParcelShop/locker name when the provider supplies it. Street, postcode
+    // and recipient contact fields in the same object are still dropped.
+    const shop = text(raw.address.parcelShopName ?? raw.address.shopName ?? raw.parcelShop, 200);
+    return [shop, plainText(raw.address.countryName, 80), plainText(raw.address.city, 120)]
+        .filter(Boolean)
+        .join(' ')
+        .slice(0, 200);
+}
+function parcelShopName(parcel) {
+    for (const event of records(parcel.history)) {
+        const name = eventLocation(event);
+        if (/parcel.?shop|locker|point relais|paketshop/i.test(name) && name)
+            return name.slice(0, 200);
+    }
+    return null;
+}
+function parcelWeight(parcel) {
+    for (const info of records(parcel.infos)) {
+        const label = text(info.label ?? info.name, 32).toLocaleLowerCase('en-US');
+        const value = text(info.value ?? info.text, 32);
+        if (!/weight|poids|gewicht/.test(label))
+            continue;
+        const match = /([\d.,]+)\s*kg/i.exec(value);
+        if (match) {
+            const parsed = Number(match[1].replace(',', '.'));
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
+    }
+    return null;
+}
+function parseEvents(parcel) {
+    const parsed = [];
+    const seen = new Set();
+    records(parcel.history).slice(0, MAX_EVENTS_TO_INSPECT).forEach((raw, sourceIndex) => {
+        const description = plainText(raw.evtDscr) || plainText(raw.description);
+        const time = parseEventTime(raw.date, raw.time);
+        if (!description || !time)
+            return;
+        const location = eventLocation(raw);
+        const code = text(raw.evtNo ?? raw.code, 32);
+        const identity = JSON.stringify([time.iso, location, description, code]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        const classified = GLS_STATUSES.get(statusCode(raw.status)) ?? classifyDescription(description);
+        parsed.push({
+            sourceIndex,
+            timestamp: time.timestamp,
+            status: classified.status,
+            event: {
+                time: time.iso,
+                location,
+                description,
+                stage: classified.stage,
+                ...(/^[A-Z0-9._-]{1,32}$/i.test(code) ? { provider_code: code } : {}),
+            },
+        });
+    });
+    parsed.sort((left, right) => (right.timestamp - left.timestamp || left.sourceIndex - right.sourceIndex));
+    return parsed.slice(0, MAX_EVENTS_TO_RETURN);
+}
+function expectedDelivery(parcel) {
+    if (!isRecord(parcel.arrivalTime))
+        return null;
+    const value = plainText(parcel.arrivalTime.value, 128);
+    const match = value.match(/\b(\d{1,2}[-/.][A-Za-z]{3}|\d{1,2}[-/.]\d{1,2})[-/.](\d{4})\b/);
+    if (!match)
+        return null;
+    const raw = match[0];
+    for (const format of ['d-MMM-yyyy', 'd/MM/yyyy', 'd.MM.yyyy']) {
+        const parsed = DateTime.fromFormat(raw, format, { zone: 'Europe/Zurich', locale: 'en' });
+        if (parsed.isValid)
+            return parsed.toISODate();
+    }
+    return null;
+}
+export function parseGLSSwitzerlandTrackingResponse(payload, rawTrackingNumber) {
+    const parcel = selectGLSParcel(payload, rawTrackingNumber);
+    if (!isRecord(parcel.progressBar)) {
+        throw new SchemaError(PROVIDER, 'GLS did not return a shipment status');
+    }
+    const progress = parcel.progressBar;
+    const current = records(progress.statusBar).find((entry) => (statusCode(entry.imageStatus) === 'CURRENT'));
+    const currentCode = statusCode(progress.statusInfo) || statusCode(current?.status);
+    const currentMetadata = GLS_STATUSES.get(currentCode);
+    const currentText = plainText(current?.statusText)
+        || plainText(progress.statusText)
+        || plainText(current?.imageText)
+        || 'Tracking information received';
+    const parsedEvents = parseEvents(parcel);
+    const events = parsedEvents.map(({ event }) => event);
+    const latestKnownEvent = parsedEvents.find((event) => event.status !== 'unknown');
+    // Newest history wording outranks a stale progress-bar heading (locker
+    // drops stick at "Delivered" upstream); the event description is the raw
+    // status. A returning parcel overrides any in-transit heading.
+    const newestDescription = events[0]?.description ?? currentText;
+    const status = isReturnParcel(parcel)
+        ? 'exception'
+        : currentMetadata?.status ?? latestKnownEvent?.status ?? 'unknown';
+    const stage = isReturnParcel(parcel)
+        ? 'returned'
+        : currentMetadata?.stage ?? latestKnownEvent?.event.stage ?? 'in_transit';
+    const shop = parcelShopName(parcel);
+    const weight = parcelWeight(parcel);
+    const pickup = stage === 'ready_for_pickup' && shop ? { pickup_point: shop } : {};
+    return {
+        status,
+        canonical_tracking_number: normalizedResponseIdentifier(parcel.tuNo),
+        ...(records(parcel.owners).some((owner) => statusCode(owner.type) === 'DELIVERY' && statusCode(owner.code) === 'CH01')
+            ? { delivery_carrier: 'swiss-post', delivery_tracking_number: normalizedResponseIdentifier(parcel.tuNo) } : {}),
+        current_stage: stage,
+        last_status_text: newestDescription,
+        last_update: events[0]?.time ?? null,
+        expected_delivery: ['delivered', 'exception'].includes(status)
+            ? null
+            : expectedDelivery(parcel),
+        timezone: 'Europe/Zurich',
+        ...pickup,
+        ...(weight != null ? { weight_kg: weight } : {}),
+        ...(status === 'delivered' && events[0]?.time ? { delivered_at: events[0].time } : {}),
+        events,
+    };
+}
+function ownerCode(parcel) {
+    return records(parcel.owners).reduce((found, owner) => (found || (statusCode(owner.type) === 'REQUEST' ? text(owner.code, 32) : '')), '');
+}
+function pageHeaders() {
+    return {
+        Accept: 'application/json',
+        'Accept-Language': 'en-CH,en;q=0.9',
+        Origin: 'https://gls-group.eu',
+        Referer: `${TRACKING_PAGE}/`,
+        'User-Agent': 'Mozilla/5.0 (compatible; DeliveryTracker/1.0)',
+    };
+}
+export class GLSSwitzerlandTracker {
+    timeoutMs;
+    now;
+    #fetcher;
+    constructor(options = {}) {
+        const { timeoutMs = DEFAULT_TIMEOUT_MS, now = Date.now, fetcher } = typeof options === 'number'
+            ? { timeoutMs: options, now: Date.now, fetcher: undefined }
+            : options;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new TypeError('GLS Switzerland timeout must be positive');
+        }
+        this.timeoutMs = timeoutMs;
+        this.now = now;
+        this.#fetcher = fetcher;
+    }
+    async fetch(rawTrackingNumber, rawPostcode = '') {
+        const trackingNumber = normalizeGLSSwitzerlandTrackingNumber(rawTrackingNumber);
+        const overview = await this.request(glsSwitzerlandOverviewApiUrl(trackingNumber, this.now()));
+        const parcel = selectGLSParcel(overview, trackingNumber);
+        if (!rawPostcode.trim())
+            return parseGLSSwitzerlandTrackingResponse(overview, trackingNumber);
+        const parcelNumber = normalizedResponseIdentifier(parcel.tuNo);
+        if (!/^\d{11,14}$/.test(parcelNumber)) {
+            throw new SchemaError(PROVIDER, 'GLS did not return a numeric parcel number');
+        }
+        const detail = await this.request(glsSwitzerlandDetailApiUrl(parcelNumber, rawPostcode, this.now(), ownerCode(parcel)));
+        const result = parseGLSSwitzerlandTrackingResponse(detail, parcelNumber);
+        const overviewResult = parseGLSSwitzerlandTrackingResponse(overview, trackingNumber);
+        return { ...result, ...glsDeliveryReference(overviewResult) };
+    }
+    /**
+     * 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.
+     */
+    async recognizes(rawTrackingNumber) {
+        const trackingNumber = normalizeGLSSwitzerlandTrackingNumber(rawTrackingNumber);
+        const { response, bytes } = await fetchBounded(glsSwitzerlandOverviewApiUrl(trackingNumber, this.now()), {
+            headers: pageHeaders(),
+        }, {
+            provider: 'GLS Switzerland tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            allowHttpError: true,
+            ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
+        });
+        if (response.status === 404) {
+            const payload = parseJsonBytes(bytes, PROVIDER);
+            if (isRecord(payload) && payload.lastError === 'E000')
+                return false;
+        }
+        if (!response.ok)
+            throw new UpstreamHttpError('GLS Switzerland tracking', response.status);
+        try {
+            return parseGLSSwitzerlandTrackingResponse(parseJsonBytes(bytes, PROVIDER), trackingNumber).status !== 'unknown';
+        }
+        catch (error) {
+            if (error instanceof GLSSwitzerlandTrackingError)
+                return false;
+            throw error;
+        }
+    }
+    async request(url) {
+        const { response, bytes } = await fetchBounded(url, {
+            headers: pageHeaders(),
+        }, {
+            provider: 'GLS Switzerland tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            allowHttpError: true,
+            ...(this.#fetcher ? { fetcher: this.#fetcher } : {}),
+        });
+        if ([400, 403, 404].includes(response.status))
+            throw new GLSSwitzerlandTrackingError();
+        if (!response.ok)
+            throw new UpstreamHttpError('GLS Switzerland tracking', response.status);
+        return parseJsonBytes(bytes, PROVIDER);
+    }
+}
+/** Keep the verified overview's delivery owner when the postcode detail omits it. */
+export function glsDeliveryReference(result) {
+    return result.delivery_carrier ? { delivery_carrier: result.delivery_carrier, delivery_tracking_number: result.delivery_tracking_number } : {};
+}
+export const adapter = (environment) => {
+    const tracker = new GLSSwitzerlandTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'gls-ch',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number, input.postcode ?? ''),
+        recognize: async (number) => ({ known: await tracker.recognizes(number) }),
+    };
+};

package/dist/carriers/gls-ch/carrier.json

@@ -0,0 +1,122 @@
+{
+  "id": "gls-ch",
+  "displayName": "GLS Switzerland",
+  "aliases": [
+    "General Logistics Systems",
+    "GLS Group"
+  ],
+  "region": {
+    "countries": [
+      "CH",
+      "LI"
+    ]
+  },
+  "brand": {
+    "color": "#ffdd00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Zurich",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "gls-ch",
+    "requirements": [
+      {
+        "field": "dpdPostcode",
+        "validator": "swissPostcode",
+        "label": "Delivery postcode",
+        "type": "text",
+        "placeholder": "8000",
+        "help": "GLS uses the recipient postcode to unlock the detailed event history.",
+        "pattern": "^[0-9]{4}$",
+        "maxLength": 4,
+        "inputMode": "numeric",
+        "autoComplete": "postal-code"
+      }
+    ],
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 60
+    },
+    "refresh": {
+      "minMinutes": 60,
+      "afterFailureMinutes": 240
+    }
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "pickup_point",
+    "weight",
+    "delivered_at",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://gls-group.eu/EU/en/parcel-tracking?match={trackingNumber}",
+    "canaryUrl": "https://gls-group.eu/EU/en/parcel-tracking",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "pickup_point",
+      "weight",
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "signature",
+      "customer_reference"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "pickup_point",
+      "weight",
+      "delivered_at",
+      "provider_code"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "signature",
+      "customer_reference"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "gls-group.eu"
+      ],
+      "params": [
+        "match",
+        "parcelNumber",
+        "matchParcelNumber"
+      ],
+      "pathPattern": "^/(?:EU|CH)/"
+    }
+  ],
+  "detection": [
+    {
+      "id": "gls-ch-1",
+      "pattern": "^(?=[A-Z0-9]{8}$)(?=.*[A-Z])(?=.*\\d)[A-Z0-9]{8}$",
+      "confidence": "low"
+    },
+    {
+      "id": "gls-ch-2",
+      "pattern": "^\\d{11}$",
+      "confidence": "low"
+    },
+    {
+      "id": "gls-ch-3",
+      "pattern": "^\\d{12}$",
+      "confidence": "low",
+      "checksum": "gls"
+    }
+  ]
+}

package/dist/carriers/gls-ch/numbers.json

@@ -0,0 +1,31 @@
+{
+  "carrier": "gls-ch",
+  "records": [
+    {
+      "number": "993990103198",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-10",
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "fedex",
+          "gls-ch",
+          "mondial-relay",
+          "gls-fr",
+          "colis-prive",
+          "gls-de",
+          "mrw",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Made-up number that follows the published format. Filed under GLS Switzerland, which stays one candidate among several."
+    }
+  ]
+}

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

@@ -0,0 +1,19 @@
+/**
+ * GLS status classification, shared by the Swiss and German folders.
+ *
+ * The GROUP recipient service labels the progress bar and most history rows
+ * with a stable status code (`INTRANSIT`, `DELIVEREDPS`, …). Codes are the
+ * authority. Rows that carry no code fall back to wording rules, which are
+ * ordered so that negatives and explicit non-events are decided before the
+ * broad words they contain, and only then consult the package's shared
+ * multilingual classifier.
+ */
+import { type ClassifiedStatus } from '../../core/status/index.js';
+export type { ClassifiedStatus };
+export declare const GLS_STATUSES: Map<string, ClassifiedStatus>;
+/** A provider status code, upper-cased, or '' when the value is not one. */
+export declare function statusCode(value: unknown): string;
+/** The shipment status for a raw GLS status code; unknown codes stay `unknown`. */
+export declare function glsSwitzerlandStatus(value: unknown): ClassifiedStatus['status'];
+/** Classify a history row that carries no status code, from its wording alone. */
+export declare function classifyDescription(description: string): ClassifiedStatus;

package/dist/carriers/gls-ch/status.js

@@ -0,0 +1,79 @@
+/**
+ * GLS status classification, shared by the Swiss and German folders.
+ *
+ * The GROUP recipient service labels the progress bar and most history rows
+ * with a stable status code (`INTRANSIT`, `DELIVEREDPS`, …). Codes are the
+ * authority. Rows that carry no code fall back to wording rules, which are
+ * ordered so that negatives and explicit non-events are decided before the
+ * broad words they contain, and only then consult the package's shared
+ * multilingual classifier.
+ */
+import { languageStageStatus, trackingLanguageStage } from '../../core/status/index.js';
+export const GLS_STATUSES = new Map([
+    ['PREADVICE', { status: 'pending', stage: 'registered' }],
+    ['NOTPICKEDUP', { status: 'exception', stage: 'returned' }],
+    ['PLANNEDPICKUP', { status: 'pending', stage: 'registered' }],
+    ['INPICKUP', { status: 'in_transit', stage: 'accepted' }],
+    ['INTRANSIT', { status: 'in_transit', stage: 'in_transit' }],
+    ['INWAREHOUSE', { status: 'in_transit', stage: 'in_transit' }],
+    ['INDELIVERY', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['DELIVERED', { status: 'delivered', stage: 'delivered' }],
+    // ParcelShop/locker arrival — arrived, not recipient-delivered.
+    ['DELIVEREDPS', { status: 'out_for_delivery', stage: 'ready_for_pickup' }],
+    ['NOTDELIVERED', { status: 'exception', stage: 'failed_attempt' }],
+    ['RETURNED', { status: 'exception', stage: 'returned' }],
+    ['CANCELED', { status: 'exception', stage: 'returned' }],
+    ['CANCELLED', { status: 'exception', stage: 'returned' }],
+    ['FINAL', { status: 'exception', stage: 'returned' }],
+    ['NORECORD', { status: 'unknown', stage: 'pending' }],
+]);
+/** A provider status code, upper-cased, or '' when the value is not one. */
+export function statusCode(value) {
+    const code = (typeof value === 'string' || typeof value === 'number'
+        ? String(value).replace(/\s+/g, ' ').trim().slice(0, 32)
+        : '').toLocaleUpperCase('en-US');
+    return /^[A-Z][A-Z0-9_]{1,31}$/.test(code) ? code : '';
+}
+/** The shipment status for a raw GLS status code; unknown codes stay `unknown`. */
+export function glsSwitzerlandStatus(value) {
+    return GLS_STATUSES.get(statusCode(value))?.status ?? 'unknown';
+}
+/** Classify a history row that carries no status code, from its wording alone. */
+export function classifyDescription(description) {
+    // EXISTING regression wording: a negative handoff does not prove GLS possession.
+    if (/^(?:the )?parcel has not been handed over to gls[.!]?$/i.test(description.trim())) {
+        return { status: 'unknown', stage: 'in_transit' };
+    }
+    const translated = trackingLanguageStage(description);
+    if (translated)
+        return { status: languageStageStatus(translated), stage: translated };
+    const value = description
+        .toLocaleLowerCase('en-US')
+        .replace(/[^a-z0-9]+/g, ' ')
+        .trim();
+    if (/(return(?:ed)? to sender|cancel(?:led|ed)|delivery (?:failed|impossible)|not delivered)/.test(value)) {
+        return { status: 'exception', stage: value.includes('return') ? 'returned' : 'failed_attempt' };
+    }
+    if (/(delivered|handed to (?:the )?recipient|collected by (?:the )?recipient)/.test(value)) {
+        return { status: 'delivered', stage: 'delivered' };
+    }
+    if (/(ready for (?:pickup|collection)|parcel ?shop|locker)/.test(value)) {
+        return { status: 'out_for_delivery', stage: 'ready_for_pickup' };
+    }
+    if (/(out for delivery|in delivery|delivery vehicle)/.test(value)) {
+        return { status: 'out_for_delivery', stage: 'out_for_delivery' };
+    }
+    if (/(data (?:was )?entered|preadvice|announced|label created)/.test(value)) {
+        return { status: 'pending', stage: 'registered' };
+    }
+    if (/^(?:the )?parcel (?:was|has been) handed over to gls$/.test(value)) {
+        return { status: 'in_transit', stage: 'accepted' };
+    }
+    if (/^(?:the )?parcel (?:was|has been) released by customs$/.test(value)) {
+        return { status: 'in_transit', stage: 'in_transit' };
+    }
+    if (/(transit|parcel cent(?:er|re)|depot|left the gls|reached gls|customs)/.test(value)) {
+        return { status: 'in_transit', stage: value.includes('customs') ? 'customs' : 'in_transit' };
+    }
+    return { status: 'unknown', stage: 'in_transit' };
+}