universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/fedex/status.js

@@ -0,0 +1,114 @@
+/** Package and scan codes, uppercased, to the product stage. */
+export const FEDEX_CODE_STAGE = {
+    OC: 'registered',
+    PU: 'accepted',
+    AR: 'in_transit',
+    DP: 'in_transit',
+    IT: 'in_transit',
+    OD: 'out_for_delivery',
+    DL: 'delivered',
+    DE: 'failed_attempt',
+    DY: 'exception',
+    SE: 'exception',
+    CA: 'exception',
+};
+const RETURNED_TERMS = ['return to sender', 'returned to shipper', 'returning to shipper'];
+const FAILED_ATTEMPT_TERMS = [
+    'delivery exception',
+    'delivery attempted',
+    'delivery attempt',
+    'we missed you',
+    'customer not available',
+    'business closed',
+    'not delivered',
+    'unable to deliver',
+    'delivery not attempted',
+];
+const EXCEPTION_TERMS = [
+    'shipment exception',
+    'exception',
+    'delayed',
+    'delay',
+    'damaged',
+    'lost',
+    'held',
+    'action required',
+    'clearance delay',
+];
+const DELIVERED_TERMS = ['delivered', 'signed for', 'left at', 'received by'];
+const CUSTOMS_TERMS = ['clearance', 'customs'];
+const OUT_FOR_DELIVERY_TERMS = ['out for delivery', 'on fedex vehicle for delivery', 'on vehicle for delivery'];
+const REGISTERED_TERMS = [
+    'shipment information sent',
+    'information sent to fedex',
+    'label created',
+    'manifest',
+    'initiated',
+    'order created',
+];
+const ACCEPTED_TERMS = ['picked up', 'pickedup', 'tendered at fedex', 'arrived at fedex location', 'accepted at'];
+const IN_TRANSIT_TERMS = [
+    'in transit',
+    'on the way',
+    'departed fedex location',
+    'departed',
+    'arrived',
+    'at local fedex facility',
+    'at destination sort facility',
+];
+/**
+ * Classify FedEx status prose. Returns null when nothing matches, so callers
+ * can fall back to the code or leave an event unstaged rather than invent a
+ * stage. `hasEvents` reports an existing scan history, which makes
+ * unrecognized wording "moving" rather than "unknown".
+ */
+export function fedexStage(text) {
+    const value = text.toLocaleLowerCase('en-US');
+    if (!value)
+        return null;
+    if (RETURNED_TERMS.some((term) => value.includes(term)))
+        return 'returned';
+    if (FAILED_ATTEMPT_TERMS.some((term) => value.includes(term)))
+        return 'failed_attempt';
+    if (DELIVERED_TERMS.some((term) => value.includes(term)))
+        return 'delivered';
+    if (OUT_FOR_DELIVERY_TERMS.some((term) => value.includes(term)))
+        return 'out_for_delivery';
+    if (CUSTOMS_TERMS.some((term) => value.includes(term)))
+        return 'customs';
+    if (EXCEPTION_TERMS.some((term) => value.includes(term)))
+        return 'exception';
+    if (REGISTERED_TERMS.some((term) => value.includes(term)))
+        return 'registered';
+    if (ACCEPTED_TERMS.some((term) => value.includes(term)))
+        return 'accepted';
+    if (IN_TRANSIT_TERMS.some((term) => value.includes(term)))
+        return 'in_transit';
+    return null;
+}
+export function statusForStage(stage) {
+    if (stage === 'delivered')
+        return 'delivered';
+    if (stage === 'out_for_delivery' || stage === 'ready_for_pickup')
+        return 'out_for_delivery';
+    if (stage === 'exception' || stage === 'failed_attempt' || stage === 'returned')
+        return 'exception';
+    if (stage === 'registered' || stage === 'pending')
+        return 'pending';
+    return 'in_transit';
+}
+/**
+ * The result-level status for a package code plus its prose. The code wins,
+ * except that an unmapped code falls back to the wording, and unrecognized
+ * wording on a shipment that already has scans reads as moving.
+ */
+export function fedexStatus(code, text, hasEvents = false) {
+    const stage = FEDEX_CODE_STAGE[code.toUpperCase()];
+    if (stage)
+        return statusForStage(stage);
+    const wording = fedexStage(text);
+    if (wording)
+        return statusForStage(wording);
+    // Unrecognized wording only means "moving" once the shipment has scans.
+    return hasEvents ? 'in_transit' : 'unknown';
+}

package/dist/carriers/fedex/statuses.json

@@ -0,0 +1,34 @@
+{
+  "carrier": "fedex",
+  "entries": [
+    { "code": "OC", "language": "en", "stage": "registered", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; shipment information sent to FedEx." },
+    { "code": "PU", "language": "en", "stage": "accepted", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; picked up." },
+    { "code": "AR", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "keyStatusCD; arrived at FedEx location." },
+    { "code": "DP", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "keyStatusCD; departed FedEx location." },
+    { "code": "IT", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "keyStatusCD; in transit." },
+    { "code": "OD", "language": "en", "stage": "out_for_delivery", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; on FedEx vehicle for delivery." },
+    { "code": "DL", "language": "en", "stage": "delivered", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; terminal, outranks the wording." },
+    { "code": "DE", "language": "en", "stage": "failed_attempt", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; drives the page's own delivery-exception flag. Adapter result status: exception." },
+    { "code": "DY", "language": "en", "stage": "exception", "confirmedBy": "bundle", "firstSeen": "2026-09-20", "note": "keyStatusCD; drives the page's own delay flag." },
+    { "code": "SE", "language": "en", "stage": "exception", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "keyStatusCD; shipment exception." },
+    { "code": "CA", "language": "en", "stage": "exception", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "keyStatusCD; cancelled. The result vocabulary has no cancelled state, so it surfaces as exception." },
+    { "wording": "Shipment information sent to FedEx", "language": "en", "stage": "registered", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Picked up", "language": "en", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Tendered at FedEx location", "language": "en", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Arrived at FedEx location", "language": "en", "stage": "accepted", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: in_transit." },
+    { "wording": "Departed FedEx location", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "At local FedEx facility", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "At destination sort facility", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "On the way", "language": "en", "stage": "in_transit", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Clearance delay", "language": "en", "stage": "customs", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: in_transit." },
+    { "wording": "Clearance in progress", "language": "en", "stage": "customs", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: in_transit." },
+    { "wording": "On FedEx vehicle for delivery", "language": "en", "stage": "out_for_delivery", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Delivered", "language": "en", "stage": "delivered", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "A delivered scan's description is replaced by this word because the original names the signatory." },
+    { "wording": "Delivery exception", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: exception." },
+    { "wording": "Customer not available or business closed", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: exception." },
+    { "wording": "Local delivery restriction - Delivery not attempted", "language": "en", "stage": "failed_attempt", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: exception." },
+    { "wording": "Shipment exception", "language": "en", "stage": "exception", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Unable to deliver", "language": "en", "stage": "exception", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "" },
+    { "wording": "Returning to shipper", "language": "en", "stage": "returned", "confirmedBy": "prior-art", "firstSeen": "2026-09-20", "note": "Adapter result status: exception." }
+  ]
+}

package/dist/carriers/four-px/adapter.d.ts

@@ -0,0 +1,12 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeFourPxNumber(raw: string): string;
+export declare function parse(payload: unknown, trackingNumber: string): CarrierResult;
+export declare class FourPxTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/four-px/adapter.js

@@ -0,0 +1,113 @@
+import { DateTime } from 'luxon';
+import { IndeterminateError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { clean, fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { fourPxStatus } from './status.js';
+const ENDPOINT = 'https://track.4px.com/track/v2/front/listTrackV3';
+export function normalizeFourPxNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^[A-Z0-9]{8,40}$/.test(number))
+        throw new TypeError('4PX requires an alphanumeric parcel reference');
+    return number;
+}
+function eventTime(raw) {
+    const local = clean(raw.tkDateStr, 64);
+    if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(local))
+        throw new SchemaError('4PX', '4PX returned an invalid scan time');
+    const zone = clean(raw.tkTimezone, 32);
+    const offset = /^UTC([+-]\d{2}:\d{2})$/.exec(zone)?.[1];
+    if (zone && !offset && zone !== 'UTC')
+        throw new SchemaError('4PX', '4PX returned an invalid scan offset');
+    // The displayed time and offset form one pair. tkDate encodes different
+    // clock digits and must not replace the portal's per-scan local timestamp.
+    const parsed = DateTime.fromISO(`${local.replace(' ', 'T')}${offset ?? (zone === 'UTC' ? 'Z' : '')}`, { setZone: true, zone: 'UTC' });
+    if (!parsed.isValid)
+        throw new SchemaError('4PX', '4PX returned an invalid scan time');
+    const iso = parsed.toISO({ suppressMilliseconds: true, includeOffset: Boolean(zone) });
+    return zone ? { time: iso } : { local_time: iso };
+}
+export function parse(payload, trackingNumber) {
+    const number = normalizeFourPxNumber(trackingNumber);
+    if (!isRecord(payload) || payload.result !== 1 || !Array.isArray(payload.data))
+        throw new SchemaError('4PX');
+    const matches = payload.data.filter((item) => isRecord(item) && clean(item.queryCode, 64).toUpperCase() === number);
+    if (matches.length !== 1 || !isRecord(matches[0]))
+        throw new SchemaError('4PX', '4PX returned a different or ambiguous shipment');
+    const item = matches[0];
+    if (item.status === 7 && item.serverCode === null && item.shipperCode === null && item.tracks === null)
+        throw new NotFoundError('4PX');
+    if (item.mutiPackage === true)
+        throw new IndeterminateError('4PX', '4PX returned a multi-package order requiring separate parcel history');
+    if (!Array.isArray(item.tracks) || item.tracks.length === 0)
+        throw new IndeterminateError('4PX', '4PX returned no parcel scans');
+    if (item.tracks.length > 500)
+        throw new SchemaError('4PX', '4PX returned excessive tracking history');
+    const events = [];
+    const seen = new Set();
+    for (const raw of item.tracks) {
+        if (!isRecord(raw))
+            throw new SchemaError('4PX');
+        const description = clean(raw.tkDesc, 500);
+        if (!description)
+            throw new SchemaError('4PX', '4PX returned an empty scan');
+        const time = eventTime(raw);
+        const location = clean(raw.tkLocation, 200);
+        const code = clean(raw.tkCode, 64);
+        const key = JSON.stringify([time, description, location, code]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const classified = fourPxStatus(code);
+        events.push({ ...time, description, location, ...(code ? { provider_code: code } : {}), ...(classified ? { stage: classified.stage } : {}) });
+    }
+    const latest = events[0];
+    const classified = fourPxStatus(latest.provider_code ?? '');
+    const deliveryNumber = clean(item.serverCode, 64).toUpperCase();
+    const country = clean(item.ctEndCode, 8).toUpperCase();
+    return {
+        status: classified?.status ?? 'unknown',
+        ...(classified ? { current_stage: classified.stage } : {}),
+        last_status_text: latest.description,
+        last_update: latest.time ?? null,
+        ...(classified?.stage === 'delivered' && latest.time ? { delivered_at: latest.time } : {}),
+        ...(/^[A-Z]{2}$/.test(country) ? { destination_country: country } : {}),
+        ...(deliveryNumber !== number && /^[A-Z0-9]{4,40}$/.test(deliveryNumber) ? { delivery_tracking_number: deliveryNumber } : {}),
+        events: events.slice(0, 100),
+    };
+}
+export class FourPxTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeFourPxNumber(raw);
+        const budgetMs = context.budgetMs ?? 15_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('4PX timeout must be positive');
+        context.signal?.throwIfAborted();
+        try {
+            const { bytes } = await fetchBounded(ENDPOINT, {
+                method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify({ queryCodes: [number], language: 'en-us', translateLanguage: '' }),
+            }, {
+                provider: '4PX', timeoutMs: Math.max(1, Math.floor(budgetMs)), maxBytes: 1_000_000,
+                fetcher: (input, init) => (this.options.fetcher ?? fetch)(input, { ...init,
+                    signal: AbortSignal.any([...(context.signal ? [context.signal] : []), ...(init?.signal ? [init.signal] : [])]) }),
+            });
+            context.signal?.throwIfAborted();
+            return parse(parseJsonBytes(bytes, '4PX'), number);
+        }
+        catch (error) {
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                throw new TransportError('4PX', '4PX tracking endpoint is unavailable', { cause: error });
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new FourPxTracker({ fetcher: environment.fetcher });
+    return { id: 'four-px', recordsSteps: true, steps: ['direct'], track: (input, context = {}) => runSteps({ carrier: 'four-px', budgetMs: context.budgetMs ?? 15_000,
+            signal: context.signal, recorder: environment.recorder }, [{ id: 'direct', run: ({ signal, remainingMs }) => tracker.fetch(input.number, { signal, budgetMs: remainingMs }) }]) };
+};

package/dist/carriers/four-px/carrier.json

@@ -0,0 +1,60 @@
+{
+  "id": "four-px",
+  "displayName": "4PX",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "CN"
+    ]
+  },
+  "brand": {
+    "color": "#f58220"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "four-px",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at"
+  ],
+  "portal": {
+    "url": "https://track.4px.com/#/result/0/{trackingNumber}",
+    "canaryUrl": "https://track.4px.com/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "track.4px.com"
+      ],
+      "pathPattern": "^/$",
+      "fragment": "^/result/0/([A-Z0-9]+)$"
+    }
+  ],
+  "detection": [
+    {
+      "id": "four-px-1",
+      "pattern": "^4PX\\d{13}CN$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/four-px/numbers.json

@@ -0,0 +1,32 @@
+{
+  "carrier": "four-px",
+  "records": [
+    {
+      "number": "4PX3001521662170CN",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/rostis232/parcelstrackingservice"
+      },
+      "expect": {
+        "carrier": "four-px",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment."
+    },
+    {
+      "number": "4PX3002790888841CN",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.chinapostaltracking.com/qa/what-is-my-tracking-number-format-159483/",
+        "date": "2026-06-26"
+      },
+      "expect": {
+        "carrier": "four-px",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified."
+    }
+  ]
+}

package/dist/carriers/four-px/status.d.ts

@@ -0,0 +1,2 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function fourPxStatus(code: string): ClassifiedStatus | undefined;

package/dist/carriers/four-px/status.js

@@ -0,0 +1,22 @@
+const CODES = new Map([
+    ['FPX_S_OK', { status: 'delivered', stage: 'delivered' }],
+    ['FPX_D_SD', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['FPX_L_RPIF', { status: 'pending', stage: 'registered' }],
+    ['FPX_O_IRI', { status: 'pending', stage: 'registered' }],
+    ['FPX_L_SC', { status: 'in_transit', stage: 'accepted' }],
+    ['FPX_C_SPLS', { status: 'in_transit', stage: 'accepted' }],
+    ['FPX_C_AAF', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_C_ADFF', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_M_HA', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_M_DFOA', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_M_ATA', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_M_CRSD', { status: 'in_transit', stage: 'customs' }],
+    ['FPX_I_RCUK', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_D_STPP', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_D_HQ', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_O_RR', { status: 'in_transit', stage: 'in_transit' }],
+    ['FPX_M_IT', { status: 'in_transit', stage: 'in_transit' }],
+]);
+export function fourPxStatus(code) {
+    return CODES.get(code);
+}

package/dist/carriers/four-px/statuses.json

@@ -0,0 +1,141 @@
+{
+  "carrier": "four-px",
+  "entries": [
+    {
+      "code": "FPX_S_OK",
+      "wording": "Delivered, in/at mailbox",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_D_SD",
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_D_HQ",
+      "wording": "Arrived at post office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_O_RR",
+      "wording": "Arrived at usps facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_M_IT",
+      "wording": "In transit to next facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_D_STPP",
+      "wording": "In transit, it's progressing through post network",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_M_CRSD",
+      "wording": "Customs clearance agent received the shipment in destnation country.",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_M_ATA",
+      "wording": "Arrival to the destination airport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_I_RCUK",
+      "wording": "Released from customs: customs cleared.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_M_DFOA",
+      "wording": "Departure from the original airport",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_M_HA",
+      "wording": "Hand over to airline.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_C_ADFF",
+      "wording": "Depart from facility to service provider.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_C_AAF",
+      "wording": "Shipment arrived at facility and measured.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_C_SPLS",
+      "wording": "Shipment picked up.",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_L_SC",
+      "wording": "Pickup scanned, in transit to warehouse",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_O_IRI",
+      "wording": "Shipping label created, usps awaiting item",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "FPX_L_RPIF",
+      "wording": "Parcel information received",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    }
+  ]
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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 type { AdapterFactory } from '../../core/adapter/index.js';
+import { NotFoundError } from '../../core/errors/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export { classifyStatus } from './status.js';
+/**
+ * Kept as a named class because the grouped live suite matches on its name. It
+ * is a plain `NotFoundError`.
+ */
+export declare class GeodisTrackingError extends NotFoundError {
+    constructor();
+}
+export declare function normalizeGeodisTrackingNumber(raw: string): string;
+export declare function geodisTrackingUrl(): string;
+export declare function geodisRequestBody(rawTrackingNumber: string): string;
+export declare function geodisServiceHeader(rawTrackingNumber: string, timestamp: number, language?: string): string;
+export declare function parseGeodisTrackingResponse(payload: unknown, rawTrackingNumber: string): CarrierResult;
+export interface GeodisTrackerOptions {
+    timeoutMs?: number;
+    /** Test seam; production uses the global fetch. */
+    fetcher?: typeof fetch;
+}
+export declare class GeodisTracker {
+    #private;
+    readonly timeoutMs: number;
+    constructor(options?: GeodisTrackerOptions);
+    fetch(rawTrackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;