universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/evri/adapter.js

@@ -0,0 +1,146 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { ChallengeError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
+import { evriStatus } from './status.js';
+const PROVIDER = 'Evri International';
+// The international tracker linked by https://www.evri.com/track-a-parcel.
+// It is separate from the domestic UK customer-tracking API.
+const ENDPOINT = 'https://globaleco.app/track';
+const MAX_RESPONSE_BYTES = 1_000_000;
+export function normalizeEvriNumber(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^[A-Z0-9]{16}$/.test(number)) {
+        throw new InputRequiredError(PROVIDER, 'number', 'Evri requires a 16-character tracking number');
+    }
+    return number;
+}
+function wallTime(raw) {
+    if (!/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(raw))
+        throw new SchemaError(PROVIDER, 'Evri returned an invalid event date');
+    // Validate calendar values without claiming that the provider's international
+    // wall clocks are UTC, or assigning one country's timezone to another leg.
+    const date = DateTime.fromFormat(raw, 'yyyy-MM-dd HH:mm:ss', { zone: 'UTC' });
+    if (!date.isValid)
+        throw new SchemaError(PROVIDER, 'Evri returned an invalid event date');
+    return date.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+/** Parse only the response to this reference's POST; empty results carry no identifier. */
+export function parse(html, trackingNumber) {
+    const number = normalizeEvriNumber(trackingNumber);
+    const $ = load(html);
+    if (/just a moment|verify.*human|captcha/i.test($('title').text())
+        || $('.g-recaptcha, .h-captcha, input[name="captcha"]').length)
+        throw new ChallengeError(PROVIDER);
+    $('script, style, noscript').remove();
+    const form = $('main form[action="/track"][method="POST"]');
+    const headings = $('main h2');
+    const detailsHeading = headings.filter((_, heading) => clean($(heading).text()).startsWith('Shipment Details #'));
+    const historyHeading = headings.filter((_, heading) => clean($(heading).text()) === 'Shipment History');
+    const input = form.find('input[name="tracking_number"]');
+    // GlobalEco clears the form input for not-found. The exact POST scopes this
+    // negative outcome; reject a nonempty input that names a different parcel.
+    if (!detailsHeading.length && !historyHeading.length && form.length === 1
+        && input.length === 1 && ['', number].includes(input.attr('value') ?? '!')
+        && headings.filter((_, heading) => clean($(heading).text()) === 'Parcel not found').length === 1) {
+        throw new NotFoundError(PROVIDER);
+    }
+    if (detailsHeading.length !== 1 || historyHeading.length !== 1) {
+        throw new SchemaError(PROVIDER, 'Evri returned missing or ambiguous shipment details');
+    }
+    const details = detailsHeading.closest('.card');
+    const fields = new Map();
+    details.find('.form-group').each((_, field) => {
+        const label = $(field).children('strong');
+        if (label.length !== 1)
+            throw new SchemaError(PROVIDER, 'Evri returned invalid shipment details');
+        const key = clean(label.text());
+        if (fields.has(key))
+            throw new SchemaError(PROVIDER, 'Evri returned ambiguous shipment details');
+        fields.set(key, clean($(field).clone().children('strong').remove().end().text(), 250));
+    });
+    // The form input can contain a partner alias instead of the submitted barcode.
+    // Bind to both independent result fields, never the echoed search input.
+    if (clean(detailsHeading.text()) !== `Shipment Details #${number}` || fields.get('System Tracking:') !== number) {
+        throw new SchemaError(PROVIDER, 'Evri returned a different shipment');
+    }
+    const history = historyHeading.closest('.card');
+    const table = history.find('table');
+    if (details[0] === history[0] || table.length !== 1
+        || table.find('thead th').map((_, cell) => clean($(cell).text())).get().join('|') !== 'Date/Time|Event|Location|Comments') {
+        throw new SchemaError(PROVIDER, 'Evri returned an invalid history table');
+    }
+    const rows = table.find('tbody > tr');
+    if (!rows.length || rows.length > 500)
+        throw new SchemaError(PROVIDER, 'Evri returned incomplete tracking history');
+    const events = [];
+    const seen = new Set();
+    for (const row of rows.toArray()) {
+        const cells = $(row).children('td');
+        if (cells.length !== 4 || cells.filter('[colspan], [rowspan]').length)
+            throw new SchemaError(PROVIDER, 'Evri returned an invalid event row');
+        const time = wallTime(clean(cells.eq(0).text(), 64));
+        const description = clean(cells.eq(1).text(), 500);
+        const location = clean(cells.eq(2).text(), 200);
+        if (!description)
+            throw new SchemaError(PROVIDER, 'Evri returned an empty event');
+        const key = JSON.stringify([time, description, location]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const status = evriStatus(description);
+        events.push({ local_time: time, description, ...(location ? { location } : {}), ...(status ? { stage: status.stage } : {}) });
+    }
+    // Already newest-first on the portal. Do not sort local clocks across legs.
+    const latest = events[0];
+    const description = fields.get('Current Status:');
+    if (!description)
+        throw new SchemaError(PROVIDER, 'Evri returned no current status');
+    const status = evriStatus(description);
+    const weight = /^(\d+(?:\.\d+)?)\s*kg$/.exec(fields.get('Weight:') ?? '');
+    const weightKg = weight ? Number(weight[1]) : NaN;
+    return {
+        status: status?.status ?? 'unknown', ...(status ? { current_stage: status.stage } : {}),
+        last_status_text: description, last_update: null, last_update_local: latest.local_time, expected_delivery: null,
+        ...(Number.isFinite(weightKg) && weightKg > 0 ? { weight_kg: weightKg } : {}),
+        events: events.slice(0, 100),
+    };
+}
+export class EvriTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeEvriNumber(raw);
+        const budgetMs = context.budgetMs ?? this.options.timeoutMs ?? 15_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('Evri timeout must be positive');
+        context.signal?.throwIfAborted();
+        try {
+            const { bytes } = await fetchBounded(ENDPOINT, {
+                method: 'POST', headers: { Accept: 'text/html', 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ tracking_number: number }).toString(),
+            }, {
+                provider: PROVIDER, maxBytes: MAX_RESPONSE_BYTES, timeoutMs: Math.max(1, Math.floor(budgetMs)),
+                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(decodeText(bytes), number);
+        }
+        catch (error) {
+            // Missing parcels use HTTP 200 with the exact result heading above.
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                throw new TransportError(PROVIDER, 'Evri International tracking endpoint is unavailable', { cause: error });
+            }
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new EvriTracker({ fetcher: environment.fetcher });
+    return { id: 'evri', steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/evri/carrier.json

@@ -0,0 +1,69 @@
+{
+  "id": "evri",
+  "displayName": "Evri",
+  "aliases": [
+    "Hermes UK"
+  ],
+  "region": {
+    "countries": [
+      "GB"
+    ]
+  },
+  "brand": {
+    "color": "#00014d"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "evri",
+    "upstreamName": "Evri International",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "weight"
+  ],
+  "portal": {
+    "url": "https://www.evri.com/track-a-parcel",
+    "canaryUrl": "https://globaleco.app/track/",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "weight",
+      "sender_name",
+      "destination",
+      "comments",
+      "tracking_alias"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "weight"
+    ],
+    "discarded": [
+      "sender_name",
+      "destination",
+      "comments",
+      "tracking_alias"
+    ],
+    "unavailable": [
+      "eta",
+      "provider_code"
+    ]
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "evri-1",
+      "pattern": "^H[A-Z0-9]{15}$",
+      "confidence": "high"
+    }
+  ]
+}

package/dist/carriers/evri/numbers.json

@@ -0,0 +1,32 @@
+{
+  "carrier": "evri",
+  "records": [
+    {
+      "number": "H0595C0000314450",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://ie.trustpilot.com/reviews/6a0adb5e679c6b7f4d03ee29",
+        "date": "2026-05-18"
+      },
+      "expect": {
+        "carrier": "evri",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. Evri International parcel."
+    },
+    {
+      "number": "H06R4A1011299623",
+      "role": "shipment",
+      "evidence": "merchant_published_example",
+      "source": {
+        "url": "https://wobaaa.com/aliexpress-uk-tracking-numbers/"
+      },
+      "expect": {
+        "carrier": "evri",
+        "confidence": "high"
+      },
+      "note": "Published integration example, not a real shipment."
+    }
+  ]
+}

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

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

package/dist/carriers/evri/status.js

@@ -0,0 +1,24 @@
+// Exact English event labels from the official GlobalEco international portal.
+// Evidence for observed versus synthetic boundaries lives in statuses.json.
+const STATUSES = {
+    'created': { status: 'pending', stage: 'registered' },
+    'received at evri': { status: 'in_transit', stage: 'accepted' },
+    'accepted': { status: 'in_transit', stage: 'accepted' },
+    'consolidated': { status: 'in_transit', stage: 'in_transit' },
+    'processed at export gateway': { status: 'in_transit', stage: 'in_transit' },
+    'cross docked': { status: 'in_transit', stage: 'in_transit' },
+    'in transit': { status: 'in_transit', stage: 'in_transit' },
+    'in customs': { status: 'in_transit', stage: 'customs' },
+    'customs cleared': { status: 'in_transit', stage: 'in_transit' },
+    'at the local depot': { status: 'in_transit', stage: 'in_transit' },
+    'delivery attempted': { status: 'exception', stage: 'failed_attempt' },
+    'carrier label error': { status: 'exception', stage: 'exception' },
+    'out for delivery': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'ready for collection': { status: 'in_transit', stage: 'ready_for_pickup' },
+    'delivered': { status: 'delivered', stage: 'delivered' },
+    'returned to sender': { status: 'exception', stage: 'returned' },
+};
+export function evriStatus(wording) {
+    const key = wording.trim().toLowerCase();
+    return Object.hasOwn(STATUSES, key) ? STATUSES[key] : undefined;
+}

package/dist/carriers/evri/statuses.json

@@ -0,0 +1,133 @@
+{
+  "carrier": "evri",
+  "entries": [
+    {
+      "wording": "Created",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Received at Evri",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Accepted",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Consolidated",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Processed at Export Gateway",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Cross Docked",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "In transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "In customs",
+      "language": "en",
+      "stage": "customs",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Customs cleared",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "At the local depot",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Delivery Attempted",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Carrier label error",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-26",
+      "note": "Exact GlobalEco international event label."
+    },
+    {
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-26",
+      "note": "Synthetic semantic boundary; not observed in the live reference."
+    },
+    {
+      "wording": "Ready for collection",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-26",
+      "note": "Synthetic semantic boundary; not observed in the live reference."
+    },
+    {
+      "wording": "Delivered",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-26",
+      "note": "Synthetic semantic boundary; not observed in the live reference."
+    },
+    {
+      "wording": "Returned to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "fixture",
+      "firstSeen": "2026-09-26",
+      "note": "Synthetic semantic boundary; not observed in the live reference."
+    }
+  ]
+}

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

@@ -0,0 +1,32 @@
+import type { AdapterFactory } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+import { TrawlClient } from '../../core/transport/index.js';
+export declare function normalizeFedExTrackingNumber(raw: string): string;
+export declare function fedexTrackingUrl(trackingNumber: string): string;
+/** The structured answer of the tracking page's own API call. */
+export declare function parseFedExTrackingResponse(payload: unknown, trackingNumber: string): CarrierResult;
+/**
+ * The page the browser rendered, read only to tell a bot challenge from an
+ * inconclusive load. The page renders its "can't find that tracking number"
+ * notice both for unknown numbers and for tracking calls the edge refused,
+ * so rendered text never decides not-found: only the structured reply does.
+ */
+export declare function parseFedExTrackingHtml(page: string): 'challenged' | 'inconclusive';
+export interface FedExTrackerOptions {
+    timeoutMs?: number;
+    /** Legacy configuration seam; `trawl` is preferred. */
+    trawlUrl?: string;
+    /** The browser service, or null when none is configured. */
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class FedExTracker {
+    #private;
+    readonly timeoutMs: number;
+    readonly trawlUrl: string;
+    constructor(options?: FedExTrackerOptions);
+    fetch(trackingNumber: string): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;