universal-parcel-scraper 0.181.0 → 0.183.0-main.1321

package/dist/carriers/gdex/parser.js

@@ -0,0 +1,149 @@
+import { DateTime } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { firstOccurrence } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { gdexStage } from './status.js';
+export const PROVIDER = 'GDEX';
+// A long history is a few kilobytes.
+export const GDEX_MAX_BYTES = 256 * 1024;
+const ZONE = 'Asia/Kuala_Lumpur';
+// Consignment notes print ten digits, or MY and eleven digits.
+const NUMBER = /^(?:\d{10}|MY\d{11})$/;
+// "2026-05-04T17:45:18", optionally with a fraction of a second.
+const WALL = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.\d{1,6})?$/;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/** A GDEX consignment number, in upper case; anything else is not one GDEX issues. */
+export function normalizeGdexNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw).toUpperCase() : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'GDEX consignment numbers are ten digits, or MY and eleven digits');
+    return number;
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 300) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `GDEX returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+// Whoever a delivery scan names after its own word: "Delivered to …", "Delivered (…)".
+const DELIVERED_TO = /^(delivered)\s*(?:[,;:.\-–(]|\b(?:to|by)\b)[\s\S]*$/i;
+// A receiver or signer named after any other scan's words.
+const RECEIVER = /\s*[,;:.\-–(]?\s*\b(?:received|signed) by\b[\s\S]*$/i;
+// A run of nine or more digits, with spaces, brackets, dots or hyphens
+// between them, as phone numbers are written.
+const PHONE = /(?<![A-Z\d])\+?\d(?:[\s().-]{0,2}\d){8,}(?![A-Z\d])/gi;
+/** A scan's wording, without the person a delivery names, a receiver or signer, or phone numbers. */
+export function gdexWording(raw) {
+    const own = clean(raw).replace(DELIVERED_TO, '$1').replace(RECEIVER, '').replace(PHONE, '');
+    return clean(own).replace(/^[\s,;:.\-–]+|[\s,;:\-–]+$/g, '');
+}
+/**
+ * A scan's `updatedAt`: the branch's wall clock, with no zone. GDEX scans in
+ * Malaysia, whose clock has no daylight saving, so it is read in
+ * `Asia/Kuala_Lumpur`.
+ */
+function scanTime(row) {
+    const wall = WALL.exec(text(row, 'updatedAt', 40))?.[1] ?? '';
+    // Parsing in UTC checks the calendar digits only. Luxon rolls 24:00:00 over to the next day.
+    const checked = DateTime.fromISO(wall, { zone: 'UTC' });
+    if (!wall || !checked.isValid || checked.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== wall) {
+        throw new SchemaError(PROVIDER, 'GDEX returned an invalid scan time');
+    }
+    return firstOccurrence(DateTime.fromISO(wall, { zone: ZONE })).toISO({ suppressMilliseconds: true });
+}
+function projectRow(row) {
+    const description = gdexWording(text(row, 'description', 500));
+    if (!description)
+        throw new SchemaError(PROVIDER, 'GDEX returned a scan without wording');
+    const time = scanTime(row);
+    const location = text(row, 'location', 120);
+    // The app's category for the scan: "Pickup", "In Transit", "Out For Delivery", "Delivered".
+    const code = text(row, 'status', 40);
+    const staged = gdexStage(code, description);
+    const event = {
+        time,
+        ...(location ? { location } : {}),
+        description,
+        ...(code ? { provider_code: code } : {}),
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+    return { key: JSON.stringify([time, code, description, location]), event };
+}
+/** The entry of the search reply for the number asked. */
+function entryFor(payload, number) {
+    if (!isRecord(payload) || !Array.isArray(payload.data))
+        throw new SchemaError(PROVIDER, 'GDEX returned an invalid envelope');
+    const entries = payload.data;
+    if (!entries.length)
+        throw new SchemaError(PROVIDER, 'GDEX answered without a consignment');
+    if (entries.some((entry) => !isRecord(entry) || typeof entry.trackingNumber !== 'string')) {
+        throw new SchemaError(PROVIDER, 'GDEX returned a consignment without its number');
+    }
+    const matching = entries
+        .filter((entry) => clean(entry.trackingNumber, 64).toUpperCase() === number);
+    if (matching.length !== 1)
+        throw new IndeterminateError(PROVIDER, 'GDEX answered for another consignment');
+    return matching[0];
+}
+/**
+ * The reply of the GDEX app's `/api/trackings?search=` for one number: one
+ * entry per number searched. A number GDEX has no record of comes back with
+ * `valid: false` and no data, which the app and the tracking page report as
+ * not found. A known consignment's scans are in `data.trackStatuses`, newest
+ * first.
+ */
+export function parseGdex(payload, raw) {
+    const number = normalizeGdexNumber(raw);
+    const entry = entryFor(payload, number);
+    if (entry.valid === false) {
+        if (entry.data === null || entry.data === undefined)
+            throw new NotFoundError(PROVIDER);
+        throw new SchemaError(PROVIDER, 'GDEX returned data for a consignment it calls invalid');
+    }
+    if (entry.valid !== true)
+        throw new SchemaError(PROVIDER, 'GDEX returned an invalid validity flag');
+    const data = entry.data;
+    if (!isRecord(data))
+        throw new SchemaError(PROVIDER, 'GDEX returned a consignment without its record');
+    const rows = data.trackStatuses ?? [];
+    if (!Array.isArray(rows))
+        throw new SchemaError(PROVIDER, 'GDEX returned a consignment with invalid scans');
+    if (rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'GDEX returned an oversized history');
+    const seen = new Set();
+    const projected = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'GDEX returned an invalid scan');
+        const scan = projectRow(row);
+        if (seen.has(scan.key))
+            continue;
+        seen.add(scan.key);
+        projected.push(scan.event);
+    }
+    if (!projected.length)
+        throw new NoHistoryError(PROVIDER);
+    // Newest first, as the app lists them; a reply listed oldest first is turned round.
+    const instant = (event) => Date.parse(event.time);
+    const events = instant(projected[0]) < instant(projected.at(-1)) ? projected.reverse() : projected;
+    const newest = events[0];
+    const current = events.find((event) => event.stage);
+    const stage = current?.stage;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: current.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: newest.time,
+        expected_delivery: null,
+        ...(stage === 'delivered' ? { delivered_at: current.time } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

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

@@ -0,0 +1,7 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** The stage GDEX's own vocabulary gives a scan: its wording, else its category. */
+export declare function gdexMappedStage(code: string | null, wording: string): Stage | undefined;
+/** A scan's stage: its wording or category, else the shared wording rules, else nothing. */
+export declare function gdexStage(code: string, wording: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/gdex/status.js

@@ -0,0 +1,41 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * GDEX's scan wordings, in `normalizeStatusWording` form. Hub and branch
+ * scans name the site: "Inbound to Kluang", "Outbound by Auto Hub".
+ */
+const WORDINGS = [
+    [/^picked up by courier$/, 'accepted'],
+    [/^(?:inbound|outbound) (?:to|by|from)\b/, 'in_transit'],
+    [/^in transit$/, 'in_transit'],
+    [/^out for delivery$/, 'out_for_delivery'],
+    // Filed under "In Transit": the parcel goes out again.
+    [/^(?:unsuccessful delivery|undelivered) due to\b/, 'failed_attempt'],
+    [/^delivered$/, 'delivered'],
+];
+/**
+ * The app's category for a scan, its `status`, in lower case. "In Transit"
+ * also holds failed deliveries, so it stages nothing on its own.
+ */
+const CODES = new Map([
+    ['pickup', 'accepted'],
+    ['out for delivery', 'out_for_delivery'],
+    ['delivered', 'delivered'],
+]);
+/** The stage GDEX's own vocabulary gives a scan: its wording, else its category. */
+export function gdexMappedStage(code, wording) {
+    const normalized = normalizeStatusWording(wording);
+    return WORDINGS.find(([pattern]) => pattern.test(normalized))?.[1] ?? (code ? CODES.get(normalizeStatusWording(code)) : undefined);
+}
+/** A scan's stage: its wording or category, else the shared wording rules, else nothing. */
+export function gdexStage(code, wording) {
+    const mapped = gdexMappedStage(code || null, wording);
+    if (mapped)
+        return { stage: mapped, source: 'carrier_map' };
+    const worded = classifyWording(wording, 'in_transit');
+    return worded.source === 'none' ? null : worded;
+}
+export const statusMap = {
+    stage: (code, wording) => gdexMappedStage(code, wording),
+    gaps: [],
+};

package/dist/carriers/gdex/statuses.json

@@ -1,13 +1,22 @@
 {
   "carrier": "gdex",
   "entries": [
-    {"wording": "Picked up by courier", "stage": "accepted", "language": "en", "confirmedBy": "portal"},
+    {"code": "Pickup", "wording": "Picked up by courier", "stage": "accepted", "language": "en", "confirmedBy": "live"},
     {"wording": "Outbound from SIN station", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Left the named GDEX station."},
+    {"wording": "Outbound to HUB", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Left for the hub."},
+    {"code": "In Transit", "wording": "Outbound by Auto Hub", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Left the named hub."},
+    {"code": "In Transit", "wording": "Inbound by Auto Hub", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Arrived at the named hub."},
+    {"code": "In Transit", "wording": "Inbound by PJY Hub (Petaling Jaya)", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Arrived at the named hub."},
+    {"code": "In Transit", "wording": "Outbound by PJY Hub (Petaling Jaya)", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Left the named hub."},
+    {"code": "In Transit", "wording": "Outbound from OCU Department", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Left the named department, after a failed delivery."},
+    {"code": "In Transit", "wording": "Inbound to Kluang", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Arrived at the named delivery branch."},
+    {"code": "In Transit", "wording": "Inbound to Petaling Jaya", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Arrived at the named delivery branch."},
     {"wording": "In transit", "stage": "in_transit", "language": "en", "confirmedBy": "portal"},
     {"wording": "Inbound to SDG station", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Arrived at the named delivery station."},
     {"wording": "Inbound to RWG station", "stage": "in_transit", "language": "en", "confirmedBy": "portal", "note": "Arrived at the named delivery station."},
-    {"wording": "Out for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "portal"},
+    {"code": "Out For Delivery", "wording": "Out for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live"},
+    {"code": "In Transit", "wording": "Unsuccessful delivery due to Customer Request for Rescheduled Delivery", "stage": "failed_attempt", "language": "en", "confirmedBy": "live", "note": "Not delivered because the customer asked for another day; the category stays In Transit."},
     {"wording": "Undelivered due to Customer Requests OC", "stage": "failed_attempt", "language": "en", "confirmedBy": "portal", "note": "Not delivered because the customer asked for another arrangement."},
-    {"wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "portal"}
+    {"code": "Delivered", "wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "live"}
   ]
 }

package/dist/carriers/leopards-courier/adapter.d.ts

@@ -0,0 +1,13 @@
+import { type AdapterFactory, type TrackingContext } from '../../core/adapter/index.js';
+import type { CarrierResult } from '../../core/result/index.js';
+import { type StepRecorder } from '../../core/telemetry/index.js';
+export declare class LeopardsTracker {
+    private readonly options;
+    constructor(options?: {
+        fetcher?: typeof fetch;
+        recorder?: StepRecorder;
+        userAgent?: string;
+    });
+    fetch(raw: string, context?: TrackingContext): Promise<CarrierResult>;
+}
+export declare const adapter: AdapterFactory;

package/dist/carriers/leopards-courier/adapter.js

@@ -0,0 +1,73 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { IndeterminateError, TransportError, UpstreamHttpError, UpstreamNetworkError } from '../../core/errors/index.js';
+import { runSteps } from '../../core/runner/index.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { LEOPARDS_LOOKUP, LEOPARDS_MAX_BYTES, LEOPARDS_ORIGIN, LEOPARDS_VIEW, normalizeLeopardsNumber, parseLeopards, PROVIDER, readLeopardsLookup, } from './parser.js';
+const REDIRECTS = [301, 302, 303, 307, 308];
+const GONE = [404, 410];
+// Laravel's session cookie, which holds the consignment the lookup found.
+const SESSION_COOKIE = /^leopards_official_session=([^\s;,]{1,4096})/;
+/**
+ * The same failure without the request and response details fetchBounded
+ * attaches: they hold the session cookie.
+ */
+function withoutSession(error) {
+    if (error instanceof UpstreamHttpError)
+        return new UpstreamHttpError(error.provider, error.status, error.retryAfterMs);
+    if (error instanceof UpstreamNetworkError)
+        return new UpstreamNetworkError(error.provider, error.cause);
+    return error;
+}
+export class LeopardsTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeLeopardsNumber(raw);
+        // The tracking box's lookup keeps the consignment in a new session, and the tracking page shows it.
+        const read = async (signal, timeoutMs) => {
+            const deadline = performance.now() + timeoutMs;
+            const left = () => Math.max(1, Math.floor(deadline - performance.now()));
+            const get = (url, headers) => fetchBounded(url, { method: 'GET', signal,
+                headers: { 'User-Agent': userAgentOf(this.options.userAgent), 'Accept-Language': 'en', ...headers } }, { provider: PROVIDER, timeoutMs: left(), maxBytes: LEOPARDS_MAX_BYTES, redirect: 'manual', fetcher: this.options.fetcher,
+                allowHttpStatuses: [...REDIRECTS, ...GONE] });
+            const answered = (response, what) => {
+                if (REDIRECTS.includes(response.status))
+                    throw new TransportError(PROVIDER, `Leopards moved its ${what}`);
+                if (GONE.includes(response.status))
+                    throw new TransportError(PROVIDER, `Leopards ${what} is unavailable`);
+            };
+            try {
+                const lookup = await get(`${LEOPARDS_LOOKUP}?${new URLSearchParams({ cn_number: number })}`, {
+                    Accept: 'application/json, text/javascript, */*; q=0.01', 'X-Requested-With': 'XMLHttpRequest', Referer: `${LEOPARDS_ORIGIN}/`
+                });
+                answered(lookup.response, 'tracking lookup');
+                readLeopardsLookup(decodeText(lookup.bytes), number);
+                const session = lookup.response.headers.getSetCookie().map(cookie => SESSION_COOKIE.exec(cookie)?.[0]).find(Boolean);
+                if (!session)
+                    throw new IndeterminateError(PROVIDER, 'Leopards did not open a tracking session', { reason: 'session_rejected' });
+                signal.throwIfAborted();
+                const page = await get(LEOPARDS_VIEW, { Accept: 'text/html,application/xhtml+xml', Cookie: session, Referer: `${LEOPARDS_ORIGIN}/` });
+                answered(page.response, 'tracking page');
+                return parseLeopards(decodeText(page.bytes), raw);
+            }
+            catch (error) {
+                throw withoutSession(error);
+            }
+        };
+        return runSteps({ carrier: 'leopards-courier', budgetMs: context.budgetMs ?? 20_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, remainingMs) },
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new LeopardsTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'leopards-courier', recordsSteps: true, steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeLeopardsNumber(number))),
+    };
+};

package/dist/carriers/leopards-courier/carrier.json

@@ -18,17 +18,62 @@
   "timezone": "Asia/Karachi",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "leopards-courier",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 965
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "delivered_at",
+    "offset_timestamps"
+  ],
   "portal": {
     "searchUrl": "https://pk.leopardscourier.com/",
     "canaryUrl": "https://pk.leopardscourier.com/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "progress_rail",
+      "origin",
+      "destination",
+      "sender_name",
+      "recipient_name",
+      "customer_reference",
+      "booking_details",
+      "piece_count",
+      "delivered_at",
+      "signatory"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "delivered_at",
+      "offset_timestamps",
+      "canonical_tracking_number"
+    ],
+    "discarded": [
+      "progress_rail",
+      "origin",
+      "destination",
+      "sender_name",
+      "recipient_name",
+      "customer_reference",
+      "booking_details",
+      "piece_count",
+      "signatory"
+    ],
+    "unavailable": [
+      "eta",
+      "service_name",
+      "weight"
+    ]
   },
   "links": [
     {

package/dist/carriers/leopards-courier/numbers.json

@@ -25,7 +25,7 @@
     },
     {
       "number": "KI0646202929",
-      "role": "quarantined",
+      "role": "shipment",
       "evidence": "public_shipment_report",
       "source": {
         "url": "https://web.archive.org/web/20260918090914/https://pk.leopardscourier.com/shipment_tracking_view?cn_number=KI0646202929",
@@ -33,9 +33,8 @@
         "dateKind": "capture",
         "access": "full_page"
       },
-      "quarantine": true,
       "context": {
-        "assessment": "review"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -46,11 +45,11 @@
           "aramex-nz"
         ]
       },
-      "note": "Sent to Leopards' own tracker, as an archived address shows; the opened capture says the number is invalid or not found, so it stays quarantined."
+      "note": "Sent to Leopards' own tracker, as an archived address shows. The opened capture, taken before its first scan, says the number is invalid or not found; Leopards' tracking page later shows its delivery."
     },
     {
       "number": "KI0646319661",
-      "role": "quarantined",
+      "role": "shipment",
       "evidence": "public_shipment_report",
       "source": {
         "url": "https://web.archive.org/web/20260922134325/https://pk.leopardscourier.com/shipment_tracking_view?cn_number=KI0646319661",
@@ -58,9 +57,8 @@
         "dateKind": "capture",
         "access": "full_page"
       },
-      "quarantine": true,
       "context": {
-        "assessment": "review"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -71,7 +69,7 @@
           "aramex-nz"
         ]
       },
-      "note": "Sent to Leopards' own tracker, as an archived address shows; the opened capture says the number is invalid or not found, so it stays quarantined."
+      "note": "Sent to Leopards' own tracker, as an archived address shows. The opened capture, taken before its first scan, says the number is invalid or not found; Leopards' tracking page later shows its delivery."
     }
   ]
 }

package/dist/carriers/leopards-courier/parser.d.ts

@@ -0,0 +1,26 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Leopards";
+export declare const LEOPARDS_MAX_BYTES = 1000000;
+export declare const LEOPARDS_ORIGIN = "https://pk.leopardscourier.com";
+/** The lookup the tracking box sends the number to. */
+export declare const LEOPARDS_LOOKUP = "https://pk.leopardscourier.com/shipment_tracking-new";
+/** The page that shows the consignment the lookup kept in the session. */
+export declare const LEOPARDS_VIEW = "https://pk.leopardscourier.com/shipment_tracking_view";
+/** A Leopards consignment number: two letters and ten digits, nine digits taking a leading zero as the tracker does. */
+export declare function normalizeLeopardsNumber(raw: string): string;
+/** Whether a page is a firewall's or bot check's instead of the site's. */
+export declare function isLeopardsBlockPage(html: string): boolean;
+/**
+ * The lookup's reply: `{"success":true}` once the site has kept the
+ * consignment in the session, or the tracking page with its notice for a
+ * number it has no record of.
+ */
+export declare function readLeopardsLookup(body: string, raw: string): void;
+/**
+ * The tracking page for the consignment the lookup kept in the session: its
+ * number, a delivery box naming who signed, the booking details and its scans
+ * newest first, each with a date, a minute and Leopards' wording. The booking
+ * details, the signatory and the receiver named in a delivery's wording are
+ * not read.
+ */
+export declare function parseLeopards(html: string, raw: string): CarrierResult;