universal-parcel-scraper 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,220 @@
+/**
+ * GLS France: the public consignee endpoint called by moncolis.gls-france.com.
+ *
+ * One bounded GET per lookup ('direct' step). The response carries the parcel
+ * record, its event list, and blocks describing the people involved; `parse()`
+ * builds its result from an explicit allowlist of status, timing and
+ * operational-location fields, so recipient names, street addresses, contacts,
+ * signatures and delivery instructions never leave this module.
+ */
+import { DateTime } from 'luxon';
+import { isValidGlsParcelNumber } from '../../core/detection/index.js';
+import { SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { EXPLICIT_OFFSET_PATTERN } from '../../core/time/index.js';
+import { cleanScalar, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { FAILED_DELAYED_DELIVERY, glsFranceStatusCode, glsFranceStatusMetadata, } from './status.js';
+export { glsFranceStatus } from './status.js';
+const PROVIDER = 'GLS France';
+const TRACKING_API = 'https://public.infra-prod.prod.cloud.fr.gls-group.com/consignee-ws/api/v1/command/public/codes';
+const TRACKING_PAGE = 'https://moncolis.gls-france.com/fr';
+const TIMEZONE = 'Europe/Paris';
+const DEFAULT_TIMEOUT_MS = 12_000;
+const MAX_RESPONSE_BYTES = 750_000;
+const MAX_EVENTS_TO_INSPECT = 500;
+const MAX_EVENTS_TO_RETURN = 100;
+function locationCode(value) {
+    const code = cleanScalar(value, 16).toLocaleUpperCase('en-US');
+    return /^[A-Z]{2}[A-Z0-9]{2,8}$/.test(code) ? code : '';
+}
+/**
+ * GLS France puts three shapes on the same timestamp fields: an ISO value with
+ * or without an offset, a SQL-style `YYYY-MM-DD HH:mm:ss.S` wall clock, and a
+ * bare calendar day. No single `core/time` policy covers all three, so this
+ * helper stays local: an explicit offset is honored, everything else is read in
+ * Europe/Paris, which is the zone the French backend stamps.
+ */
+function parsedTime(value) {
+    const raw = cleanScalar(value, 64);
+    // Empty timestamps arrive padded with year 1 instead of being omitted.
+    if (!raw || raw.startsWith('0001-'))
+        return null;
+    let parsed = raw.includes('T')
+        ? DateTime.fromISO(raw, { setZone: EXPLICIT_OFFSET_PATTERN.test(raw), zone: TIMEZONE })
+        : DateTime.fromSQL(raw, { zone: TIMEZONE });
+    if (!parsed.isValid && /^\d{4}-\d{2}-\d{2}$/.test(raw)) {
+        parsed = DateTime.fromISO(raw, { zone: TIMEZONE });
+    }
+    if (!parsed.isValid)
+        return null;
+    const iso = parsed.toISO({ suppressMilliseconds: true });
+    return iso ? { iso, timestamp: parsed.toMillis() } : null;
+}
+function expectedDelivery(value) {
+    return parsedTime(value)?.iso.slice(0, 10) ?? null;
+}
+/**
+ * A GLS parcel number is 11 digits; labels print it with its check digit as a
+ * 12th. A 12-digit number is accepted only when that digit is valid, and is
+ * known by its first 11 digits.
+ */
+function parcelNumber(value) {
+    if (/^(?:[A-Z0-9]{8}|\d{11})$/.test(value))
+        return value;
+    return isValidGlsParcelNumber(value) ? value.slice(0, 11) : '';
+}
+function normalizedCandidate(value) {
+    return parcelNumber(cleanScalar(value, 32).toLocaleUpperCase('en-US').replace(/[\s.-]/g, ''));
+}
+function printedNumber(raw) {
+    return raw.toLocaleUpperCase('en-US').replace(/[\s.-]/g, '');
+}
+export function normalizeGLSFranceTrackingNumber(raw) {
+    const value = parcelNumber(printedNumber(raw));
+    if (!value) {
+        throw new TypeError('GLS France tracking numbers must contain 8 letters or digits, or 11 digits (12 with a valid check digit)');
+    }
+    return value;
+}
+export function glsFranceTrackingUrl(trackingNumber) {
+    return `${TRACKING_PAGE}/${encodeURIComponent(normalizeGLSFranceTrackingNumber(trackingNumber))}`;
+}
+export function glsFranceTrackingApiUrl(trackingNumber) {
+    return `${TRACKING_API}/${encodeURIComponent(normalizeGLSFranceTrackingNumber(trackingNumber))}`;
+}
+function records(value) {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function responseIdentifiers(parcel) {
+    return [parcel.trackid, parcel.numeroalphaColis, parcel.numeroGp]
+        .map(normalizedCandidate)
+        .filter(Boolean);
+}
+function parseEvent(raw, sourceIndex) {
+    const eventStatusCode = glsFranceStatusCode(raw.statutEvenement);
+    const typeCode = glsFranceStatusCode(raw.typeEvenement);
+    const code = eventStatusCode || typeCode;
+    const metadata = eventStatusCode === 'DEL' && typeCode === 'LIV'
+        ? FAILED_DELAYED_DELIVERY
+        : glsFranceStatusMetadata(code);
+    const time = parsedTime(raw.datereference) ?? parsedTime(raw.datecreation);
+    if (!code && !time)
+        return null;
+    const location = locationCode(raw.codelieuEvenement);
+    return {
+        timestamp: time?.timestamp ?? Number.NEGATIVE_INFINITY,
+        sourceIndex,
+        typeCode,
+        metadata,
+        event: {
+            ...(time ? { time: time.iso } : {}),
+            ...(location ? { location } : {}),
+            description: metadata?.description ?? 'GLS France tracking update',
+            // An unmapped code carries no stage: the sync classifies and records it.
+            ...(metadata ? { stage: metadata.stage } : {}),
+            ...(code ? { provider_code: code } : {}),
+        },
+    };
+}
+export function parseGLSFranceTrackingResponse(payload, trackingNumber) {
+    const requested = normalizeGLSFranceTrackingNumber(trackingNumber);
+    if (!isRecord(payload) || !isRecord(payload.colis)) {
+        throw new SchemaError(PROVIDER, 'GLS France returned an invalid tracking response');
+    }
+    const parcel = payload.colis;
+    const identifiers = responseIdentifiers(parcel);
+    if (identifiers.length === 0) {
+        throw new SchemaError(PROVIDER, 'GLS France did not return a shipment identifier');
+    }
+    if (!identifiers.includes(requested)) {
+        throw new SchemaError(PROVIDER, 'GLS France returned a different shipment');
+    }
+    const seen = new Set();
+    const parsedEvents = [];
+    records(payload.evenements).slice(0, MAX_EVENTS_TO_INSPECT).forEach((raw, index) => {
+        const parsed = parseEvent(raw, index);
+        if (!parsed)
+            return;
+        const identity = JSON.stringify([
+            parsed.event.time ?? '',
+            parsed.event.location ?? '',
+            parsed.event.provider_code ?? '',
+        ]);
+        if (seen.has(identity))
+            return;
+        seen.add(identity);
+        parsedEvents.push(parsed);
+    });
+    parsedEvents.sort((left, right) => (right.timestamp - left.timestamp || left.sourceIndex - right.sourceIndex));
+    const latestParsedEvent = parsedEvents[0];
+    const events = parsedEvents
+        .slice(0, MAX_EVENTS_TO_RETURN)
+        .map(({ event }) => event);
+    const currentCode = glsFranceStatusCode(parcel.statutColis);
+    const current = currentCode === 'DEL' && latestParsedEvent?.typeCode === 'LIV'
+        ? FAILED_DELAYED_DELIVERY
+        : glsFranceStatusMetadata(currentCode);
+    const latestEvent = events[0];
+    const latestEventStatus = latestParsedEvent?.metadata ?? glsFranceStatusMetadata(latestEvent?.provider_code);
+    const fallbackUpdate = parsedTime(parcel.dateActionColis);
+    return {
+        status: current?.status ?? latestEventStatus?.status ?? 'unknown',
+        last_status_text: current?.description
+            ?? latestEvent?.description
+            ?? 'Tracking information received',
+        last_update: latestEvent?.time ?? fallbackUpdate?.iso ?? null,
+        expected_delivery: expectedDelivery(parcel.dateTheoriqueLivraison),
+        timezone: TIMEZONE,
+        events,
+    };
+}
+export class GLSFranceTracker {
+    timeoutMs;
+    #fetcher;
+    constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0) {
+            throw new TypeError('GLS France timeout must be positive');
+        }
+        this.#fetcher = options.fetcher;
+    }
+    async fetch(trackingNumber) {
+        const normalized = normalizeGLSFranceTrackingNumber(trackingNumber);
+        const printed = printedNumber(trackingNumber);
+        try {
+            return await this.lookup(normalized, normalized);
+        }
+        catch (error) {
+            // The 11-digit parcel number is what GLS keys a parcel by. Should the
+            // French backend only know the number as printed, ask for it once too.
+            if (printed === normalized || !(error instanceof UpstreamHttpError) || error.status !== 404)
+                throw error;
+            return await this.lookup(printed, normalized);
+        }
+    }
+    async lookup(code, normalized) {
+        const { bytes } = await fetchBounded(`${TRACKING_API}/${encodeURIComponent(code)}`, {
+            headers: {
+                Accept: 'application/json',
+                'Accept-Language': 'fr-FR,fr;q=0.9',
+                Origin: 'https://moncolis.gls-france.com',
+                Referer: `${TRACKING_PAGE}/`,
+                'User-Agent': 'Mozilla/5.0 (compatible; SwissDeliveryTracker/1.0)',
+            },
+        }, {
+            provider: 'GLS France tracking',
+            timeoutMs: this.timeoutMs,
+            maxBytes: MAX_RESPONSE_BYTES,
+            fetcher: this.#fetcher,
+        });
+        return parseGLSFranceTrackingResponse(parseJsonBytes(bytes, PROVIDER), normalized);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new GLSFranceTracker({ fetcher: environment.fetcher });
+    return {
+        id: 'gls-fr',
+        steps: ['direct'],
+        track: (input) => tracker.fetch(input.number),
+    };
+};

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

@@ -0,0 +1,107 @@
+{
+  "id": "gls-fr",
+  "displayName": "GLS France",
+  "aliases": [
+    "General Logistics Systems France"
+  ],
+  "region": {
+    "countries": [
+      "FR"
+    ]
+  },
+  "brand": {
+    "color": "#ffdd00"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "gls-fr",
+    "steps": [
+      "direct"
+    ],
+    "refresh": {
+      "minMinutes": 60,
+      "afterFailureMinutes": 240
+    }
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://moncolis.gls-france.com/fr/{trackingNumber}",
+    "canaryUrl": "https://moncolis.gls-france.com/fr/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "signature",
+      "delivery_instructions"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "discarded": [
+      "recipient_name",
+      "recipient_address",
+      "recipient_contact",
+      "signature",
+      "delivery_instructions"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "moncolis.gls-france.com",
+        "gls-france.com"
+      ],
+      "path": "^/fr/([^/?#]+)/?$"
+    },
+    {
+      "domains": [
+        "gls-group.com",
+        "gls-group.eu"
+      ],
+      "params": [
+        "match",
+        "parcelNumber",
+        "matchParcelNumber"
+      ],
+      "pathPattern": "^/FR/"
+    }
+  ],
+  "detection": [
+    {
+      "id": "gls-fr-1",
+      "pattern": "^00(?=[A-Z0-9]{6}$)(?=.*[A-Z])(?=.*\\d)[A-Z0-9]{6}$",
+      "confidence": "high"
+    },
+    {
+      "id": "gls-fr-2",
+      "pattern": "^(?=[A-Z0-9]{8}$)(?=.*[A-Z])(?=.*\\d)[A-Z0-9]{8}$",
+      "confidence": "low"
+    },
+    {
+      "id": "gls-fr-3",
+      "pattern": "^\\d{11}$",
+      "confidence": "low"
+    },
+    {
+      "id": "gls-fr-4",
+      "pattern": "^\\d{12}$",
+      "confidence": "low",
+      "checksum": "gls"
+    }
+  ]
+}

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

@@ -0,0 +1,113 @@
+{
+  "carrier": "gls-fr",
+  "records": [
+    {
+      "number": "00AB12CD",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-12",
+      "expect": {
+        "carrier": "gls-fr",
+        "confidence": "high"
+      },
+      "note": "Made-up number that follows the published format."
+    },
+    {
+      "number": "00E7V8YY",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://forum.quechoisir.org/probleme-colis-mondial-relay-gls-t286523.html"
+      },
+      "expect": {
+        "carrier": "gls-fr",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    },
+    {
+      "number": "00IU9SEC",
+      "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": "gls-fr",
+        "confidence": "high"
+      },
+      "note": "Published integration example, not a real shipment."
+    },
+    {
+      "number": "123416227171",
+      "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": [
+          "fedex",
+          "gls-ch",
+          "dpd-fr",
+          "mondial-relay",
+          "gls-fr",
+          "colis-prive",
+          "gls-de",
+          "mrw",
+          "purolator",
+          "sf-express",
+          "sto",
+          "zto",
+          "yamato",
+          "j-and-t"
+        ]
+      },
+      "note": "Published integration example, not a real shipment. The source attributes it to GLS France, which stays one candidate among several."
+    },
+    {
+      "number": "20189360332",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://forum.quechoisir.org/non-livraison-usage-sciemment-reitere-de-faux-bons-de-livraison-t375192.html",
+        "date": "2025-10-30"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "postlogistics",
+          "gls-ch",
+          "gls-fr",
+          "gls-de",
+          "blue-dart",
+          "aramex"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to GLS France, which stays one candidate among several."
+    },
+    {
+      "number": "ZBH2FY7Q",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://forum.quechoisir.org/probleme-colis-mondial-relay-gls-t286523-40.html",
+        "date": "2022-04-25"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "gls-ch",
+          "gls-fr",
+          "gls-de"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to GLS France, which stays one candidate among several."
+    }
+  ]
+}

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

@@ -0,0 +1,28 @@
+/**
+ * GLS France status codes.
+ *
+ * The public consignee endpoint reports letter codes and no human wording:
+ * `statutEvenement` and `typeEvenement` on every event, `statutColis` on the
+ * parcel. This map is therefore the only status source for the adapter, and the
+ * English descriptions below are ours, not GLS's. A code that is not listed
+ * stays unmapped: the adapter emits the event without a stage and the sync
+ * classifies and records it for review.
+ */
+import type { CarrierStatus } from '../../core/result/index.js';
+import type { Stage } from '../../generated/catalog.js';
+export interface GLSFranceStatusMetadata {
+    status: CarrierStatus;
+    stage: Stage;
+    description: string;
+}
+/**
+ * GLS's frontend treats DEL as a rescheduled delay by default. It only marks
+ * the parcel as failed when the newest event has typeEvenement=LIV.
+ */
+export declare const DELAYED_DELIVERY: GLSFranceStatusMetadata;
+export declare const FAILED_DELAYED_DELIVERY: GLSFranceStatusMetadata;
+export declare const GLS_FRANCE_STATUSES: Map<string, GLSFranceStatusMetadata>;
+/** A provider code is two to four letters; anything else is not a code we can read. */
+export declare function glsFranceStatusCode(value: unknown): string;
+export declare function glsFranceStatusMetadata(value: unknown): GLSFranceStatusMetadata | null;
+export declare function glsFranceStatus(value: unknown): CarrierStatus;

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

@@ -0,0 +1,58 @@
+import { cleanScalar } from '../../core/transport/index.js';
+/**
+ * GLS's frontend treats DEL as a rescheduled delay by default. It only marks
+ * the parcel as failed when the newest event has typeEvenement=LIV.
+ */
+export const DELAYED_DELIVERY = {
+    status: 'in_transit',
+    stage: 'in_transit',
+    description: 'Delivery delayed',
+};
+export const FAILED_DELAYED_DELIVERY = {
+    status: 'exception',
+    stage: 'failed_attempt',
+    description: 'Delivery delayed',
+};
+export const GLS_FRANCE_STATUSES = new Map([
+    ['CON', { status: 'pending', stage: 'registered', description: 'Shipment information received' }],
+    ['REC', { status: 'in_transit', stage: 'accepted', description: 'Parcel received at GLS depot' }],
+    ['EXP', { status: 'in_transit', stage: 'in_transit', description: 'Parcel in transit' }],
+    ['PBC', { status: 'in_transit', stage: 'in_transit', description: 'Parcel in transit' }],
+    ['DOU', { status: 'in_transit', stage: 'customs', description: 'Parcel in customs clearance' }],
+    ['TRV', { status: 'out_for_delivery', stage: 'out_for_delivery', description: 'Out for delivery' }],
+    ['LIV', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['LTV', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['LTL', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['LIL', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['LIT', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['LTT', { status: 'delivered', stage: 'delivered', description: 'Delivered' }],
+    ['INC', { status: 'exception', stage: 'exception', description: 'Incomplete delivery information' }],
+    ['PBP', { status: 'exception', stage: 'failed_attempt', description: 'Parcel delivery issue' }],
+    ['NLI', { status: 'exception', stage: 'failed_attempt', description: 'Delivery attempt unsuccessful' }],
+    ['NLK', { status: 'exception', stage: 'failed_attempt', description: 'Locker delivery unsuccessful' }],
+    ['NLP', { status: 'exception', stage: 'failed_attempt', description: 'ParcelShop delivery unsuccessful' }],
+    ['RET', { status: 'exception', stage: 'returned', description: 'Returning to sender' }],
+    ['PBA', { status: 'exception', stage: 'failed_attempt', description: 'Parcel delivery issue' }],
+    ['SIN', { status: 'exception', stage: 'exception', description: 'Shipment incident' }],
+    ['LIP', { status: 'out_for_delivery', stage: 'ready_for_pickup', description: 'Ready for pickup at GLS ParcelShop' }],
+    ['LTP', { status: 'out_for_delivery', stage: 'ready_for_pickup', description: 'Ready for pickup at GLS ParcelShop' }],
+    ['LIK', { status: 'out_for_delivery', stage: 'ready_for_pickup', description: 'Ready for pickup at GLS Locker' }],
+    ['LTK', { status: 'out_for_delivery', stage: 'ready_for_pickup', description: 'Ready for pickup at GLS Locker' }],
+    ['PAQ', { status: 'out_for_delivery', stage: 'ready_for_pickup', description: 'Ready for pickup at GLS depot' }],
+    // These additional values are present in the current official tracking frontend.
+    ['DEP', { status: 'in_transit', stage: 'in_transit', description: 'ParcelShop delivery planned' }],
+    ['DEK', { status: 'in_transit', stage: 'in_transit', description: 'Locker delivery planned' }],
+    ['DEL', DELAYED_DELIVERY],
+    ['LIR', { status: 'exception', stage: 'returned', description: 'Returned to sender' }],
+]);
+/** A provider code is two to four letters; anything else is not a code we can read. */
+export function glsFranceStatusCode(value) {
+    const code = cleanScalar(value, 12).toLocaleUpperCase('en-US');
+    return /^[A-Z]{2,4}$/.test(code) ? code : '';
+}
+export function glsFranceStatusMetadata(value) {
+    return GLS_FRANCE_STATUSES.get(glsFranceStatusCode(value)) ?? null;
+}
+export function glsFranceStatus(value) {
+    return glsFranceStatusMetadata(value)?.status ?? 'unknown';
+}

package/dist/carriers/gls-fr/statuses.json

@@ -0,0 +1,34 @@
+{
+  "carrier": "gls-fr",
+  "entries": [
+    { "code": "CON", "stage": "registered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Shipment information received; the parcel is announced but not yet handed over." },
+    { "code": "REC", "stage": "accepted", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Parcel received at a GLS depot." },
+    { "code": "EXP", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "PBC", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "DOU", "stage": "customs", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "TRV", "stage": "out_for_delivery", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "LIV", "stage": "delivered", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Also read as typeEvenement: DEL plus typeEvenement LIV is a failed attempt, not a delivery." },
+    { "code": "LTV", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "LTL", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "LIL", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "LIT", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "LTT", "stage": "delivered", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "INC", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Incomplete delivery information. Reclassified to exception 2026-09-12." },
+    { "code": "PBP", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "NLI", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "NLK", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Locker delivery unsuccessful." },
+    { "code": "NLP", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "ParcelShop delivery unsuccessful." },
+    { "code": "RET", "stage": "returned", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Returning to sender." },
+    { "code": "PBA", "stage": "failed_attempt", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "" },
+    { "code": "SIN", "stage": "exception", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Shipment incident. Reclassified to exception 2026-09-12." },
+    { "code": "LIP", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Waiting at a GLS ParcelShop." },
+    { "code": "LTP", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Waiting at a GLS ParcelShop." },
+    { "code": "LIK", "stage": "ready_for_pickup", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Waiting in a GLS locker." },
+    { "code": "LTK", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Waiting in a GLS locker." },
+    { "code": "PAQ", "stage": "ready_for_pickup", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Waiting at a GLS depot." },
+    { "code": "DEP", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "ParcelShop delivery planned; present in the current official tracking frontend." },
+    { "code": "DEK", "stage": "in_transit", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Locker delivery planned; present in the current official tracking frontend." },
+    { "code": "DEL", "stage": "in_transit", "confirmedBy": "fixture", "firstSeen": "2026-09-12", "note": "Rescheduled delay. The same code becomes failed_attempt when the event's typeEvenement is LIV, which is how the official frontend reads it." },
+    { "code": "LIR", "stage": "returned", "confirmedBy": "official-doc", "firstSeen": "2026-09-12", "note": "Returned to sender." }
+  ]
+}

package/dist/carriers/gofo/adapter.d.ts

@@ -0,0 +1,11 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class GofoTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/gofo/adapter.js

@@ -0,0 +1,41 @@
+import { SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { GOFO_CLOCK_ZONE, normalizeGofoNumber, parseGofo } from './parser.js';
+const ENDPOINT = 'https://www.gofo.com/us/cnee-api/consignee/track/query/page';
+export class GofoTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeGofoNumber(raw);
+        return runSteps({ carrier: 'gofo', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    try {
+                        const { bytes } = await fetchBounded(ENDPOINT, { method: 'POST', signal,
+                            headers: { Accept: 'application/json', 'Content-Type': 'application/json', lang: 'en', 'User-Time-Zone': GOFO_CLOCK_ZONE },
+                            body: JSON.stringify({ numberList: [number] }) }, { provider: 'GOFO', timeoutMs: Math.max(1, Math.floor(remainingMs)),
+                            maxBytes: 1_000_000, fetcher: this.options.fetcher });
+                        let payload;
+                        try {
+                            payload = parseJsonBytes(bytes, 'GOFO');
+                        }
+                        catch (cause) {
+                            throw new SchemaError('GOFO', 'GOFO returned invalid tracking JSON', { cause });
+                        }
+                        return parseGofo(payload, number);
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                            throw new TransportError('GOFO', 'GOFO tracking endpoint is unavailable', { cause: error });
+                        throw error;
+                    }
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new GofoTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'gofo', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};