universal-parcel-scraper 0.0.0-stage → 0.2.0

package/dist/providers/shared/hints.js

@@ -0,0 +1,37 @@
+import { brandCarrierIds, carrierIdFromName } from '../../core/catalog/hints.js';
+import { detectCarrierMatch } from '../../core/detection/index.js';
+export { isKnownCarrierName } from '../../core/catalog/hints.js';
+/**
+ * A bare brand ("DPD Group") names several catalog networks; the number can
+ * still pick one. Keep the networks whose detection rules match it, then the
+ * one a preferred rule backs, such as a DPD depot range. Anything else stays
+ * unresolved rather than guessed.
+ */
+export function brandCarrierForNumber(name, trackingNumber) {
+    const networks = brandCarrierIds(name);
+    if (!networks.length)
+        return undefined;
+    const detected = detectCarrierMatch(trackingNumber);
+    const matching = networks.filter((id) => detected.candidates.includes(id));
+    if (matching.length === 1)
+        return matching[0];
+    const preferred = matching.filter((id) => detected.preferred.includes(id));
+    return preferred.length === 1 ? preferred[0] : undefined;
+}
+/**
+ * Names are hints only. A direct adapter must confirm the shipment before
+ * adoption. The looked-up number resolves a bare brand name.
+ */
+export function universalCarrierHints(raw, trackingNumber) {
+    const names = [...new Set(raw.filter((value) => typeof value === 'string'
+            && value.length <= 80 && /^[\p{L}\p{N} .&'()-]+$/u.test(value)).map((value) => value.trim()))].filter(Boolean).slice(0, 10);
+    const detected = new Set();
+    for (const name of names) {
+        const carrier = carrierIdFromName(name) ?? (trackingNumber ? brandCarrierForNumber(name, trackingNumber) : undefined);
+        if (carrier)
+            detected.add(carrier);
+    }
+    return { reported_carriers: names,
+        ...(names.length === 1 && detected.size === 1 ? { discovered_carrier: [...detected][0] } : {}),
+    };
+}

package/dist/providers/shared/result.d.ts

@@ -0,0 +1,15 @@
+import type { Stage } from '../../generated/catalog.js';
+import type { CarrierEvent, CarrierResult } from '../../core/result/index.js';
+export type UniversalSource = '17TRACK' | 'ParcelsApp' | 'Postal Ninja' | 'Ship24' | 'UPU';
+export declare function numberOf(raw: string): string;
+export declare function text(value: unknown): string;
+export declare function isNotice(description: string): boolean;
+export declare function hasPrivateDeliveryDetails(description: string): boolean;
+export declare function eventStage(description: string): Stage | undefined;
+export declare function event(time: unknown, description: unknown, stage?: unknown): CarrierEvent | null;
+/**
+ * Like event(), but a scan without an offset keeps its wall time as local_time
+ * instead of failing the whole shipment. Never invents a UTC instant.
+ */
+export declare function localEvent(time: unknown, description: unknown, stage?: unknown): CarrierEvent | null;
+export declare function result(events: CarrierEvent[], source: UniversalSource, preserveOrder?: boolean): CarrierResult;

package/dist/providers/shared/result.js

@@ -0,0 +1,161 @@
+/**
+ * What the universal providers share once a payload has been read: the
+ * tracking-number guard, the text and notice filters, the event builders with
+ * their timezone policy, and the result projection that sorts, deduplicates
+ * and summarizes a history.
+ *
+ * The wording -> stage logic below is provider vocabulary (Ship24, ParcelsApp,
+ * 17TRACK and Postal Ninja all render the same aggregated scans), not a
+ * carrier status map. It is kept here unchanged while the classifiers are
+ * merged in a later step.
+ */
+import { DateTime } from 'luxon';
+import { trackingLanguageStage } from '../../core/status/index.js';
+import { nonterminalEnglishReturn } from '../../core/status/language.js';
+const STAGES = {
+    InfoReceived: 'registered', InTransit: 'in_transit', AvailableForPickup: 'ready_for_pickup',
+    OutForDelivery: 'out_for_delivery', DeliveryFailure: 'failed_attempt', Delivered: 'delivered',
+};
+export function numberOf(raw) {
+    const number = raw.toUpperCase().replace(/[\s.-]/g, '');
+    if (!/^(?=.*\d)[A-Z0-9]{4,40}$/.test(number))
+        throw new TypeError('Invalid tracking number');
+    return number;
+}
+export function text(value) {
+    return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim().slice(0, 500) : '';
+}
+// Universal sites mix carrier events with UI notices. Notices must not manufacture a
+// shipment timestamp or make an electronic announcement look like movement.
+export function isNotice(description) {
+    return /enter .*?(?:postal|post|zip|phone)|select (?:a |the )?(?:carrier|destination country)|no information about your (?:package|parcel|shipment)|tracking (?:is |temporarily )?unavailable|tracking number (?:not found|is incorrect)|no tracking (?:information|data)|delivery preference|captcha|verify (?:you|your)|enable javascript|try again later/i.test(description);
+}
+// Raw text, so accented and plain spellings are both listed. A carrier receiving the
+// parcel ("Recibido por Estafeta") and German "Firma" (a business) are not private.
+export function hasPrivateDeliveryDetails(description) {
+    return /\bpin\s*:|(?:access|security|pickup|collection) code|(?:door|house) (?:no\b|number)|signed (?:for )?by|signature|numero civico|firmato da|signe par|signé par|code (?:de retrait|d['’]acc[eè]s)|num[eé]ro de (?:rue|maison)|abholcode|zugangscode|hausnummer|unterschrieben von|codice (?:di ritiro|di accesso)|c[oó]digo (?:pin|secreto|de (?:recogida|retirada|retiro|acceso|acesso|entrega|seguridad|seguran[cç]a|levantamento|recolha|desbloqueo|desbloqueio|apertura|abertura))|firmad[oa] por|firma del destinatari|assinad[oa] por|assinatura|n[uú]mero (?:de (?:portal|puerta|casa|piso|vivienda|pol[ií]cia)|da (?:porta|casa))|(?:porta|puerta) n\.?\s?[º°]|n\.?\s?[º°] (?:de |da )?porta/i.test(description);
+}
+function sourceEventStage(description, includeBroadMovement = true) {
+    // Public aggregators retain the carrier's French wording even in English.
+    const french = description.toLowerCase().normalize('NFD').replace(/\p{Diacritic}/gu, '');
+    if (/colis en preparation chez l'expediteur/.test(french))
+        return 'registered';
+    if (/prise en charge de votre colis sur notre site logistique/.test(french))
+        return 'accepted';
+    if (nonterminalEnglishReturn(description))
+        return 'exception';
+    if (/returned to (?:the )?sender/i.test(description))
+        return 'returned';
+    if (/not delivered|could not.*deliver|unable to deliver|delivery (?:attempt|failed)/i.test(description))
+        return 'failed_attempt';
+    // Carrier-reported problems that are neither a missed attempt nor a return.
+    if (/damaged|broken in transit|lost in transit|(?:package|parcel|shipment) (?:is )?lost|refused(?: by)?|rejected by (?:the )?recipient|(?:incorrect|incomplete|insufficient|unknown|invalid) address|address (?:incorrect|incomplete|insufficient|unknown|invalid)|addressee (?:unknown|cannot be located)|delivery exception|shipment exception|carrier exception|held (?:by|in|at) customs|customs (?:issue|problem)|action required|awaiting instructions|(?:shipment|parcel) (?:held|on hold)/i.test(description))
+        return 'exception';
+    // A voided label was cancelled before shipping, even where a provider files
+    // it as transit (17TRACK's generic code). Exact wording only, so a relabel
+    // ("label voided, new label created") is not read as a cancellation.
+    if (/^(?:parcel|package|shipment|(?:shipping )?label) (?:(?:has been|was|is) )?void(?:ed)?[.!]?$/i.test(description))
+        return 'exception';
+    if (/delivered to (?:the )?(?:local carrier|delivery partner|post office)/i.test(description))
+        return 'in_transit';
+    if (/will be available for (?:pickup|collection)/i.test(description))
+        return 'in_transit';
+    // Sender pre-advice such as Quickpac's "Shipment recorded by sender (data delivered)".
+    if (/will be delivered|being prepared by the sender|recorded by (?:the )?(?:foreign )?sender|\bdata delivered\b|en route to .*awaiting processing/i.test(description))
+        return 'registered';
+    // The bare word also appears in handoffs, forecasts and negations ("delivered
+    // to airline", "expected to be delivered", "not yet delivered"); those follow
+    // the language rules instead of reading as a delivery.
+    if (/\bdelivered\b|delivery completed/i.test(description)
+        && [undefined, 'delivered'].includes(trackingLanguageStage(description)))
+        return 'delivered';
+    if (/ready for (?:pickup|collection)|available for (?:pickup|collection)/i.test(description))
+        return 'ready_for_pickup';
+    // "The status will be updated once shipment is out for delivery" is not the round itself.
+    if (/out for delivery/i.test(description)
+        && !/(?:once|when|as soon as) (?:the |your )?(?:shipment|parcel|package|item) is out for delivery/i.test(description))
+        return 'out_for_delivery';
+    if (/clearance (?:processing )?completed|customs (?:cleared|released)/i.test(description))
+        return 'in_transit';
+    if (/customs|clearance/i.test(description))
+        return 'customs';
+    if (/instruction data.*provided.*electronically|electronic information|information (?:received|submitted)|label (?:created|printed)|pre.?advice|shipment announced/i.test(description))
+        return 'registered';
+    if (/will be transported to the destination country/i.test(description))
+        return 'in_transit';
+    if (!includeBroadMovement)
+        return undefined;
+    if (/package received at dhl ecommerce|^pick-up was successful[.!]?$|accepted|collected|picked up|handed over/i.test(description))
+        return 'accepted';
+    if (/transit|arrived|departed|processed|processing completed at origin|sorting|sorted|transport|dispatched|en route|loaded to movement/i.test(description))
+        return 'in_transit';
+    return undefined;
+}
+export function eventStage(description) {
+    return sourceEventStage(description, false) ?? trackingLanguageStage(description) ?? sourceEventStage(description);
+}
+const EXPLICIT_OFFSET = /(?:Z|[+-]\d{2}:\d{2})$/;
+const LOCAL_WALL_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
+function describe(description, stage) {
+    const label = text(description);
+    if (!label || isNotice(label))
+        return null;
+    const declared = typeof stage === 'string' && Object.hasOwn(STAGES, stage) ? STAGES[stage] : undefined;
+    // Established source semantics (e.g. handoff/negation) remain first. A real
+    // provider stage outranks the new intuitive translation fallback.
+    const resolved = sourceEventStage(label, false) ?? declared ?? trackingLanguageStage(label) ?? sourceEventStage(label);
+    if (resolved !== 'delivered' && hasPrivateDeliveryDetails(label))
+        return null;
+    // Delivery descriptions can include signatures, access codes or door numbers.
+    return { description: resolved === 'delivered' ? 'Delivered' : label, stage: resolved ?? 'pending' };
+}
+export function event(time, description, stage) {
+    const described = describe(description, stage);
+    if (!described)
+        return null;
+    // Require an explicit offset: universal events can originate in any timezone.
+    if (typeof time !== 'string' || !EXPLICIT_OFFSET.test(time)) {
+        throw new TypeError('Tracking event has no valid timezone');
+    }
+    const date = DateTime.fromISO(time, { setZone: true });
+    if (!date.isValid)
+        throw new TypeError('Tracking event has an invalid timestamp');
+    return { time: date.toUTC().toISO(), ...described };
+}
+/**
+ * Like event(), but a scan without an offset keeps its wall time as local_time
+ * instead of failing the whole shipment. Never invents a UTC instant.
+ */
+export function localEvent(time, description, stage) {
+    if (typeof time === 'string' && EXPLICIT_OFFSET.test(time))
+        return event(time, description, stage);
+    const described = describe(description, stage);
+    if (!described)
+        return null;
+    if (typeof time !== 'string' || !LOCAL_WALL_TIME.test(time) || !DateTime.fromISO(time, { zone: 'UTC' }).isValid) {
+        throw new TypeError('Tracking event has an invalid timestamp');
+    }
+    return { local_time: time, ...described };
+}
+function moment(value) {
+    return value.time ?? (typeof value.local_time === 'string' ? value.local_time : '');
+}
+export function result(events, source, preserveOrder = false) {
+    // Wall times sort alongside UTC instants only approximately; providers that
+    // omit offsets everywhere pass preserveOrder instead.
+    const unique = [...new Map(events.map((e) => [`${moment(e)}|${e.description}`, e])).values()]
+        .sort((a, b) => preserveOrder ? 0 : moment(b).localeCompare(moment(a))).slice(0, 100);
+    if (!unique.length)
+        throw new TypeError('No usable tracking events');
+    const current = unique.find((e) => e.stage && e.stage !== 'pending')?.stage;
+    // Unknown wording can be displayed, but must not imply movement.
+    const status = current === 'delivered' ? 'delivered'
+        : current === 'registered' || !current ? 'pending'
+            : current === 'out_for_delivery' || current === 'ready_for_pickup' ? 'out_for_delivery'
+                : ['returned', 'failed_attempt', 'exception'].includes(current) ? 'exception' : 'in_transit';
+    return {
+        status, current_stage: current ?? 'pending', last_status_text: unique[0].description,
+        last_update: unique[0].time ?? null, expected_delivery: null, timezone: 'UTC',
+        tracking_provider: source, events: unique,
+    };
+}

package/dist/providers/shared/scans.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Carrier scan vocabularies for histories a universal provider relays.
+ *
+ * Some carriers reach us only through aggregators, which pass the carrier's own
+ * scan labels through, sometimes machine-translated. When the provider names
+ * the carrier of a scan and that carrier has a vocabulary, the label's stage and
+ * stored wording come from it rather than from the shared wording rules.
+ */
+import type { CarrierEvent } from '../../core/result/index.js';
+import type { Stage } from '../../core/status/index.js';
+export interface CarrierScan {
+    stage: Stage;
+    wording: string;
+    returnLeg?: true;
+}
+/** The vocabulary entry for one relayed label, when its carrier has a vocabulary. */
+export declare function carrierScan(carrier: string | undefined, label: string): CarrierScan | undefined;
+/** Rewrites the delivery-side scans that follow a vocabulary return scan. */
+export declare function markReturnLeg(scans: ReadonlyArray<{
+    event: CarrierEvent;
+    scan: CarrierScan;
+}>): void;

package/dist/providers/shared/scans.js

@@ -0,0 +1,29 @@
+import { ytoScan } from '../../carriers/yto/status.js';
+const VOCABULARIES = {
+    yto: ytoScan,
+};
+/** The vocabulary entry for one relayed label, when its carrier has a vocabulary. */
+export function carrierScan(carrier, label) {
+    return carrier && Object.hasOwn(VOCABULARIES, carrier) ? VOCABULARIES[carrier](label) : undefined;
+}
+// After the carrier's own return scan, its delivery-side scans are the trip
+// back: the sender signing for the parcel is a return, not a delivery.
+const RETURN_LEG = {
+    out_for_delivery: 'Out for delivery back to the sender',
+    ready_for_pickup: 'In a parcel locker or station on its way back',
+    delivered: 'Returned to the sender',
+};
+/** Rewrites the delivery-side scans that follow a vocabulary return scan. */
+export function markReturnLeg(scans) {
+    const started = scans.filter(({ scan }) => scan.returnLeg || scan.stage === 'returned')
+        .map(({ event }) => event.time ?? '').filter(Boolean).sort()[0];
+    if (!started)
+        return;
+    for (const { event, scan } of scans) {
+        if ((event.time ?? '') < started)
+            continue;
+        const wording = RETURN_LEG[scan.stage];
+        Object.assign(event, { provider_leg: 'return' }, wording ? { description: wording,
+            stage: scan.stage === 'delivered' ? 'returned' : scan.stage } : {});
+    }
+}

package/dist/providers/ship24/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 UniversalBrowserOptions } from '../../core/transport/browser.js';
+import { Ship24HttpClient } from './http.js';
+export declare function parseShip24Response(payload: unknown, trackingNumber: string, timezone?: string | null): CarrierResult;
+export interface Ship24Options extends UniversalBrowserOptions {
+    /** The signed HTTP client for the direct tier; without one the browser tier runs alone. */
+    httpClient?: Ship24HttpClient | null;
+    recorder?: StepRecorder;
+}
+export declare class Ship24Tracker {
+    readonly options: Ship24Options;
+    constructor(options?: Ship24Options);
+    fetch(trackingNumber: string, budgetMs?: number, timezone?: string | null): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/providers/ship24/adapter.js

@@ -0,0 +1,140 @@
+/**
+ * Ship24 (ship24.com), a universal aggregator and the first discovery
+ * provider.
+ *
+ * Two tiers: `direct` is one signed anonymous JSON POST per lookup (see
+ * http.ts), `browser` loads the public tracking page in a local Chromium
+ * session and reads the same API response from it. The browser tier only runs
+ * when the direct tier failed for a reason a browser can repair: a rate limit
+ * or a server outage is reported as it is, so the router's backoff is not
+ * amplified into a second request, and a number the aggregator does not know
+ * stays unknown to the page that asks the same API.
+ */
+import { DateTime } from 'luxon';
+import { carrierTimezone } from '../../core/catalog/index.js';
+import { brandTimeZones, carrierIdFromName, carrierNameCountryZone } from '../../core/catalog/hints.js';
+import { SchemaError, UpstreamHttpError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { scrapeUniversalPage } from '../../core/transport/browser.js';
+import { countryTimeZone, sharedClockZone } from '../../core/time/index.js';
+import { isRecord } from '../../core/types.js';
+import { brandCarrierForNumber, universalCarrierHints } from '../shared/hints.js';
+import { localEvent, numberOf, result } from '../shared/result.js';
+import { Ship24HttpClient } from './http.js';
+const SOURCE = 'Ship24';
+const MAX_EVENTS = 1000;
+const MAX_COURIERS = 20;
+/** The direct tier's own share of the lookup budget; the browser keeps the rest. */
+const DIRECT_BUDGET_MS = 8_000;
+/** A courier name's clock: its catalog carrier's, the country it names, or its brand's shared one. */
+function courierZones(name, number, wall) {
+    const carrier = carrierIdFromName(name) ?? brandCarrierForNumber(name, number);
+    const zone = carrier ? carrierTimezone(carrier) : 'UTC';
+    if (zone !== 'UTC')
+        return zone;
+    return carrierNameCountryZone(name) ?? sharedClockZone(brandTimeZones(name), wall);
+}
+/**
+ * The zone of a scan whose timestamp names no offset: it is the scanning
+ * carrier's wall clock. Read it in the clock every courier the reply names
+ * keeps at that moment (La Poste and its Chronopost leg), else the scan
+ * location's country, else the zone routing passes for the parcel's carrier.
+ * With none of them it stays a wall time, which the timeline cannot place.
+ */
+function wallZone(couriers, location, number, wall, fallback) {
+    const zones = couriers.map((name) => courierZones(name, number, wall));
+    const named = zones.length && zones.every((zone) => zone !== null) ? sharedClockZone(zones, wall) : null;
+    if (named)
+        return named;
+    const country = typeof location === 'string' ? location.split(',').at(-1) : undefined;
+    return countryTimeZone(country) ?? fallback;
+}
+export function parseShip24Response(payload, trackingNumber, timezone = null) {
+    const number = numberOf(trackingNumber);
+    if (!isRecord(payload) || !isRecord(payload.data) || payload.data.tracking_number !== number
+        || payload.data.error || !Array.isArray(payload.data.events) || payload.data.events.length > MAX_EVENTS) {
+        throw new SchemaError(SOURCE, 'Ship24 has no matching shipment history');
+    }
+    // The public frontend renders couriers[].translation.name. Keep names only;
+    // website/phone fields and alternate numbers are not needed for discovery.
+    const couriers = Array.isArray(payload.data.couriers) ? payload.data.couriers.slice(0, MAX_COURIERS) : [];
+    const names = universalCarrierHints(couriers.map((courier) => isRecord(courier) && isRecord(courier.translation) ? courier.translation.name : undefined), number);
+    const events = [];
+    for (const raw of payload.data.events) {
+        if (!isRecord(raw))
+            throw new SchemaError(SOURCE, 'Ship24 returned an invalid event');
+        // datetime can end in Z while still containing the carrier's local time.
+        // timestamp carries the real offset (verified against the public web app),
+        // except for some carrier legs (Chronopost) that omit it entirely.
+        const parsed = localEvent(raw.timestamp, raw.status, raw.dispatch_code_id === 7 ? 'Delivered' : undefined);
+        if (!parsed)
+            continue;
+        const wall = typeof parsed.local_time === 'string' ? parsed.local_time : null;
+        const zone = wall ? wallZone(names.reported_carriers, raw.location, number, wall, timezone) : null;
+        const instant = wall && zone ? DateTime.fromISO(wall, { zone }) : null;
+        if (instant?.isValid) {
+            const timed = { ...parsed, time: instant.toUTC().toISO() };
+            delete timed.local_time;
+            events.push(timed);
+        }
+        else
+            events.push(parsed);
+    }
+    return { ...result(events, SOURCE), ...names };
+}
+/**
+ * A browser cannot repair a rate limit or a server outage: keep the original
+ * status and Retry-After for the router's backoff instead of asking twice.
+ * Nor can it find a parcel the API answered 404 for: the page waits for the
+ * same reply, so every such fallback only burned the rest of the budget.
+ */
+function browserCanRecover(error) {
+    return !(error instanceof UpstreamHttpError
+        && (error.status === 404 || error.status === 410 || error.status === 429 || error.status >= 500));
+}
+export class Ship24Tracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(trackingNumber, budgetMs, timezone = null) {
+        const number = numberOf(trackingNumber);
+        const timeoutMs = budgetMs ?? this.options.timeoutMs ?? 45_000;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60_000)
+            throw new TypeError('Ship24 timeout must be between 1 and 60000 ms');
+        const http = this.options.httpClient ?? null;
+        return runSteps({ carrier: SOURCE, budgetMs: timeoutMs, recorder: this.options.recorder }, [
+            {
+                id: 'direct',
+                enabled: http !== null,
+                run: async ({ remainingMs }) => ({
+                    ...parseShip24Response(await http.fetch(number, Math.max(1, Math.min(DIRECT_BUDGET_MS, Math.floor(remainingMs)))), number, timezone),
+                    tracking_source: 'structured-web-response',
+                }),
+            },
+            {
+                id: 'browser',
+                recovers: browserCanRecover,
+                run: async ({ remainingMs }) => ({
+                    ...await scrapeUniversalPage({ executablePath: this.options.executablePath, timeoutMs: Math.max(1, Math.floor(remainingMs)) }, {
+                        name: SOURCE, url: `https://www.ship24.com/tracking?p=${number}`,
+                        responseUrl: `https://api.ship24.com/api/parcels/${number}?lang=en`,
+                    }, (payload) => parseShip24Response(payload, number, timezone)),
+                    tracking_source: 'browser-session-response',
+                }),
+            },
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new Ship24Tracker({
+        httpClient: new Ship24HttpClient(environment.fetcher),
+        executablePath: environment.browserExecutablePath ?? undefined,
+        recorder: environment.recorder,
+    });
+    return {
+        id: SOURCE,
+        steps: ['direct', 'browser'],
+        track: (input, context) => tracker.fetch(input.number, context?.budgetMs, input.timezone ?? null),
+    };
+};

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

@@ -0,0 +1,7 @@
+export declare function ship24Checksum(text: string): number;
+export declare class Ship24HttpClient {
+    readonly fetcher?: typeof fetch | undefined;
+    constructor(fetcher?: typeof fetch | undefined);
+    fetch(number: string, timeoutMs: number): Promise<unknown>;
+}
+export declare const ship24Http: Ship24HttpClient;

package/dist/providers/ship24/http.js

@@ -0,0 +1,75 @@
+/**
+ * The signed request the public Ship24 web app makes for one parcel.
+ *
+ * The website builds `x-ship24-token` from a timestamp, an opaque digest, a
+ * MurmurHash3 checksum bound to the tracking number and an HMAC over the
+ * three. The constants below are public frontend configuration read from the
+ * site's own script, not a provisioned API credential: no account, cookie,
+ * browser fingerprint or issued token is involved. See README.md.
+ */
+import { createHash, createHmac } from 'node:crypto';
+import { fetchBounded, parseJsonBytes } from '../../core/transport/index.js';
+const PAGE = 'https://www.ship24.com/tracking';
+// Public website checksum configuration, not a provisioned API credential.
+// Source (verified 2026-09-10):
+// https://cdn.ship24.com/assets/main.16f5bc7c0914804e.js
+// getOneParcel's N(...) argument and the first value appended to $zoho_.
+const WEBSITE_SIGNING_KEY = "qxV6SOr2tqw9m36j0-R-ohPt1PAB2et0"; // gitleaks:allow -- public frontend checksum constant, not an API credential
+const WEBSITE_SALT = '\u1780';
+// Standard MurmurHash3 x86/32, used by the public frontend's request checksum.
+export function ship24Checksum(text) {
+    const bytes = Buffer.from(text);
+    let hash = 0;
+    let offset = 0;
+    const mix = (value) => {
+        value = Math.imul(value, 0xcc9e2d51);
+        value = value << 15 | value >>> 17;
+        return Math.imul(value, 0x1b873593);
+    };
+    for (; offset + 4 <= bytes.length; offset += 4) {
+        hash ^= mix(bytes.readUInt32LE(offset));
+        hash = hash << 13 | hash >>> 19;
+        hash = (Math.imul(hash, 5) + 0xe6546b64) | 0;
+    }
+    let tail = 0;
+    for (let index = offset; index < bytes.length; index++)
+        tail |= bytes[index] << ((index - offset) * 8);
+    if (offset < bytes.length)
+        hash ^= mix(tail);
+    hash ^= bytes.length;
+    hash = Math.imul(hash ^ hash >>> 16, 0x85ebca6b);
+    hash = Math.imul(hash ^ hash >>> 13, 0xc2b2ae35);
+    return (hash ^ hash >>> 16) >>> 0;
+}
+function token(number) {
+    const timestamp = Date.now();
+    // The anonymous endpoint accepts an opaque digest; a browser fingerprint is
+    // unnecessary. Verified with fresh Node-only requests in the production container.
+    const digest = createHash('sha256').update(`delivery-tracker|en-US|${timestamp}`).digest('hex');
+    const encoded = Buffer.from(JSON.stringify({
+        a: ship24Checksum(number + timestamp + digest.length + WEBSITE_SALT), b: timestamp, c: digest,
+    })).toString('base64');
+    return `${encoded}.${createHmac('sha256', WEBSITE_SIGNING_KEY).update(encoded).digest('hex')}`;
+}
+export class Ship24HttpClient {
+    fetcher;
+    constructor(fetcher) {
+        this.fetcher = fetcher;
+    }
+    async fetch(number, timeoutMs) {
+        if (!/^(?=.*\d)[A-Z0-9]{4,40}$/.test(number))
+            throw new TypeError('Invalid Ship24 tracking number');
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 1)
+            throw new TypeError('Ship24 HTTP timeout must be positive');
+        const { bytes } = await fetchBounded(`https://api.ship24.com/api/parcels/${number}?lang=en`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Origin: 'https://www.ship24.com',
+                Referer: PAGE, 'x-ship24-token': token(number) },
+            body: JSON.stringify({ userAgent: '', os: 'Linux', browser: 'Unknown', device: 'Unknown',
+                os_version: 'unknown', browser_version: 'unknown', deviceType: 'desktop',
+                orientation: 'landscape', uL: 'en-US' }),
+        }, { provider: 'Ship24 HTTP', fetcher: this.fetcher, timeoutMs: Math.floor(timeoutMs), maxBytes: 2_000_000 });
+        return parseJsonBytes(bytes, 'Ship24');
+    }
+}
+export const ship24Http = new Ship24HttpClient();

package/dist/providers/types.d.ts

@@ -0,0 +1 @@
+export type UniversalSource = 'Ship24' | 'ParcelsApp' | '17TRACK' | 'Postal Ninja' | 'UPU';

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/universal.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The universal discovery chain: what runs when no dedicated carrier adapter
+ * can answer for a parcel.
+ *
+ * Default order is ParcelsApp -> Ship24 -> 17TRACK -> UPU, with Postal Ninja inserted before
+ * 17TRACK only when the host enables it. A carrier with coverage evidence
+ * (coverage.ts) gets its own order: fuller history first, HTTP before the
+ * browser service within a tier, providers that answered with another parcel or
+ * refused the format left out. Validated China Post C/L numbers put 17TRACK
+ * first. Each provider is asked once per lookup and the first usable history
+ * wins; the per-parcel router remembers which provider answered, except UPU
+ * stays last and requires a postal S10. The source names are persisted in
+ * routing state and must not change.
+ *
+ * This module owns the order and the aggregate failure; every protocol detail
+ * lives in the provider folder next to it.
+ */
+import type { AdapterEnvironment } from '../core/adapter/index.js';
+import type { CarrierResult } from '../core/result/index.js';
+import { type UniversalSource as Source } from './shared/result.js';
+export { parse17TrackResponse, SeventeenTrackLookupError, SeventeenTrackNoHistoryError, SeventeenTrackVerificationError } from './seventeentrack/adapter.js';
+export { parseParcelsAppHtml, parseParcelsAppResponse } from './parcelsapp/adapter.js';
+export { parsePostalNinjaResponse } from './postal-ninja/adapter.js';
+export { parseShip24Response } from './ship24/adapter.js';
+export { TrackingCaptureError } from './shared/capture.js';
+export type { UniversalSource } from './shared/result.js';
+export * from './plan.js';
+interface SourceFailure {
+    source: Source;
+    reason: string;
+    error: unknown;
+}
+export declare class UniversalTrackingError extends AggregateError {
+    readonly failures: ReadonlyArray<SourceFailure>;
+    constructor(failures: ReadonlyArray<SourceFailure>);
+}
+export interface UniversalTrackerOptions {
+    providers?: readonly Source[];
+    /** The browser service endpoint; overrides `environment.trawl`. An empty string disables it. */
+    trawlUrl?: string;
+    timeoutMs?: number;
+    fetcher?: typeof fetch;
+    executablePath?: string;
+    enablePostalNinja?: boolean;
+    /** Test seam replacing the two local-browser providers. */
+    browserLookup?: (source: 'Postal Ninja' | 'Ship24', number: string) => Promise<CarrierResult>;
+    /** What the host gives every adapter: browser service, telemetry sink, flags. */
+    environment?: Partial<AdapterEnvironment>;
+}
+export declare class UniversalTracker {
+    readonly options: UniversalTrackerOptions;
+    private readonly instances;
+    constructor(options?: UniversalTrackerOptions);
+    /**
+     * Look up one number through the whole chain. `postcode` is the parcel's
+     * stored delivery postcode, if the user supplied one: it is forwarded into
+     * every provider's track input. ParcelsApp submits it as extra[zipcode] on
+     * its direct API request; the other providers currently do not consume it.
+     */
+    fetch(trackingNumber: string, postcode?: string | null): Promise<CarrierResult>;
+    fetchSource(source: Source, trackingNumber: string, timeoutMs?: number, postcode?: string | null, timezone?: string | null, signal?: AbortSignal): Promise<CarrierResult>;
+    /** One provider adapter, built from this tracker's environment. */
+    private provider;
+    private environment;
+    private trawl;
+}