universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/ecoscooting/statuses.json

@@ -0,0 +1,295 @@
+{
+  "carrier": "ecoscooting",
+  "entries": [
+    {
+      "code": "GTMS_SIGNED",
+      "wording": "Parcel has been delivered successfully",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_PUDO_SIGNED",
+      "wording": "Your shipment has been collected by consignee at the parcelshop",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_STA_SIGNED",
+      "wording": "Delivered to PUDO",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "note": "The pickup point signed for the parcel, not the recipient."
+    },
+    {
+      "code": "GTMS_PUDO_INBOUND",
+      "wording": "Your shipment has arrived at parcelshop and you‘ll receive pickup instructions shortly",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_PUDO_OVERDUE",
+      "wording": "Exceeded pickup time",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "bundle",
+      "note": "Ecoscooting's web client shows this headline for the code; the reply's own wording was not seen."
+    },
+    {
+      "code": "GTMS_SIGN_FAILURE",
+      "wording": "Parcel will be returned to the origin",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_SIGNIN_SUCCESS",
+      "wording": "Parcel has been returned back to the sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_DO_DEPART",
+      "wording": "Return Outbound",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_DO_ARRIVE",
+      "wording": "Return Inbound",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_WH_OUTBOUND",
+      "wording": "Return outbound: parcel outbound from sorting center",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_WH_INBOUND",
+      "wording": "Return inbound: parcel received in sorting center",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_DO_DEPART",
+      "wording": "Out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_DEL_FAILURE",
+      "wording": "Delivery Attempt Failure",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "GTMS_ACCEPT",
+      "wording": "Parcel has been accepted by last mile",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "TD_TRANSWH_OUTBOUND",
+      "wording": "Parcels outbound from sorting center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "TD_TRANS_ARRIVE_C",
+      "wording": "Parcel arrives at sorting center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "In_transit",
+      "wording": "Shipment is in transit to Cainiao Express",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "Partner_outbound",
+      "wording": "Shipment has left Cainiao Express's partner facility",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "create",
+      "wording": "Shipment order created",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "Label_created",
+      "wording": "Shipment data information received",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "LM_SIGN_SUCCESS",
+      "wording": "Your shipment has been delivered successfully",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "PUDO_SIGN_SUCCESS",
+      "wording": "Your shipment has been collected by consignee at the parcelshop",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "PUDO_DELIVERY",
+      "wording": "Delivered to PUDO",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live",
+      "note": "The pickup point signed for the parcel, not the recipient."
+    },
+    {
+      "code": "PUDO_INBOUND",
+      "wording": "Your shipment has arrived at parcelshop and you‘ll receive pickup instructions shortly",
+      "language": "en",
+      "stage": "ready_for_pickup",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "PUDO_OVERDUE",
+      "wording": "Your shipment has expired at the parcelshop, and will be returned to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "LM_UNREACHABLE_RETURN",
+      "wording": "Your shipment will be returned to its origin",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_LM_SIGN_SUCCESS",
+      "wording": "Your shipment has been returned successfully to sender",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_LM_DELIVERY_DEPART",
+      "wording": "Your return shipment is out for delivery",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_LM_DELIVERY_ARRIVE",
+      "wording": "Your return shipment arrived at last mile station",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_SC_OUTBOUND",
+      "wording": "Your return shipment has been processed at sorting center and ready for shipping",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "RT_SC_INBOUND",
+      "wording": "Your return shipment arrived at sorting center",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "LM_DELIVERY_DEPART",
+      "wording": "Your shipment is out for delivery",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "LM_DELIVERY_FAILURE",
+      "wording": "Delivery Attempt Failure",
+      "language": "en",
+      "stage": "failed_attempt",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "LM_PARCEL_EXCEPTION",
+      "wording": "Your shipment has encountered an exception at last mile station",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "SL_ACCEPT",
+      "wording": "Your shipment has been accepted by delivery carrier",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "TRANSFER_ARRIVE",
+      "wording": "Your shipment has arrived at the transit destination",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "TRANSFER_DEPART",
+      "wording": "Your shipment has departed from the transit origin",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "SC_OUTBOUND",
+      "wording": "Your shipment has been processed at sorting center and ready for shipping",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "SC_INBOUND",
+      "wording": "Your shipment has arrived at sorting center",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "PU_PICKUP_SUCCESS",
+      "wording": "Shipment picked up by carrier",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live"
+    },
+    {
+      "code": "CREATE_ORDER_CES",
+      "wording": "Shipment order created",
+      "language": "en",
+      "stage": "registered",
+      "confirmedBy": "live"
+    }
+  ]
+}

package/dist/carriers/ems/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 normalizeEmsTrackingNumber(raw: string): string;
+/** Project only the requested result table; form inputs and other items prove nothing. */
+export declare function parse(html: string, trackingNumber: string): CarrierResult;
+export declare class EmsTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        timeoutMs?: number;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/ems/adapter.js

@@ -0,0 +1,124 @@
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import { isValidS10TrackingNumber, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { ChallengeError, InputRequiredError, NotFoundError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { clean, decodeText, fetchBounded } from '../../core/transport/index.js';
+import { emsStatus } from './status.js';
+const ENDPOINT = 'https://items.ems.post/api/publicTracking/track';
+const TIMEOUT_MS = 15_000;
+const MAX_RESPONSE_BYTES = 1_000_000;
+// A fresh request with this ordinary browser header works without session state.
+const USER_AGENT = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/153.0.0.0 Safari/537.36';
+export function normalizeEmsTrackingNumber(raw) {
+    const number = normalizeTrackingNumber(raw);
+    if (!/^E[A-Z]\d{9}[A-Z]{2}$/.test(number) || !isValidS10TrackingNumber(number)) {
+        throw new InputRequiredError('EMS', 'number', 'EMS requires a valid E-prefixed postal tracking number');
+    }
+    return number;
+}
+function wallTime(raw) {
+    // UTC is used only to validate calendar fields. The portal supplies no zone;
+    // never emit a fabricated offset or reorder cross-border scans by wall time.
+    const parsed = DateTime.fromFormat(raw, 'LLL d, yyyy, h:mm a', { locale: 'en-US', zone: 'UTC' });
+    if (!parsed.isValid)
+        throw new SchemaError('EMS', 'EMS returned an invalid event date');
+    return parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+/** Project only the requested result table; form inputs and other items prove nothing. */
+export function parse(html, trackingNumber) {
+    const number = normalizeEmsTrackingNumber(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('EMS');
+    $('script, style, noscript').remove();
+    const result = $('.result-table').filter((_, element) => $(element).attr('id') === `table-${number}`);
+    if (result.length !== 1)
+        throw new SchemaError('EMS', 'EMS returned a different or ambiguous shipment');
+    if (result.find('.error').length) {
+        if (/does not denote an EMS item\./.test(result.find('.error').text())) {
+            throw new InputRequiredError('EMS', 'number', 'EMS does not support this postal service');
+        }
+        throw new SchemaError('EMS', 'EMS could not complete the tracking query');
+    }
+    const table = result.children('table');
+    const headers = table.find('thead th').map((_, cell) => clean($(cell).text())).get();
+    if (table.length !== 1 || headers.join('|') !== 'Date and time|Status of Item|Location') {
+        throw new SchemaError('EMS', 'EMS returned an invalid tracking table');
+    }
+    const rows = table.find('tbody > tr');
+    const noResults = rows.find('td.no-results-found');
+    if (rows.length === 1 && rows.children('td').length === 1 && noResults.length === 1
+        && clean(noResults.text()) === 'There were no results found.')
+        throw new NotFoundError('EMS');
+    if (rows.length === 0 || rows.length > 500 || noResults.length)
+        throw new SchemaError('EMS', 'EMS returned incomplete tracking history');
+    const events = [];
+    const seen = new Set();
+    // EMS presents oldest first. Reversal preserves its sequence for equal times
+    // and for international legs whose local clocks cannot be compared safely.
+    for (const row of rows.toArray().reverse()) {
+        const cells = $(row).children('td');
+        if (cells.length !== 3 || cells.filter('[colspan]').length)
+            throw new SchemaError('EMS');
+        const description = clean(cells.eq(1).text(), 500);
+        if (!description)
+            throw new SchemaError('EMS', 'EMS returned an empty event');
+        const time = wallTime(clean(cells.eq(0).text(), 64));
+        const location = clean(cells.eq(2).text(), 200);
+        const key = JSON.stringify([time, description, location]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const status = emsStatus(description);
+        events.push({ local_time: time, description, location, ...(status ? { stage: status.stage } : {}) });
+    }
+    const latest = events[0];
+    const status = emsStatus(latest.description);
+    return {
+        status: status?.status ?? 'unknown',
+        ...(status ? { current_stage: status.stage } : {}),
+        last_status_text: latest.description,
+        last_update: null,
+        last_update_local: latest.local_time,
+        expected_delivery: null,
+        events: events.slice(0, 100),
+    };
+}
+export class EmsTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeEmsTrackingNumber(raw);
+        const budgetMs = context.budgetMs ?? this.options.timeoutMs ?? TIMEOUT_MS;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
+            throw new TypeError('EMS timeout must be positive');
+        context.signal?.throwIfAborted();
+        const url = `${ENDPOINT}?${new URLSearchParams({ language: 'EN', itemId: number })}`;
+        try {
+            const { bytes } = await fetchBounded(url, { headers: { 'User-Agent': USER_AGENT } }, {
+                provider: 'EMS', 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) {
+            // Unknown items use HTTP 200 + a specific table row. A missing endpoint
+            // must not make routing conclude that the parcel does not exist.
+            if (error instanceof UpstreamHttpError && [404, 410].includes(error.status)) {
+                throw new TransportError('EMS', 'EMS tracking endpoint is unavailable', { cause: error });
+            }
+            throw error;
+        }
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new EmsTracker({ fetcher: environment.fetcher });
+    return { id: 'ems', steps: ['direct'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/ems/carrier.json

@@ -0,0 +1,61 @@
+{
+  "id": "ems",
+  "displayName": "EMS",
+  "aliases": [
+    "Express Mail Service",
+    "EMS Post"
+  ],
+  "region": {
+    "countries": []
+  },
+  "brand": {
+    "color": "#003b7a"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ems",
+    "steps": [
+      "direct"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://items.ems.post/api/publicTracking/track?language=EN&itemId={trackingNumber}",
+    "canaryUrl": "https://items.ems.post/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [],
+    "unavailable": [
+      "eta",
+      "weight",
+      "sender_name",
+      "pickup_point"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "items.ems.post"
+      ],
+      "pathPattern": "^/api/publicTracking/track/?$",
+      "params": [
+        "itemId"
+      ]
+    }
+  ],
+  "detection": []
+}

package/dist/carriers/ems/numbers.json

@@ -0,0 +1,43 @@
+{
+  "carrier": "ems",
+  "records": [
+    {
+      "number": "EB000000005CN",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "observed_request",
+      "shapeConfirmed": "2026-09-21",
+      "expect": {
+        "carrier": "china-post",
+        "confidence": "high"
+      },
+      "note": "Synthetic EMS S10 identifier; bare numbers retain their national postal operator, while an EMS link or manual selection chooses EMS."
+    },
+    {
+      "number": "EB865157741CN",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.chinapostaltracking.com/qa/package-stuck-export-customskeep-pending-inspection-161051/",
+        "date": "2026-09-16"
+      },
+      "expect": {
+        "carrier": "china-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source calls it a China Post EMS parcel; detection selects China Post."
+    },
+    {
+      "number": "EW000000005FR",
+      "role": "shipment",
+      "evidence": "synthetic",
+      "derivedFrom": "observed_request",
+      "shapeConfirmed": "2026-09-21",
+      "expect": {
+        "carrier": "la-poste",
+        "confidence": "high"
+      },
+      "note": "Synthetic second EMS origin; selecting EMS does not reassign French postal number detection."
+    }
+  ]
+}

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

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

package/dist/carriers/ems/status.js

@@ -0,0 +1,24 @@
+// English labels from the EMS Cooperative public table. Observed vocabulary
+// and separately reconstructed terminal examples are recorded in statuses.json.
+const STATUS = new Map([
+    ['Posted', { status: 'in_transit', stage: 'accepted' }],
+    ['Arrived at export office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Presented to export customs and security', { status: 'in_transit', stage: 'customs' }],
+    ['Released from export customs and security', { status: 'in_transit', stage: 'in_transit' }],
+    ['Departed from export office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Held for export customs inspection', { status: 'in_transit', stage: 'customs' }],
+    ['Export cancelled', { status: 'exception', stage: 'exception' }],
+    ['Arrived at destination import office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Held at destination import office', { status: 'in_transit', stage: 'customs' }],
+    ['Presented to import customs', { status: 'in_transit', stage: 'customs' }],
+    ['Released from import customs', { status: 'in_transit', stage: 'in_transit' }],
+    ['Departed from destination import office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Arrived at post office', { status: 'in_transit', stage: 'in_transit' }],
+    ['Out for delivery', { status: 'out_for_delivery', stage: 'out_for_delivery' }],
+    ['Delivered', { status: 'delivered', stage: 'delivered' }],
+    ['Delivery attempted', { status: 'exception', stage: 'failed_attempt' }],
+    ['Returned to sender', { status: 'exception', stage: 'returned' }],
+]);
+export function emsStatus(description) {
+    return STATUS.get(description);
+}