universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/providers/parcelsapp/adapter.d.ts

@@ -0,0 +1,23 @@
+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 type { TrawlClient } from '../../core/transport/index.js';
+import { ParcelsAppHttpClient } from './http.js';
+export declare const PARCELSAPP_BUDGET_MS = 45000;
+export declare function parseParcelsAppResponse(payload: unknown, trackingNumber: string, html: string, timezone?: string | null): CarrierResult;
+export declare function parseParcelsAppHtml(html: string, trackingNumber: string, timezone?: string | null): CarrierResult;
+export interface ParcelsAppOptions {
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+    timeoutMs?: number;
+    /** Null runs only the existing browser capture tier. */
+    httpClient?: ParcelsAppHttpClient | null;
+}
+export declare class ParcelsAppTracker {
+    readonly options: ParcelsAppOptions;
+    private readonly http;
+    constructor(options?: ParcelsAppOptions);
+    fetch(trackingNumber: string, budgetMs?: number, postcode?: string | null, timezone?: string | null): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/providers/parcelsapp/adapter.js

@@ -0,0 +1,391 @@
+/**
+ * ParcelsApp (parcelsapp.com), a universal aggregator used as the second
+ * discovery provider.
+ *
+ * Transport: a scoped anonymous POST reproduces the public frontend checksum
+ * and submits the stored delivery postcode. Browser capture remains recovery
+ * for protocol challenges. Numberless direct replies belong to their single
+ * POST; captured replies still require the rendered result's identity.
+ */
+import { load } from 'cheerio';
+import { DateTime } from 'luxon';
+import timers from 'node:timers/promises';
+import { carrierTimezone } from '../../core/catalog/index.js';
+import { brandTimeZones, carrierIdFromName, carrierNameCountryZone } from '../../core/catalog/hints.js';
+import { carrierErrorKind, ChallengeError, IndeterminateError, InputRequiredError, NoHistoryError, SchemaError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { canadaProvinceTimeZone, countryCode, countryTimeZone, mislabeledLocalTime, mislabeledWallTime, regionHasTown, sharedClockZone, timeZoneCountry, usStateTimeZone, } from '../../core/time/index.js';
+import { isRecord } from '../../core/types.js';
+import { capturedBodies, loadCapture } from '../shared/capture.js';
+import { universalCarrierHints } from '../shared/hints.js';
+import { event, isNotice, localEvent, numberOf, result } from '../shared/result.js';
+import { carrierScan, markReturnLeg } from '../shared/scans.js';
+import { PARCELSAPP_API, ParcelsAppHttpClient } from './http.js';
+const SOURCE = 'ParcelsApp';
+const MAX_EVENTS = 1000;
+export const PARCELSAPP_BUDGET_MS = 45_000;
+const DIRECT_BUDGET_MS = 30_000;
+const RETRY_DELAY_MS = 2_000;
+// ParcelsApp's response omits the number. Bind it to the rendered result's
+// tracking-number row, never merely to the input field or the requested URL.
+function parcelsIdentity(html, number) {
+    const $ = load(html);
+    const rows = $('.tracking-info .parcel .parcel-attributes tr').filter((_, row) => $(row).children('td').first().text().trim() === 'Tracking number');
+    return rows.length === 1 && rows.first().children('td').eq(1).text().trim() === number;
+}
+export function parseParcelsAppResponse(payload, trackingNumber, html, timezone = null) {
+    if (!parcelsIdentity(html, numberOf(trackingNumber)))
+        throw new SchemaError(SOURCE, 'ParcelsApp shipment identity missing');
+    return parseHistory(payload, trackingNumber, timezone);
+}
+/**
+ * ParcelsApp's `date` is the scan's local clock, labeled as UTC or shifted
+ * into an offset of its own: a DPD scan at 14:05+02:00 arrives as
+ * "14:05+00:00", a Swiss Post delivery at 11:30 local as "13:30+02:00"
+ * (both shapes checked 2026-09-22). Its UTC digits are re-read in the zone
+ * of the scan's carrier, else its location's country, else the country the
+ * carrier name ends with ("DPD UK"), else, for a scan with no location, the
+ * clock that all catalog networks of a bare brand share at that moment ("DPD
+ * Group": DPD Switzerland and France), else the zone routing passes for the
+ * parcel. Without one it stays as labeled, as it does when the name's
+ * country or the parcel's zone meets a location in another country. TNT's
+ * international scans stay as labeled too: tnt.com gives them offsets, and
+ * ParcelsApp's UTC matches them. So do Asendia USA's, wherever they happened:
+ * their dates are the UTC instants of Asendia's A1 feed, and Swiss Post's own
+ * scans of the same item agree (checked 2026-09-30).
+ */
+function stateCarrierName(payload, state) {
+    const carriers = Array.isArray(payload.carriers) ? payload.carriers : [];
+    return typeof state.carrier === 'number' ? carriers[state.carrier] : undefined;
+}
+// The names ParcelsApp gives Asendia USA's scans.
+const ASENDIA_USA = /^asendia\s+(?:usa|united\s+states)$/i;
+// Carriers whose ParcelsApp dates are a North American scan's local clock:
+// UPS's own instants, FedEx's own page, UniUni's own feed and Ship24's offsets
+// agree once they are read that way (checked 2026-09-30 on US scans; UPS's
+// also in Germany, the Netherlands and Spain). OnTrac's are UTC and
+// Landmark's keep one clock everywhere, so no other carrier gets this step.
+const LOCAL_CLOCK_CARRIERS = /^(?:ups|fedex|uniuni|uni express|easyship)$/i;
+const UNITED_STATES = /^(?:us|usa|united states(?: of america)?)$/i;
+const POSTAL_CODE = /\s*\b(?:\d{5}(?:-\d{4})?|[A-Z]\d[A-Z] ?\d[A-Z]\d)$/i;
+/**
+ * The zone of the US state or Canadian province a location names ("Riverside,
+ * CA, US", "Charlotte, NC", "Linden, NJ 07036", "Scranton PA", "Mississauga,
+ * ON, CA"). It is `certain` when the location names the country, the code is
+ * no country's, or the town lies in that state or province ("Chicago, IL" is
+ * not in Israel); "Atlanta, GA" could still be in Gabon.
+ */
+function regionClock(location) {
+    const parts = location.split(',').map((part) => part.trim()).filter(Boolean);
+    const last = parts.at(-1) ?? '';
+    // "CA" after a province is Canada; after a town it is California.
+    const country = parts.length > 1 && UNITED_STATES.test(last) ? 'US'
+        : (parts.length > 1 && /^canada$/i.test(last)) || (parts.length > 2 && /^ca$/i.test(last)) ? 'CA' : null;
+    if (country)
+        parts.pop();
+    if (parts.length > 1 && !parts.at(-1).replace(POSTAL_CODE, ''))
+        parts.pop();
+    // "Example City, BE, NL": a region, then some other country.
+    if (!country && parts.length > 2 && parts.slice(-2).every((part) => /^[A-Z]{2}$/i.test(part)))
+        return null;
+    const words = (parts.at(-1) ?? '').replace(POSTAL_CODE, '').split(/\s+/);
+    const code = parts.length > 1 || words.length > 1 ? words.at(-1) : '';
+    const town = parts.length > 1 ? parts.at(-2) : words.slice(0, -1).join(' ');
+    const zone = (country === 'CA' ? null : usStateTimeZone(code)) ?? (country === 'US' ? null : canadaProvinceTimeZone(code));
+    return zone ? { zone, certain: country !== null || !countryCode(code) || regionHasTown(code, town) } : null;
+}
+/** Where a location puts a scan, for the reply-wide North America check. */
+function placeKind(location) {
+    const region = regionClock(location);
+    if (region?.certain)
+        return 'certain';
+    const place = location.split(',').at(-1);
+    if (countryTimeZone(place))
+        return 'abroad';
+    if (region)
+        return 'region';
+    const country = countryCode(place);
+    return country && country !== 'US' && country !== 'CA' ? 'abroad' : null;
+}
+/**
+ * The state or province of a North American scan from a carrier whose dates
+ * are local clocks. An uncertain one counts only in a reply that is in North
+ * America.
+ */
+function regionScanZone(name, location, inNorthAmerica) {
+    const region = typeof name === 'string' && LOCAL_CLOCK_CARRIERS.test(name.trim()) ? regionClock(location) : null;
+    return region && (region.certain || inNorthAmerica) ? region : null;
+}
+function scanZone(payload, state, fallback, number, inNorthAmerica = false) {
+    const name = stateCarrierName(payload, state);
+    const carrier = typeof name === 'string' ? carrierIdFromName(name) : undefined;
+    if (carrier === 'tnt' && /^\d{9}$/.test(number))
+        return null;
+    if (typeof name === 'string' && ASENDIA_USA.test(name.trim()))
+        return null;
+    const zone = carrier ? carrierTimezone(carrier) : 'UTC';
+    if (zone !== 'UTC')
+        return zone;
+    const location = typeof state.location === 'string' ? state.location.trim() : '';
+    const place = location.split(',').at(-1);
+    // A state or province the town confirms beats the country its code also
+    // names ("Chicago, IL"); a merely possible one comes after ("Koeln, DE").
+    const region = regionScanZone(name, location, inNorthAmerica);
+    if (region?.certain)
+        return region.zone;
+    const located = countryTimeZone(place);
+    if (located)
+        return located;
+    if (region)
+        return region.zone;
+    // The zones below only guess where the scan was. A location in another
+    // country, one with several clocks or none listed ("Example City, CA,
+    // United States", "Example City, South Africa"), rules a guess out, and the
+    // scan keeps its labeled instant.
+    const country = countryCode(place);
+    const guess = (candidate) => candidate && (!country || timeZoneCountry(candidate) === country) ? candidate : null;
+    if (typeof name !== 'string')
+        return guess(fallback);
+    const named = guess(carrierNameCountryZone(name));
+    if (named)
+        return named;
+    // A location with no single-clock country ("Toronto, ON", "Chicago, US")
+    // can be a network of the brand outside the catalog, on another clock.
+    const brand = location ? [] : brandTimeZones(name);
+    const wall = brand.length ? mislabeledWallTime(state.date) : null;
+    return (wall ? sharedClockZone(brand, wall) : null) ?? guess(fallback);
+}
+/**
+ * ParcelsApp relays some carriers' labels twice over, TIPSA's as
+ * "ENTREGADOENTREGADO". Only a label made of two identical halves is collapsed.
+ */
+function relayedLabel(value) {
+    const label = typeof value === 'string' ? value.trim() : '';
+    const half = label.length / 2;
+    return Number.isInteger(half) && label.slice(0, half) === label.slice(half) ? label.slice(0, half) : label;
+}
+function parseHistory(payload, trackingNumber, timezone = null) {
+    if (isRecord(payload) && payload.error === 'RELOAD')
+        throw new ChallengeError(SOURCE);
+    if (isRecord(payload) && (payload.error === 'NO_DATA' || payload.error === 'NO_TRACKER')) {
+        throw new NoHistoryError(SOURCE, 'ParcelsApp has no usable shipment history');
+    }
+    if (!isRecord(payload) || payload.error || !Array.isArray(payload.states) || payload.states.length > MAX_EVENTS) {
+        throw new SchemaError(SOURCE, 'ParcelsApp lookup unavailable');
+    }
+    const number = numberOf(trackingNumber);
+    const events = [];
+    const scans = [];
+    const scanCarriers = new Set();
+    let undated = 0;
+    // The reply is in North America when a scan certainly is, or when a scan
+    // names a state or province ("Atlanta, GA") and none names another country.
+    const kinds = payload.states.flatMap((raw) => isRecord(raw) && typeof raw.location === 'string' && raw.location.trim() ? [placeKind(raw.location)] : []);
+    const inNorthAmerica = kinds.includes('certain') || (kinds.includes('region') && !kinds.includes('abroad'));
+    const entries = [];
+    for (const raw of payload.states) {
+        if (!isRecord(raw))
+            throw new SchemaError(SOURCE, 'ParcelsApp returned an invalid event');
+        if (raw.require_fields || raw.error)
+            continue;
+        // A state can come without a date (an Asendia Spain leg). It has no place
+        // among the dated scans, so it is counted instead of read as the latest.
+        if (raw.date == null || raw.date === '') {
+            undated++;
+            continue;
+        }
+        const name = stateCarrierName(payload, raw);
+        const status = relayedLabel(raw.status);
+        const scan = carrierScan(typeof name === 'string' ? carrierIdFromName(name) : undefined, status);
+        const zone = scanZone(payload, raw, timezone, number, inNorthAmerica);
+        const location = typeof raw.location === 'string' ? raw.location.trim() : '';
+        entries.push({ raw, name, scan, wording: scan?.wording ?? status, zone,
+            local: zone !== null && zone === regionScanZone(name, location, inNorthAmerica)?.zone });
+    }
+    // Another carrier's copy of such a scan (Cainiao relaying UniUni's "Delivered"
+    // at the same minute, with no place) takes that scan's zone, so the two stay
+    // one scan.
+    const copyKey = ({ raw, wording }) => {
+        const wall = mislabeledWallTime(raw.date);
+        const text = wall ? localEvent(raw.date, wording)?.description : undefined;
+        return wall && text ? `${wall}|${text}` : '';
+    };
+    const localClocks = new Map(entries.filter((entry) => entry.local).map((entry) => [copyKey(entry), entry.zone]).filter(([key]) => key));
+    for (const entry of entries) {
+        const { raw, name, scan } = entry;
+        const zone = (localClocks.size && !entry.local ? localClocks.get(copyKey(entry)) : undefined) ?? entry.zone;
+        const parsed = localEvent((zone ? mislabeledLocalTime(raw.date, zone)?.iso : undefined) ?? raw.date, entry.wording);
+        // Nor has an offset-less date that no zone resolves: a wall time, not an instant.
+        if (parsed && !parsed.time) {
+            undated++;
+            continue;
+        }
+        if (parsed) {
+            events.push(parsed);
+            scanCarriers.add(name);
+        }
+        if (parsed && scan)
+            scans.push({ event: Object.assign(parsed, { stage: scan.stage }), scan });
+    }
+    markReturnLeg(scans);
+    if (!events.length) {
+        const fields = payload.states.flatMap((raw) => isRecord(raw) && Array.isArray(raw.require_fields) ? raw.require_fields : []);
+        if (fields.some((field) => isRecord(field) && field.name === 'zipcode')) {
+            throw new InputRequiredError(SOURCE, 'postcode', 'ParcelsApp requires a valid delivery postcode or further recipient information');
+        }
+        // An empty history is the NO_DATA answer; states that don't parse are not an answer.
+        if (!payload.states.length)
+            throw new NoHistoryError(SOURCE, 'ParcelsApp has no usable shipment history');
+        throw new IndeterminateError(SOURCE, 'No usable tracking events');
+    }
+    // The carriers ParcelsApp aggregated for this number ("DPD Group"), as
+    // discovery hints; routing confirms one with its own adapter before adopting it.
+    const services = Array.isArray(payload.services) ? payload.services : [];
+    const carriers = Array.isArray(payload.carriers) ? payload.carriers : [];
+    const hints = universalCarrierHints([
+        ...carriers, ...services.map((service) => isRecord(service) ? service.name : undefined),
+    ].slice(0, 20), number);
+    // The list also names carriers asked without an answer. When every scan
+    // names the same carrier, that carrier is the hint.
+    const discovered = hints.discovered_carrier
+        ?? (scanCarriers.size === 1 ? universalCarrierHints([...scanCarriers], number).discovered_carrier : undefined);
+    return { ...result(events, SOURCE), ...(undated ? { undated_event_count: undated } : {}),
+        ...hints, ...(discovered ? { discovered_carrier: discovered } : {}) };
+}
+function browserCanRecover(error) {
+    // A slow uncached lookup needs more time on the same API. It has already
+    // had one direct retry; a new browser lookup would repeat the work again.
+    if (error instanceof UpstreamNetworkError)
+        return false;
+    // A second lookup cannot repair missing input, rate limiting or an outage.
+    if (error instanceof UpstreamHttpError && (error.status === 429 || error.status >= 500))
+        return false;
+    const kind = carrierErrorKind(error);
+    return kind === null || kind === 'challenge' || kind === 'transport' || kind === 'schema';
+}
+export function parseParcelsAppHtml(html, trackingNumber, timezone = null) {
+    if (!parcelsIdentity(html, numberOf(trackingNumber)))
+        throw new SchemaError(SOURCE, 'ParcelsApp shipment identity missing');
+    const $ = load(html);
+    const nodes = $('.tracking-info .parcel .events > .event');
+    if (nodes.length > MAX_EVENTS)
+        throw new SchemaError(SOURCE, 'ParcelsApp returned too many events');
+    const events = [];
+    // Each scan names its carrier ("DPD Group") under its wording, as the JSON
+    // reply's `carriers` index does: the same zone rules then give the same
+    // instants, and so the same event ids, whichever tier answered.
+    const carriers = [];
+    const scans = [];
+    let undated = 0;
+    nodes.each((_, node) => {
+        const row = $(node);
+        if (row.find('input, select, form').length)
+            return;
+        const description = relayedLabel(row.find('.event-content > strong').first().text());
+        if (isNotice(description))
+            return;
+        const date = row.find('.event-time > strong').text().trim();
+        const time = row.find('.event-time > span').text().trim();
+        // Notice rows ("No information about your package...") render a date with
+        // an empty time. Skip them instead of failing the whole history.
+        if (!time)
+            return;
+        const name = row.find('.event-content .carrier').first().text().replace(/\s+/g, ' ').trim();
+        if (name && !carriers.includes(name))
+            carriers.push(name);
+        // The page prints a state without a date as "aN Inv NaN" at "aN:aN":
+        // counted, as in the JSON reply.
+        if (date.includes('NaN')) {
+            undated++;
+            return;
+        }
+        // The English web app renders the UTC digits of its API, which are the
+        // scan's local clock.
+        const labeled = DateTime.fromFormat(`${date} ${time}`, 'dd LLL yyyy HH:mm', { locale: 'en', zone: 'UTC' });
+        if (!labeled.isValid)
+            throw new SchemaError(SOURCE, 'ParcelsApp returned an invalid event date');
+        const state = { date: labeled.toISO(), ...(name ? { carrier: carriers.indexOf(name) } : {}) };
+        const zone = scanZone({ carriers }, state, timezone, numberOf(trackingNumber));
+        const scan = carrierScan(name ? carrierIdFromName(name) : undefined, description);
+        const parsed = event((zone ? mislabeledLocalTime(state.date, zone)?.iso : undefined) ?? state.date, scan?.wording ?? description);
+        if (parsed)
+            events.push(parsed);
+        if (parsed && scan)
+            scans.push({ event: Object.assign(parsed, { stage: scan.stage }), scan });
+    });
+    markReturnLeg(scans);
+    return { ...result(events, SOURCE), ...(undated ? { undated_event_count: undated } : {}),
+        ...universalCarrierHints(carriers.slice(0, 20), numberOf(trackingNumber)) };
+}
+export class ParcelsAppTracker {
+    options;
+    http;
+    constructor(options = {}) {
+        this.options = options;
+        this.http = options.httpClient === undefined ? new ParcelsAppHttpClient(options.fetcher) : options.httpClient;
+    }
+    async fetch(trackingNumber, budgetMs = this.options.timeoutMs ?? PARCELSAPP_BUDGET_MS, postcode, timezone = null) {
+        const number = numberOf(trackingNumber);
+        if (!Number.isFinite(budgetMs) || budgetMs < 1)
+            throw new TypeError('ParcelsApp timeout must be positive');
+        const deadline = performance.now() + budgetMs;
+        const request = async (remainingMs) => {
+            const payload = await this.http.fetch(number, Math.max(1, Math.min(DIRECT_BUDGET_MS, Math.floor(remainingMs))), postcode);
+            // This endpoint returns one shipment per POST, synchronously, with no
+            // shared session or polling handle. Each retry keeps its own request
+            // binding. Numberless browser captures never get this exemption.
+            if (isRecord(payload) && payload.correctId && payload.correctId !== number) {
+                throw new SchemaError(SOURCE, 'ParcelsApp returned an unverified tracking alias');
+            }
+            return { ...parseHistory(payload, number, timezone), tracking_source: 'structured-web-response' };
+        };
+        return runSteps({ carrier: SOURCE, budgetMs, recorder: this.options.recorder }, [{
+                id: 'direct',
+                enabled: this.http !== null,
+                run: ({ remainingMs }) => request(remainingMs),
+            }, {
+                id: 'retry',
+                enabled: this.http !== null,
+                // Uncached carrier aggregation can outlive a timed-out HTTP request.
+                // Retry that replayable read once; responses such as NO_DATA, input
+                // gates, aliases, challenges and HTTP errors do not qualify.
+                recovers: (error) => error instanceof UpstreamNetworkError && deadline - performance.now() > RETRY_DELAY_MS + 1,
+                run: async ({ signal }) => {
+                    await timers.setTimeout(RETRY_DELAY_MS, undefined, { signal });
+                    signal.throwIfAborted();
+                    return request(deadline - performance.now());
+                },
+            }, {
+                id: 'trawl',
+                enabled: this.options.trawl != null || this.http === null,
+                recovers: browserCanRecover,
+                run: async ({ remainingMs }) => {
+                    const capture = {
+                        source: SOURCE, url: `https://parcelsapp.com/en/tracking/${number}`, apiUrl: PARCELSAPP_API,
+                        budgetMs: remainingMs, fetcher: this.options.fetcher,
+                    };
+                    const page = await loadCapture(this.options.trawl ?? null, capture);
+                    for (const body of capturedBodies(page, capture)) {
+                        try {
+                            return parseParcelsAppResponse(JSON.parse(body), number, page.html, timezone);
+                        }
+                        catch {
+                            // Polling replies, unrelated numbers and demo shipments are not history.
+                        }
+                    }
+                    // The rendered page carries the same history when no body was readable.
+                    return parseParcelsAppHtml(page.html, number, timezone);
+                },
+            }]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new ParcelsAppTracker({
+        trawl: environment.trawl, fetcher: environment.fetcher, recorder: environment.recorder,
+    });
+    return {
+        id: SOURCE,
+        steps: ['direct', 'retry', 'trawl'],
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.postcode, input.timezone ?? null),
+    };
+};

package/dist/providers/parcelsapp/http.d.ts

@@ -0,0 +1,9 @@
+export declare const PARCELSAPP_API = "https://parcelsapp.com/api/v2/parcels";
+/** MurmurHash2 with the public website's seed, over ASCII protocol data. */
+export declare function parcelsAppChecksum(text: string): number;
+export declare function parcelsAppRequest(trackingNumber: string, postcode?: string | null): URLSearchParams;
+export declare class ParcelsAppHttpClient {
+    readonly fetcher?: typeof fetch | undefined;
+    constructor(fetcher?: typeof fetch | undefined);
+    fetch(trackingNumber: string, timeoutMs: number, postcode?: string | null): Promise<unknown>;
+}

package/dist/providers/parcelsapp/http.js

@@ -0,0 +1,67 @@
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+import { numberOf } from '../shared/result.js';
+export const PARCELSAPP_API = 'https://parcelsapp.com/api/v2/parcels';
+// Public frontend protocol, verified 2026-09-12. No session or issued secret:
+// packs/js/application-aa19cda6a00923f7e330.js on dvow0vltefbxy.cloudfront.net.
+// The website accepts this fixed telemetry profile, including its documented
+// "undefined" stack fallback. The checksum below binds it to each number.
+const TELEMETRY = '1361x780,1470x830,1280x800,no,MacIntel,Gecko,Mozilla,Netscape,Google Inc.,true,true,'
+    + 'Google Inc. (Apple),ANGLE (Apple, ANGLE Metal Renderer: Apple M1, Unspecified Version),true,true,'
+    + Buffer.from('parcelsapp.com').toString('base64') + ',' + Buffer.from('undefined').toString('base64');
+/** MurmurHash2 with the public website's seed, over ASCII protocol data. */
+export function parcelsAppChecksum(text) {
+    const bytes = Buffer.from(text, 'ascii');
+    let hash = 978 ^ bytes.length;
+    let offset = 0;
+    for (; offset + 4 <= bytes.length; offset += 4) {
+        let block = Math.imul(bytes.readUInt32LE(offset), 0x5bd1e995);
+        block ^= block >>> 24;
+        hash = Math.imul(hash, 0x5bd1e995) ^ Math.imul(block, 0x5bd1e995);
+    }
+    const remaining = bytes.length - offset;
+    if (remaining >= 3)
+        hash ^= bytes[offset + 2] << 16;
+    if (remaining >= 2)
+        hash ^= bytes[offset + 1] << 8;
+    if (remaining >= 1)
+        hash = Math.imul(hash ^ bytes[offset], 0x5bd1e995);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0x5bd1e995);
+    return (hash ^ hash >>> 15) >>> 0;
+}
+export function parcelsAppRequest(trackingNumber, postcode) {
+    const number = numberOf(trackingNumber);
+    // The bundle shifts ASCII by 2 * sum([1,2,8,4,5,6,7,5]) modulo 126,
+    // URI-encodes it, then lets jQuery form-encode it a second time.
+    const shifted = [...number].map((char) => String.fromCharCode((char.charCodeAt(0) + 76) % 126)).join('');
+    const params = new URLSearchParams({
+        trackingId: encodeURIComponent(shifted), carrier: 'Auto-Detect', language: 'en', country: 'Unknown',
+        platform: 'web-desktop', wd: 'false', c: 'true', p: '5', l: '3',
+        se: `${TELEMETRY},${TELEMETRY.length},${number.length},${parcelsAppChecksum(encodeURIComponent(number) + TELEMETRY)}`,
+    });
+    const zipcode = postcode?.trim();
+    if (zipcode)
+        params.set('extra[zipcode]', zipcode);
+    return params;
+}
+export class ParcelsAppHttpClient {
+    fetcher;
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    async fetch(trackingNumber, timeoutMs, postcode) {
+        const number = numberOf(trackingNumber);
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 1)
+            throw new TypeError('ParcelsApp HTTP timeout must be positive');
+        const { bytes } = await fetchBounded(PARCELSAPP_API, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+                Origin: 'https://parcelsapp.com', Referer: `https://parcelsapp.com/en/tracking/${number}`,
+                'X-Requested-With': 'XMLHttpRequest',
+            },
+            body: parcelsAppRequest(number, postcode),
+        }, { provider: 'ParcelsApp', fetcher: this.fetcher, timeoutMs: Math.floor(timeoutMs), maxBytes: 2_000_000 });
+        return parseJsonBytes(bytes, 'ParcelsApp');
+    }
+}

package/dist/providers/plan.d.ts

@@ -0,0 +1,38 @@
+import { type CoverageTier } from './coverage.js';
+import type { UniversalSource as Source } from './types.js';
+export declare const UNIVERSAL_SOURCES: Source[];
+/** Providers reached only through the browser service: slower, and sharing one TRAWL. */
+export declare const BROWSER_SOURCES: ReadonlySet<Source>;
+/** Lookup time reserved by the chain and host router, before transport allowance. */
+export declare function universalSourceBudget(source: Source): number;
+/** Evidence-based exception to affinity/rotation, shared by discovery and routing. */
+export declare function priorityUniversalSource(trackingNumber?: string): Source | undefined;
+export interface UniversalPlan {
+    /** The eligible providers, in the order to ask them. */
+    sources: Source[];
+    /** The carrier whose coverage evidence ordered them, or null for the default order. */
+    carrier: string | null;
+    /** A provider's coverage tier for that carrier; `unknown` without evidence. */
+    tier(source: Source): CoverageTier;
+    /** Lower is fuller history for the carrier; providers without evidence share one rank. */
+    rank(source: Source): number;
+}
+/**
+ * Orders providers (given in the default order) by a carrier's coverage tiers:
+ * fuller history first, HTTP before the browser service, then the default order.
+ * Excluded providers are left out unless nothing else would remain. UPU stays
+ * last whatever its evidence: sparse, never a preferred source.
+ */
+export declare function orderUniversalSources(eligible: readonly Source[], tiers: Partial<Record<Source, CoverageTier>> | null): Source[];
+/**
+ * The providers to ask for a number, ordered by the coverage evidence of the
+ * first of `carriers` that has some (the carrier the lookup is for, then the one
+ * confirmed or discovered for the number), otherwise in the default order.
+ */
+export declare function universalPlan(options?: {
+    carriers?: ReadonlyArray<string | null | undefined>;
+    trackingNumber?: string;
+    enablePostalNinja?: boolean;
+}): UniversalPlan;
+/** The default order for a number, without a carrier's evidence. */
+export declare function universalSources(enablePostalNinja?: boolean, trackingNumber?: string): Source[];

package/dist/providers/plan.js

@@ -0,0 +1,54 @@
+import { isValidS10TrackingNumber } from '../core/detection/s10.js';
+import { normalizeTrackingNumber } from '../core/detection/normalize.js';
+import { coverageTiers } from './coverage.js';
+export const UNIVERSAL_SOURCES = ['ParcelsApp', 'Ship24', '17TRACK', 'UPU'];
+/** Providers reached only through the browser service: slower, and sharing one TRAWL. */
+export const BROWSER_SOURCES = new Set(['17TRACK', 'Postal Ninja']);
+/** Lookup time reserved by the chain and host router, before transport allowance. */
+export function universalSourceBudget(source) {
+    return source === 'ParcelsApp' ? 45_000 : source === 'UPU' ? 8_000 : 30_000;
+}
+/** Evidence-based exception to affinity/rotation, shared by discovery and routing. */
+export function priorityUniversalSource(trackingNumber) {
+    // E-series and untested formats keep ordinary discovery.
+    return trackingNumber && /^[CL][A-Z]\d{9}CN$/.test(normalizeTrackingNumber(trackingNumber)) && isValidS10TrackingNumber(trackingNumber)
+        ? '17TRACK' : undefined;
+}
+const TIER_RANK = { full: 0, partial: 1, unknown: 2, empty: 3, excluded: 4 };
+const tierRank = (tiers, source) => TIER_RANK[source === 'UPU' ? 'unknown' : tiers?.[source] ?? 'unknown'];
+/**
+ * Orders providers (given in the default order) by a carrier's coverage tiers:
+ * fuller history first, HTTP before the browser service, then the default order.
+ * Excluded providers are left out unless nothing else would remain. UPU stays
+ * last whatever its evidence: sparse, never a preferred source.
+ */
+export function orderUniversalSources(eligible, tiers) {
+    const excluded = (source) => source !== 'UPU' && tiers?.[source] === 'excluded';
+    const usable = eligible.some((source) => source !== 'UPU' && !excluded(source)) ? eligible.filter((source) => !excluded(source)) : [...eligible];
+    return usable.sort((a, b) => Number(a === 'UPU') - Number(b === 'UPU') || tierRank(tiers, a) - tierRank(tiers, b)
+        || Number(BROWSER_SOURCES.has(a)) - Number(BROWSER_SOURCES.has(b)) || eligible.indexOf(a) - eligible.indexOf(b));
+}
+/**
+ * The providers to ask for a number, ordered by the coverage evidence of the
+ * first of `carriers` that has some (the carrier the lookup is for, then the one
+ * confirmed or discovered for the number), otherwise in the default order.
+ */
+export function universalPlan(options = {}) {
+    const { trackingNumber, enablePostalNinja = false } = options;
+    const defaults = enablePostalNinja ? ['ParcelsApp', 'Ship24', 'Postal Ninja', '17TRACK', 'UPU'] : [...UNIVERSAL_SOURCES];
+    const eligible = defaults.filter((source) => source !== 'UPU' || trackingNumber === undefined || isValidS10TrackingNumber(trackingNumber));
+    const carrier = (options.carriers ?? []).find((candidate) => coverageTiers(candidate)) ?? null;
+    const tiers = coverageTiers(carrier);
+    const ordered = orderUniversalSources(eligible, tiers);
+    const priority = priorityUniversalSource(trackingNumber);
+    return {
+        sources: priority ? [priority, ...ordered.filter((source) => source !== priority)] : ordered,
+        carrier,
+        tier: (source) => tiers?.[source] ?? 'unknown',
+        rank: (source) => tierRank(tiers, source),
+    };
+}
+/** The default order for a number, without a carrier's evidence. */
+export function universalSources(enablePostalNinja = false, trackingNumber) {
+    return universalPlan({ trackingNumber, enablePostalNinja }).sources;
+}

package/dist/providers/postal-ninja/adapter.d.ts

@@ -0,0 +1,17 @@
+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 type { TrawlClient } from '../../core/transport/index.js';
+import { type UniversalBrowserOptions } from '../../core/transport/browser.js';
+export declare function parsePostalNinjaResponse(payload: unknown, trackingNumber: string): CarrierResult;
+export interface PostalNinjaOptions extends UniversalBrowserOptions {
+    trawl?: TrawlClient | null;
+    fetcher?: typeof fetch;
+    recorder?: StepRecorder;
+}
+export declare class PostalNinjaTracker {
+    readonly options: PostalNinjaOptions;
+    constructor(options?: PostalNinjaOptions);
+    fetch(trackingNumber: string, budgetMs?: number): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;