universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/carriers/tnt/carrier.json

@@ -0,0 +1,66 @@
+{
+  "id": "tnt",
+  "displayName": "TNT",
+  "aliases": [],
+  "region": {
+    "countries": []
+  },
+  "brand": {
+    "color": "#ff6600"
+  },
+  "selectable": true,
+  "timezone": "Europe/Paris",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "tnt",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 44
+    }
+  },
+  "capabilities": [
+    "history",
+    "location",
+    "eta",
+    "provider_code"
+  ],
+  "portal": {
+    "url": "https://www.tnt.com/express/en_gb/site/shipping-tools/tracking.html?searchType=con&cons={trackingNumber}",
+    "canaryUrl": "https://www.tnt.fr/public/suivi_colis/recherche/index.do",
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "customer_reference",
+      "signature"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "eta",
+      "provider_code"
+    ],
+    "discarded": [
+      "customer_reference",
+      "signature"
+    ],
+    "unavailable": []
+  },
+  "links": [],
+  "detection": [
+    {
+      "id": "tnt-1",
+      "pattern": "^\\d{9}$",
+      "confidence": "low"
+    },
+    {
+      "id": "tnt-2",
+      "pattern": "^\\d{16}$",
+      "confidence": "low"
+    }
+  ]
+}

package/dist/carriers/tnt/numbers.json

@@ -0,0 +1,116 @@
+{
+  "carrier": "tnt",
+  "records": [
+    {
+      "number": "1319298002846673",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a58c1f15d75ae6cf50b8bf7",
+        "date": "2026-07-16"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to TNT France, which stays one candidate among several."
+    },
+    {
+      "number": "1320002490250705",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6a636f2d0801a8c8be5d2c1b",
+        "date": "2026-07-24"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dhl-ecommerce",
+          "correos-express",
+          "canada-post",
+          "tnt"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to TNT France, which stays one candidate among several."
+    },
+    {
+      "number": "211691259",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to TNT, which stays one candidate among several."
+    },
+    {
+      "number": "928567507",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "tnt"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to TNT, which stays one candidate among several."
+    },
+    {
+      "number": "1158418300904",
+      "role": "quarantined",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to TNT, which no rule claims."
+    },
+    {
+      "number": "MY33217326",
+      "role": "quarantined",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://gist.github.com/zxp/e83a4a1b7294a5ed6207",
+        "date": "2015-08-29"
+      },
+      "quarantine": true,
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to TNT; no rule matches this shape."
+    }
+  ]
+}

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

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

package/dist/carriers/tnt/status.js

@@ -0,0 +1,35 @@
+const STATUS = {
+    "colis chez l'expéditeur": { status: 'pending', stage: 'registered' },
+    'en attente': { status: 'pending', stage: 'registered' },
+    'ramassage du colis': { status: 'in_transit', stage: 'accepted' },
+    'acheminement': { status: 'in_transit', stage: 'in_transit' },
+    "en cours d'acheminement": { status: 'in_transit', stage: 'in_transit' },
+    'livraison en cours': { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    'livré': { status: 'delivered', stage: 'delivered' },
+    'incident de livraison': { status: 'exception', stage: 'exception' },
+    "en attente d'instructions": { status: 'exception', stage: 'exception' },
+};
+export function tntFranceStatus(text) {
+    return STATUS[text.toLocaleLowerCase('fr-FR').replaceAll('’', "'")];
+}
+// tnt.com scan codes (`legacyCode`). The wording is prose and changes with the
+// locale; "partially delivered" must not read as a delivery.
+const EXPRESS_CODES = {
+    PU: { status: 'in_transit', stage: 'accepted' },
+    CI: { status: 'in_transit', stage: 'in_transit' },
+    TR: { status: 'in_transit', stage: 'in_transit' },
+    OS: { status: 'in_transit', stage: 'in_transit' },
+    IS: { status: 'in_transit', stage: 'in_transit' },
+    HW: { status: 'in_transit', stage: 'in_transit' },
+    AS: { status: 'in_transit', stage: 'in_transit' },
+    IR: { status: 'in_transit', stage: 'in_transit' },
+    OD: { status: 'out_for_delivery', stage: 'out_for_delivery' },
+    OK: { status: 'delivered', stage: 'delivered' },
+    LP: { status: 'exception', stage: 'exception' },
+    MR: { status: 'exception', stage: 'exception' },
+    WL: { status: 'exception', stage: 'exception' },
+    RTS: { status: 'exception', stage: 'returned' },
+};
+export function tntExpressStatus(code) {
+    return Object.hasOwn(EXPRESS_CODES, code) ? EXPRESS_CODES[code] : undefined;
+}

package/dist/carriers/tnt/statuses.json

@@ -0,0 +1,126 @@
+{
+  "carrier": "tnt",
+  "entries": [
+    {
+      "wording": "Colis chez l'expéditeur",
+      "language": "fr",
+      "stage": "registered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28",
+      "note": "National tracking history label; future rail labels are not events."
+    },
+    {
+      "code": "PU",
+      "wording": "Shipment collected from collection address",
+      "language": "en",
+      "stage": "accepted",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "CI",
+      "wording": "Shipment now at the depot nearest to collection address",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "TR",
+      "wording": "Shipment in transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "OS",
+      "wording": "Shipment in transit",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "IS",
+      "wording": "Shipment arrived at connection point",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "HW",
+      "wording": "Shipment arrived at TNT location",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "AS",
+      "wording": "Shipment being processed at TNT location.",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "IR",
+      "wording": "Shipment now at depot nearest to delivery address",
+      "language": "en",
+      "stage": "in_transit",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "OD",
+      "wording": "Shipment is out for delivery.",
+      "language": "en",
+      "stage": "out_for_delivery",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "OK",
+      "wording": "Shipment delivered in good condition",
+      "language": "en",
+      "stage": "delivered",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "LP",
+      "wording": "Shipment partially delivered. Recovery actions underway",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28",
+      "note": "Only part of the consignment arrived; the shared wording rules would read a delivery."
+    },
+    {
+      "code": "MR",
+      "wording": "Delay due to routing error. We're working hard to deliver on time.",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "WL",
+      "wording": "Delay due to routing error. Recovery actions underway",
+      "language": "en",
+      "stage": "exception",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    },
+    {
+      "code": "RTS",
+      "wording": "Returned to sender as agreed",
+      "language": "en",
+      "stage": "returned",
+      "confirmedBy": "live",
+      "firstSeen": "2026-09-28"
+    }
+  ]
+}

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

@@ -0,0 +1,13 @@
+import type { AdapterFactory, TrackingContext } from '../../core/adapter/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare const UKRPOSHTA_API = "https://track.ukrposhta.ua/php/track_new.php";
+export declare function ukrposhtaTrackingUrl(number: string): string;
+export declare class UkrposhtaTracker {
+    private readonly options;
+    constructor(options?: {
+        executablePath?: string | null;
+        recorder?: StepRecorder;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<import("../../index.js").CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/ukrposhta/adapter.js

@@ -0,0 +1,152 @@
+import { loadChromium } from '../../core/transport/optional.js';
+import { BudgetExceededError, ChallengeError, SchemaError, TransportError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { isRecord } from '../../core/types.js';
+import { normalizeUkrposhtaNumber, parseUkrposhtaHistory, parseUkrposhtaOverview } from './parser.js';
+export const UKRPOSHTA_API = 'https://track.ukrposhta.ua/php/track_new.php';
+const MAX_BYTES = 1_000_000;
+let browserBusy = false;
+export function ukrposhtaTrackingUrl(number) {
+    const url = new URL('https://track.ukrposhta.ua/en/');
+    url.searchParams.set('barcode', number);
+    return url.toString();
+}
+function httpFailure(status, retryAfterMs) {
+    const cause = new UpstreamHttpError('ukrposhta', status, retryAfterMs);
+    return [404, 410].includes(status)
+        ? new TransportError('ukrposhta', 'Ukrposhta tracking endpoint is unavailable', { cause, status }) : cause;
+}
+function requestMatches(response, page, number) {
+    const request = response.request();
+    let body;
+    try {
+        body = request.postDataJSON();
+    }
+    catch {
+        return false;
+    }
+    return response.url() === UKRPOSHTA_API && request.method() === 'POST'
+        && request.frame() === page.mainFrame() && isRecord(body) && body.barcode === number && body.lang === 'EN';
+}
+async function readLookup(page, number, deadline, signal, budgetMs) {
+    signal.throwIfAborted();
+    const remainingMs = Math.floor(deadline - performance.now());
+    if (remainingMs <= 0)
+        throw new BudgetExceededError('ukrposhta', budgetMs);
+    const captured = page.waitForResponse(response => response.url() === UKRPOSHTA_API && response.request().method() === 'POST', { timeout: remainingMs });
+    void captured.catch(() => { });
+    const navigation = await page.goto(ukrposhtaTrackingUrl(number), { waitUntil: 'domcontentloaded', timeout: remainingMs });
+    signal.throwIfAborted();
+    if (!navigation)
+        throw new TransportError('ukrposhta', 'Ukrposhta tracking page is unavailable');
+    if ([401, 403].includes(navigation.status()))
+        throw new ChallengeError('ukrposhta');
+    if (navigation.status() !== 200)
+        throw httpFailure(navigation.status());
+    const response = await captured;
+    signal.throwIfAborted();
+    if (!requestMatches(response, page, number))
+        throw new SchemaError('ukrposhta', 'The browser submitted a different tracking request');
+    if ([401, 403].includes(response.status()))
+        throw new ChallengeError('ukrposhta');
+    if (response.status() !== 200) {
+        const retryAfter = response.headers()['retry-after'];
+        const retryAfterMs = retryAfter && /^\d+$/.test(retryAfter) ? Number(retryAfter) * 1_000 : undefined;
+        throw httpFailure(response.status(), retryAfterMs);
+    }
+    if (Number(response.headers()['content-length']) > MAX_BYTES)
+        throw new SchemaError('ukrposhta', 'Ukrposhta returned excessive tracking data');
+    const bytes = await response.body();
+    signal.throwIfAborted();
+    if (bytes.length > MAX_BYTES)
+        throw new SchemaError('ukrposhta', 'Ukrposhta returned excessive tracking data');
+    try {
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch (cause) {
+        throw new SchemaError('ukrposhta', 'Ukrposhta returned invalid tracking JSON', { cause });
+    }
+}
+async function localBrowser(number, executablePath, signal, timeoutMs) {
+    signal.throwIfAborted();
+    if (browserBusy)
+        throw new TransportError('ukrposhta', 'The Ukrposhta tracking browser is busy');
+    browserBusy = true;
+    const deadline = performance.now() + timeoutMs;
+    let browser;
+    let launching;
+    let closing;
+    const close = () => {
+        if (browser && !closing)
+            closing = browser.close();
+        return closing ?? Promise.resolve();
+    };
+    let rejectAbort;
+    const aborted = new Promise((_, reject) => { rejectAbort = reject; });
+    void aborted.catch(() => { });
+    const abort = () => { rejectAbort(signal.reason); void close().catch(() => { }); };
+    signal.addEventListener('abort', abort, { once: true });
+    try {
+        launching = (await loadChromium("Ukrposhta")).launch({ executablePath, headless: true, timeout: Math.min(timeoutMs, 10_000),
+            env: { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? '/tmp', LANG: 'en_US.UTF-8' } });
+        const operation = (async () => {
+            browser = await launching;
+            signal.throwIfAborted();
+            const context = await browser.newContext({ locale: 'en-US', acceptDownloads: false, serviceWorkers: 'block' });
+            signal.throwIfAborted();
+            await context.route('**/*', async (route) => {
+                const url = new URL(route.request().url());
+                const allowed = url.protocol === 'https:' && ['track.ukrposhta.ua', 'www.google.com', 'www.gstatic.com', 'www.recaptcha.net'].includes(url.hostname);
+                await (allowed ? route.continue() : route.abort());
+            });
+            signal.throwIfAborted();
+            const page = await context.newPage();
+            signal.throwIfAborted();
+            // The native repeated-reference batch supplies a barcode-bound latest
+            // scan and total count. Its single-reference mode supplies full history.
+            const overview = parseUkrposhtaOverview(await readLookup(page, `${number},${number}`, deadline, signal, timeoutMs), number);
+            return parseUkrposhtaHistory(await readLookup(page, number, deadline, signal, timeoutMs), overview);
+        })();
+        return await Promise.race([operation, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        if (browser) {
+            try {
+                await close();
+            }
+            finally {
+                browserBusy = false;
+            }
+        }
+        else if (launching) {
+            // Reject the caller promptly, but retain the lock until a launch that
+            // ignored cancellation has resolved and its browser has been closed.
+            void launching.then(async (late) => { browser = late; await close(); }).catch(() => { }).finally(() => { browserBusy = false; });
+        }
+        else
+            browserBusy = false;
+    }
+}
+export class UkrposhtaTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    fetch(raw, context = {}) {
+        const number = normalizeUkrposhtaNumber(raw);
+        const budgetMs = context.budgetMs ?? 45_000;
+        if (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > 60_000)
+            throw new TypeError('Ukrposhta budget must be between 1 and 60000 ms');
+        if (!this.options.executablePath)
+            throw new ChallengeError('ukrposhta', 'Ukrposhta requires a configured tracking browser');
+        return runSteps({ carrier: 'ukrposhta', budgetMs, signal: context.signal, recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'browser', run: ({ signal, remainingMs }) => localBrowser(number, this.options.executablePath, signal, Math.max(1, Math.floor(remainingMs))) },
+        ]);
+    }
+}
+export const adapter = environment => {
+    const tracker = new UkrposhtaTracker({ executablePath: environment.browserExecutablePath, recorder: environment.recorder });
+    return { id: 'ukrposhta', recordsSteps: true, steps: ['browser'], track: (input, context) => tracker.fetch(input.number, context) };
+};

package/dist/carriers/ukrposhta/carrier.json

@@ -0,0 +1,62 @@
+{
+  "id": "ukrposhta",
+  "displayName": "Ukrposhta",
+  "aliases": [],
+  "region": {
+    "countries": [
+      "UA"
+    ]
+  },
+  "brand": {
+    "color": "#ffbe0c"
+  },
+  "selectable": true,
+  "timezone": "UTC",
+  "tracking": {
+    "mode": "automatic",
+    "adapter": "ukrposhta",
+    "steps": [
+      "browser"
+    ],
+    "localClocks": true
+  },
+  "capabilities": [
+    "history",
+    "location"
+  ],
+  "portal": {
+    "url": "https://track.ukrposhta.ua/en/?barcode={trackingNumber}",
+    "canaryUrl": "https://track.ukrposhta.ua/en/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location"
+    ],
+    "discarded": [
+      "postcodes",
+      "query_time",
+      "free_form_details",
+      "delivery_date"
+    ],
+    "unavailable": [
+      "eta",
+      "delivered_at"
+    ]
+  },
+  "links": [
+    {
+      "domains": [
+        "track.ukrposhta.ua"
+      ],
+      "params": [
+        "barcode"
+      ]
+    }
+  ],
+  "detection": []
+}

package/dist/carriers/ukrposhta/numbers.json

@@ -0,0 +1,53 @@
+{
+  "carrier": "ukrposhta",
+  "records": [
+    {
+      "number": "0505683900154",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.vidhuk.ua/uk/ukrposhta-ukrpochta/review-2374754",
+        "date": "2026-09-07"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "low",
+        "candidates": [
+          "dpd-fr",
+          "la-poste",
+          "correos-chile",
+          "delhivery",
+          "yunda"
+        ]
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Ukrposhta, which no rule claims. Domestic parcel."
+    },
+    {
+      "number": "CA315000362UA",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://www.trustpilot.com/reviews/6aae6849e25391667cb34f4b",
+        "date": "2026-09-19"
+      },
+      "expect": {
+        "carrier": "intl-post",
+        "confidence": "high"
+      },
+      "note": "Publicly reported shipment number; the attribution was not independently verified. The source attributes it to Ukrposhta; detection selects the generic postal carrier. Return to China, reviewed on AliExpress's page."
+    },
+    {
+      "number": "RF426331371SG",
+      "role": "shipment",
+      "evidence": "open_source_example",
+      "source": {
+        "url": "https://github.com/kolyabres/ukrposhta-api"
+      },
+      "expect": {
+        "carrier": "singapore-post",
+        "confidence": "high"
+      },
+      "note": "Open-source project example, not a real shipment. The source attributes it to Ukrposhta; detection selects Singapore Post."
+    }
+  ]
+}

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

@@ -0,0 +1,15 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare function normalizeUkrposhtaNumber(raw: string): string;
+/** Validate calendar digits without assigning a timezone to the wall clock. */
+export declare function ukrposhtaWallClock(value: string): string | null;
+export interface UkrposhtaOverview {
+    number: string;
+    count: number;
+    date: string;
+    code: string;
+    label: string;
+    location: string;
+    country: string;
+}
+export declare function parseUkrposhtaOverview(payload: unknown, requested: string): UkrposhtaOverview;
+export declare function parseUkrposhtaHistory(payload: unknown, overview: UkrposhtaOverview): CarrierResult;