universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/ems/statuses.json

@@ -0,0 +1,128 @@
+{
+  "carrier": "ems",
+  "entries": [
+    {
+      "wording": "Posted",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Arrived at export office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Presented to export customs and security",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Released from export customs and security",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Departed from export office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Held for export customs inspection",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Arrived at destination import office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Held at destination import office",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Presented to import customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Released from import customs",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Departed from destination import office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Arrived at post office",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-21"
+    },
+    {
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-21",
+      "note": "Conservative exact-wording case; synthetic fixture only, not observed in the live references."
+    },
+    {
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-21",
+      "note": "Conservative exact-wording case; synthetic fixture only, not observed in the live references."
+    },
+    {
+      "wording": "Delivery attempted",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-21",
+      "note": "Conservative exact-wording case; synthetic fixture only, not observed in the live references."
+    },
+    {
+      "wording": "Returned to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-21",
+      "note": "Conservative exact-wording case; synthetic fixture only, not observed in the live references."
+    },
+    {
+      "wording": "Export cancelled",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "note": "Observed Cooperative export cancellation; does not prove completed return."
+    }
+  ]
+}

package/dist/carriers/estafeta/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 EstafetaTracker {
+    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/estafeta/adapter.js

@@ -0,0 +1,45 @@
+import { BudgetExceededError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded } from '../../core/transport/index.js';
+import { normalizeEstafetaNumber, parseEstafetaHistory, parseEstafetaLookup } from './parser.js';
+const ORIGIN = 'https://cs.estafeta.com';
+export class EstafetaTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeEstafetaNumber(raw);
+        const budgetMs = context.budgetMs ?? 15_000;
+        return runSteps({ carrier: 'estafeta', budgetMs, signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [{ id: 'direct', run: async ({ signal, remainingMs }) => {
+                    const started = performance.now();
+                    const timeout = () => {
+                        signal.throwIfAborted();
+                        const left = remainingMs - (performance.now() - started);
+                        if (left <= 0)
+                            throw new BudgetExceededError('Estafeta', budgetMs);
+                        return Math.max(1, Math.floor(left));
+                    };
+                    try {
+                        const params = new URLSearchParams({ wayBill: number, wayBillType: number.length === 10 ? '0' : '1', isShipmentDetail: 'True' });
+                        const first = await fetchBounded(`${ORIGIN}/es/Tracking/searchByGet?${params}`, { signal }, { provider: 'Estafeta', timeoutMs: timeout(), maxBytes: 1_000_000, fetcher: this.options.fetcher });
+                        const lookup = parseEstafetaLookup(decodeText(first.bytes), number);
+                        // Only the identity-bound canonical guide controls this read-only
+                        // history request. No account, issued session or report API is used.
+                        const history = await fetchBounded(`${ORIGIN}/es/Tracking/GetTrackingItemHistory`, { method: 'POST', signal,
+                            headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ waybill: lookup.guide }).toString() }, { provider: 'Estafeta', timeoutMs: timeout(), maxBytes: 1_000_000, fetcher: this.options.fetcher });
+                        return parseEstafetaHistory(decodeText(history.bytes), lookup);
+                    }
+                    catch (error) {
+                        if (error instanceof UpstreamHttpError && [404, 410].includes(error.status))
+                            throw new TransportError('Estafeta', 'Estafeta tracking endpoint is unavailable', { cause: error });
+                        throw error;
+                    }
+                } }]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new EstafetaTracker({ fetcher: environment.fetcher, recorder: environment.recorder });
+    return { id: 'estafeta', recordsSteps: true, steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/estafeta/carrier.json

@@ -0,0 +1,79 @@
+{
+  "id": "estafeta",
+  "displayName": "Estafeta",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "MX"
+    ]
+  },
+  "brand": {
+    "color": "#e30613"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "estafeta",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://cs.estafeta.com/es/Tracking/searchByGet?wayBill={trackingNumber}&isShipmentDetail=True",
+    "canaryUrl": "https://cs.estafeta.com/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "recipient_names",
+      "postcodes",
+      "signatures",
+      "proof_images",
+      "shipment_reports",
+      "scheduled_delivery"
+    ],
+    "unavailable": []
+  },
+  "links": [
+    {
+      "domains": [
+        "cs.estafeta.com"
+      ],
+      "path": "^/es/Tracking/searchByGet/?$",
+      "params": [
+        "wayBill"
+      ]
+    }
+  ],
+  "detection": [
+    {
+      "id": "estafeta-1",
+      "pattern": "^\\d{10}$",
+      "confidence": "low"
+    },
+    {
+      "id": "estafeta-full-guide",
+      "pattern": "^(?:\\d{22}|\\d{15}[A-Z0-9]{7})$",
+      "confidence": "low"
+    },
+    {
+      "id": "estafeta-lettered-guide",
+      "pattern": "^\\d{12}(?:[A-Z]\\d|\\d[A-Z])\\d{8}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/estafeta/numbers.json

@@ -0,0 +1,85 @@
+{
+  "carrier": "estafeta",
+  "records": [
+    {
+      "number": "1172614482",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a8f2a5d5d9cdb66b6991955",
+        "date": "2026-08-26"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Publicly reported short tracking code; the native single-parcel response pairs it with its full guide. The shape remains ambiguous pending a matching lookup."
+    },
+    {
+      "number": "2806075762",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/dmoralesm/estafeta-api"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl",
+          "mondial-relay",
+          "relais-colis",
+          "tipsa",
+          "estafeta"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Estafeta, which stays one candidate among several."
+    },
+    {
+      "number": "502553526650A704483512",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a8f2a5d5d9cdb66b6991955",
+        "date": "2026-08-26"
+      },
+      "expect": {
+        "carrier": "estafeta",
+        "confidence": "high"
+      },
+      "note": "Publicly reported full guide with a letter in the 13th place; the native single-parcel response pairs it with its short tracking code."
+    },
+    {
+      "number": "805590979741C700931121",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/albertollopez92-dev/bitacora-envios/blob/main/index.html"
+      },
+      "expect": {
+        "carrier": "estafeta",
+        "confidence": "high"
+      },
+      "note": "Full-guide placeholder in an open-source shipment log, with a letter in the 13th place."
+    },
+    {
+      "number": "9000000000001D00000002",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "official_shape",
+      "shapeConfirmed": "2026-09-30",
+      "expect": {
+        "carrier": "estafeta",
+        "confidence": "high"
+      },
+      "note": "Made-up two-day guide with the service letter D in the 14th place, as on older Estafeta result pages."
+    }
+  ]
+}

package/dist/carriers/estafeta/parser.d.ts

@@ -0,0 +1,11 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export interface EstafetaLookup {
+    number: string;
+    guide: string;
+    latestDate: string;
+    latestClock: string;
+    state: string;
+}
+export declare function normalizeEstafetaNumber(raw: string): string;
+export declare function parseEstafetaLookup(html: string, rawNumber: string): EstafetaLookup;
+export declare function parseEstafetaHistory(html: string, lookup: EstafetaLookup): CarrierResult;

package/dist/carriers/estafeta/parser.js

@@ -0,0 +1,123 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { ChallengeError, IndeterminateError, SchemaError } from '../../core/errors/index.js';
+import { clean } from '../../core/transport/index.js';
+import { estafetaStatus } from './status.js';
+// A letter can take the 13th or 14th place (two-day guides carry a D in the 14th).
+const FULL_GUIDE = /^(?:\d{22}|\d{12}(?:[A-Z]\d|\d[A-Z])\d{8}|\d{15}[A-Z0-9]{7})$/;
+export function normalizeEstafetaNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^\d{10}$/.test(number) && !FULL_GUIDE.test(number))
+        throw new TypeError('Estafeta requires a tracking code or full guide');
+    return number;
+}
+function page(html) {
+    const $ = load(html);
+    if (/just a moment|verify.*human|captcha/i.test($('title').text()) || $('.g-recaptcha,.h-captcha,#challenge-form').length)
+        throw new ChallengeError('Estafeta');
+    $('script,style,noscript').remove();
+    return $;
+}
+export function parseEstafetaLookup(html, rawNumber) {
+    const number = normalizeEstafetaNumber(rawNumber);
+    const $ = page(html);
+    const cards = $('.shipmentByOne');
+    if ($('[data-tracking-code],.clsnTrackingCode,.multiplesWaybillList,.MultipleLink').length || cards.length > 1) {
+        throw new IndeterminateError('Estafeta', 'Estafeta requires a specific single-piece guide');
+    }
+    if (!cards.length && $('.TimeLineErrorRow h4').length === 1
+        && clean($('.TimeLineErrorRow h4').text()) === 'Lo sentimos, no se encontró información') {
+        // The observed error omits the requested reference and also describes
+        // unavailable information; it does not prove parcel absence.
+        throw new IndeterminateError('Estafeta', 'Estafeta returned no bound parcel information');
+    }
+    if (cards.length !== 1 || cards.find('.shipmentInfoDiv').length !== 1 || $('title').text().trim() !== 'Resultado')
+        throw new SchemaError('Estafeta');
+    const field = (label) => {
+        const nodes = cards.find('.shipmentInfoSeparator').filter((_, node) => clean($(node).children('.fontRoman').text()) === label);
+        if (nodes.length !== 1 || nodes.children('.fontBold').length !== 1)
+            throw new SchemaError('Estafeta', 'Estafeta returned incomplete parcel identity');
+        return clean(nodes.children('.fontBold').text(), 64);
+    };
+    const guide = field('Número de guía:');
+    const code = field('Código de rastreo:');
+    if (!FULL_GUIDE.test(guide) || !/^\d{10}$/.test(code) || (number.length === 10 ? code !== number : guide !== number)) {
+        throw new SchemaError('Estafeta', 'Estafeta returned a different parcel');
+    }
+    const controls = cards.find('.showHistory');
+    if (controls.length !== 1 || controls.attr('data-shipment-index') !== guide)
+        throw new SchemaError('Estafeta', 'Estafeta returned a different history target');
+    const state = cards.find('.stateDescription.fontColorCurrentProcess');
+    const messages = cards.find('.fontColorCurrentProcessMessage');
+    const parts = messages.contents().filter((_, node) => node.type === 'text').map((_, node) => clean($(node).text(), 100)).get().filter(Boolean);
+    if (state.length !== 1 || messages.length !== 1 || parts.length < 2)
+        throw new SchemaError('Estafeta', 'Estafeta returned incomplete latest activity');
+    return { number, guide, state: clean(state.text(), 200), latestClock: parts[0], latestDate: parts[1] };
+}
+function clockText(raw) { return raw.replace(/\s+hrs\.$/i, '').trim(); }
+function clock(day, time) {
+    const rawClock = clockText(time);
+    const validated = /^\d{2}\/\d{2}\/\d{4}$/.test(day) && /^(?:[01]\d|2[0-3]):[0-5]\d$/.test(rawClock)
+        ? DateTime.fromFormat(`${day} ${rawClock}`, 'dd/MM/yyyy HH:mm', { zone: 'UTC' }) : null;
+    return validated?.isValid ? { local_time: validated.toISO({ includeOffset: false, suppressMilliseconds: true }) }
+        : { provider_time_text: clean(`${day} ${time}`, 100) };
+}
+export function parseEstafetaHistory(html, lookup) {
+    const $ = page(html);
+    const groups = $('.historyEventRow');
+    if (!groups.length)
+        throw new IndeterminateError('Estafeta', 'Estafeta returned no parcel history');
+    if (groups.length > 500 || $('.eventInfo').length > 500)
+        throw new SchemaError('Estafeta', 'Estafeta returned excessive history');
+    const events = [];
+    const seen = new Set();
+    let scanCount = 0;
+    let firstDate = '';
+    let firstClock = '';
+    for (const group of groups.toArray()) {
+        const root = $(group);
+        const bindings = root.find('.remainingHistoryEvents[data-shipmentindex]');
+        const dayCell = root.children('.col-xs-2');
+        const eventBox = root.children('.col-xs-9');
+        if (bindings.length !== 1 || bindings.attr('data-shipmentindex') !== lookup.guide || dayCell.length !== 1 || eventBox.length !== 1
+            || root.find('.historyEventRow').length)
+            throw new SchemaError('Estafeta', 'Estafeta returned a different or ambiguous history group');
+        const day = clean(dayCell.text(), 64);
+        const rows = eventBox.find('.eventInfo');
+        if (!rows.length)
+            throw new SchemaError('Estafeta', 'Estafeta returned an empty history group');
+        for (const row of rows.toArray()) {
+            const cells = $(row).children('div');
+            if (cells.length !== 3 || cells.eq(0).is('.col-sm-2') === false || cells.eq(1).is('.col-sm-3') === false || cells.eq(2).is('.col-sm-7') === false)
+                throw new SchemaError('Estafeta');
+            const time = clean(cells.eq(0).text(), 64);
+            const description = clean(cells.eq(2).text(), 500);
+            if (!description)
+                throw new SchemaError('Estafeta', 'Estafeta returned an empty scan');
+            if (scanCount++ === 0) {
+                firstDate = day;
+                firstClock = clockText(time);
+            }
+            const mapped = estafetaStatus(description);
+            const event = { ...clock(day, time), description, location: clean(cells.eq(1).text(), 200), ...(mapped ? { stage: mapped.stage } : {}) };
+            const key = JSON.stringify(event);
+            if (!seen.has(key)) {
+                seen.add(key);
+                events.push(event);
+            }
+        }
+    }
+    if (scanCount !== $('.eventInfo').length)
+        throw new SchemaError('Estafeta', 'Estafeta returned scans outside its parcel groups');
+    if (firstDate !== lookup.latestDate || firstClock !== clockText(lookup.latestClock))
+        throw new IndeterminateError('Estafeta', 'Estafeta latest summary does not match its first scan');
+    const latest = events[0];
+    const current = estafetaStatus(String(latest.description));
+    const summary = estafetaStatus(lookup.state);
+    if ((current?.stage === 'delivered' || summary?.stage === 'delivered') && current?.stage !== summary?.stage)
+        throw new IndeterminateError('Estafeta', 'Estafeta returned inconsistent delivery evidence');
+    return { status: current?.status ?? 'unknown', ...(current ? { current_stage: current.stage } : {}),
+        last_status_text: latest.description, last_update: null, last_update_local: latest.local_time ?? null, expected_delivery: null,
+        ...(lookup.number !== lookup.guide ? { canonical_tracking_number: lookup.guide } : {}), events: events.slice(0, 100) };
+}

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

@@ -0,0 +1,3 @@
+import type { ClassifiedStatus } from '../../core/status/index.js';
+export declare function estafetaWording(value: string): string;
+export declare function estafetaStatus(wording: string): ClassifiedStatus | undefined;

package/dist/carriers/estafeta/status.js

@@ -0,0 +1,17 @@
+export function estafetaWording(value) {
+    return value.normalize('NFD').replace(/\p{Diacritic}/gu, '').trim().toLowerCase();
+}
+const WORDINGS = new Map([
+    ['entregado', { status: 'delivered', stage: 'delivered' }],
+    ['en proceso de entrega a domicilio', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['en transito', { status: 'in_transit', stage: 'in_transit' }],
+    ['recibido por estafeta', { status: 'in_transit', stage: 'accepted' }],
+    ['carga demorada por bloqueo o accidente externo en via federal', { status: 'exception', stage: 'exception' }],
+    ['pendiente programacion para salida a ruta (ver fecha programada de entrega )', { status: 'in_transit', stage: 'in_transit' }],
+]);
+export function estafetaStatus(wording) {
+    const normalized = estafetaWording(wording);
+    if (/^.+ llegada a centro operativo plaza destino$/.test(normalized))
+        return { status: 'in_transit', stage: 'in_transit' };
+    return WORDINGS.get(normalized);
+}

package/dist/carriers/estafeta/statuses.json

@@ -0,0 +1,47 @@
+{
+  "carrier": "estafeta",
+  "entries": [
+    {
+      "wording": "Entregado",
+      "language": "es",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "En proceso de entrega a domicilio",
+      "language": "es",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "En tránsito",
+      "language": "es",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "Recibido por estafeta",
+      "language": "es",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "CARGA DEMORADA POR BLOQUEO O ACCIDENTE EXTERNO EN VIA FEDERAL",
+      "language": "es",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "Guadalajara Centro Llegada a centro Operativo plaza Destino",
+      "language": "es",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "wording": "Pendiente programacion para salida a ruta (Ver fecha programada de entrega )",
+      "language": "es",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    }
+  ]
+}

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

@@ -0,0 +1,14 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeEvriNumber(raw: string): string;
+/** Parse only the response to this reference's POST; empty results carry no identifier. */
+export declare function parse(html: string, trackingNumber: string): CarrierResult;
+export declare class EvriTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;