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

package/dist/carriers/couriersplease/parser.js

@@ -0,0 +1,222 @@
+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 { clean, textFromHtml } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { couriersPleaseStage } from './status.js';
+export const PROVIDER = 'CouriersPlease';
+// A consignment of several items is a few kilobytes per item.
+export const COURIERSPLEASE_MAX_BYTES = 512 * 1024;
+// Consignments, item labels, prepaid coupons and the SSCCs some senders print:
+// letters and digits, with at least one digit.
+const NUMBER = /^(?=[A-Z]*\d)[A-Z0-9]{8,30}$/;
+// The tracking page's session token: "salt==:encrypted".
+const TOKEN = /<meta\s+name="csrf-token"\s+content="([A-Za-z0-9+/=_:-]{16,512})"/;
+const MAX_ITEMS = 100;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/** A number for CouriersPlease's tracker, in upper case; anything else is not one it issues. */
+export function normalizeCouriersPleaseNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw).toUpperCase() : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'CouriersPlease numbers are eight to thirty letters and digits');
+    return number;
+}
+/** The session token the tracking page puts in its `csrf-token` meta tag, or null. */
+export function couriersPleaseToken(html) {
+    return TOKEN.exec(html.slice(0, 200_000))?.[1] ?? null;
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 500) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        throw new SchemaError(PROVIDER, `CouriersPlease returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+const LINK = /<a\b[^>]*>([\s\S]*?)<\/a\s*>/gi;
+const BREAK = /\s*<br\s*\/?>\s*/gi;
+const MARK = '\u0000';
+/**
+ * A scan's wording without its markup. A line break becomes the end of a
+ * sentence, as on the page, and a sentence that points to a link, such as
+ * "Please contact our Customer Support Team here", is left out.
+ */
+export function couriersPleaseWording(raw) {
+    // A link's text keeps a mark, so that its sentence can be told apart.
+    const marked = textFromHtml(raw.slice(0, 2_000).replace(LINK, ` ${MARK}$1 `).replace(BREAK, '. '), 1_000);
+    const kept = marked.split(/(?<=\.)\s+/).filter((sentence) => !sentence.includes(MARK)).join(' ');
+    const wording = kept || marked.replaceAll(MARK, '');
+    return clean(wording.replace(/\.(?:\s*\.)+/g, '.').replace(/\s+([,.])/g, '$1')).replace(/^[\s,;:.\-–]+|[\s,;:\-–.]+$/g, '');
+}
+const DATE = /^\d{1,2} [A-Z][a-z]{2} \d{4}$/;
+const CLOCK = /^(?:1[0-2]|0?[1-9]):[0-5]\d [ap]m$/i;
+/** A scan's `date` ("23 Mar 2026") and `time` ("5:00 pm"), a wall clock to the minute. */
+function wallClock(date, time) {
+    const parsed = DATE.test(date) && CLOCK.test(time)
+        // Parsing in UTC checks the calendar only; the wall clock keeps no offset.
+        ? DateTime.fromFormat(`${date} ${time}`, 'd MMM yyyy h:mm a', { zone: 'UTC', locale: 'en-US' }) : null;
+    if (!parsed?.isValid)
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid scan time');
+    return parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss");
+}
+/** The consignment's labelled facts: `time` names the field and `action` holds its value. */
+function facts(rows) {
+    if (!Array.isArray(rows) || rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned invalid consignment details');
+    const found = new Map();
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'CouriersPlease returned invalid consignment details');
+        const label = text(row, 'time', 60);
+        if (label && !found.has(label))
+            found.set(label, text(row, 'action', 300));
+    }
+    return found;
+}
+/** Each item's rows, or null for an item the tracker has no rows for. */
+function items(entry) {
+    const list = entry.trakingInfo;
+    if (!Array.isArray(list) || list.length > MAX_ITEMS)
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned invalid items');
+    return list.map((item) => {
+        if (!isRecord(item) || !isRecord(item.tracker))
+            throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid item');
+        const track = item.tracker.track;
+        if (track === null || track === undefined)
+            return null;
+        if (!Array.isArray(track) || track.length > MAX_ROWS)
+            throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid item history');
+        if (track.some((row) => !isRecord(row)))
+            throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid scan');
+        return track;
+    });
+}
+/** The item number an item's first row names ("CPPL TRACKER", "SSCC TRACKER" or a coupon's product), or ''. */
+function itemNumber(rows) {
+    const [first] = rows;
+    if (!first || first.action !== null || first.nodeType !== null)
+        return '';
+    return text(first, 'date', 64).toUpperCase();
+}
+/**
+ * An item's scans, as the page lists them: rows with wording, without the
+ * first row naming the item, the page's own "Overdue" marker, a sender's
+ * notice that the parcel was despatched to CouriersPlease, or the shipment
+ * details a sender sends after the pickup.
+ */
+function itemScans(rows, order) {
+    const scans = [];
+    let pickedUp = false;
+    for (const row of itemNumber(rows) ? rows.slice(1) : rows) {
+        const code = text(row, 'nodeType', 40).toLowerCase();
+        if (code === 'pickup')
+            pickedUp = true;
+        const date = text(row, 'date', 32);
+        const action = row.action;
+        if (action !== null && action !== undefined && typeof action !== 'string')
+            throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid action');
+        const description = typeof action === 'string' ? couriersPleaseWording(action) : '';
+        if (!date || !description || /^overdue$/i.test(description))
+            continue;
+        if (code === 'manifest' && pickedUp)
+            continue;
+        if (code === 'status' && /despatched to couriersplease/i.test(description))
+            continue;
+        const wall = wallClock(date, text(row, 'time', 16));
+        const location = text(row, 'stateName', 60);
+        const providerCode = /^[a-z][a-z-]{0,39}$/.test(code) ? code : '';
+        const staged = couriersPleaseStage(providerCode, description);
+        const event = {
+            local_time: wall,
+            ...(location ? { location } : {}),
+            description,
+            ...(providerCode ? { provider_code: providerCode } : {}),
+            ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+        };
+        scans.push({ event, key: JSON.stringify([wall, providerCode, description, location]), wall, order: order.next++ });
+    }
+    return scans;
+}
+/** The estimate the page shows, "26 Mar 2026", as a calendar day. */
+function estimate(value) {
+    if (!value || !DATE.test(value))
+        return null;
+    const parsed = DateTime.fromFormat(value, 'd MMM yyyy', { zone: 'UTC', locale: 'en-US' });
+    return parsed.isValid ? parsed.toISODate() : null;
+}
+/**
+ * The reply of the tracking page's `/api/track/locate` for one number. Its one
+ * entry holds the consignment's details, when the number is a consignment, and
+ * each item's rows, the first naming the item. A consignment must be the
+ * number asked, or an item must: a label or coupon has no consignment details.
+ * An unknown number gets no rows ("No scan events found", or an empty list),
+ * which the page reports as not a valid tracking number.
+ */
+export function parseCouriersPlease(payload, raw) {
+    const number = normalizeCouriersPleaseNumber(raw);
+    if (!isRecord(payload) || !Object.hasOwn(payload, 'data'))
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid envelope');
+    if (payload.data === null) {
+        // The service's refusal of the request itself, worded in `msg`.
+        if (typeof payload.msg === 'string' && payload.msg)
+            throw new IndeterminateError(PROVIDER, 'CouriersPlease did not take the lookup');
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned a reply without data');
+    }
+    if (!isRecord(payload.data) || !Array.isArray(payload.data.root))
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned an invalid result list');
+    if (payload.data.root.length !== 1 || !isRecord(payload.data.root[0])) {
+        throw new SchemaError(PROVIDER, 'CouriersPlease answered for another number of shipments');
+    }
+    const entry = payload.data.root[0];
+    if (!isRecord(entry.statusInfo))
+        throw new SchemaError(PROVIDER, 'CouriersPlease returned a result without its status');
+    const details = facts(entry.consignmentInfo ?? []);
+    const tracks = items(entry);
+    const consignment = (details.get('Consignment #') ?? '').toUpperCase();
+    const listed = tracks.flatMap((rows) => rows?.length ? [rows] : []);
+    if (!listed.length) {
+        if (consignment === number)
+            throw new NoHistoryError(PROVIDER);
+        throw new NotFoundError(PROVIDER);
+    }
+    if (consignment !== number && !listed.some((rows) => itemNumber(rows) === number)) {
+        throw new IndeterminateError(PROVIDER, 'CouriersPlease answered for another shipment');
+    }
+    const order = { next: 0 };
+    const seen = new Set();
+    const scans = [];
+    for (const rows of listed) {
+        for (const scan of itemScans(rows, order)) {
+            // An item of several repeats the consignment's own scans.
+            if (seen.has(scan.key))
+                continue;
+            seen.add(scan.key);
+            scans.push(scan);
+        }
+    }
+    if (!scans.length)
+        throw new NoHistoryError(PROVIDER);
+    // Newest first; each item lists its scans oldest first.
+    scans.sort((a, b) => (a.wall === b.wall ? b.order - a.order : a.wall < b.wall ? 1 : -1));
+    const events = scans.map((scan) => scan.event);
+    const newest = events[0];
+    const current = events.find((event) => event.stage);
+    const stage = current?.stage;
+    // The page shows the estimate as still to be confirmed while the sender's
+    // details are all there is.
+    const announced = events.every((event) => event.provider_code === 'manifest');
+    const expected = stage === 'delivered' || stage === 'returned' || announced ? null : estimate(details.get('Delivery ETA'));
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: current.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: null,
+        last_update_local: newest.local_time,
+        expected_delivery: expected,
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/couriersplease/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 CouriersPlease's vocabulary gives a row's wording, else its kind. */
+export declare function couriersPleaseMappedStage(code: string | null, wording: string): Stage | undefined;
+/** A scan's stage: its wording or kind, else the shared wording rules, else nothing. */
+export declare function couriersPleaseStage(code: string, wording: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;

package/dist/carriers/couriersplease/status.js

@@ -0,0 +1,96 @@
+import { classifyWording } from '../../core/status/index.js';
+import { normalizeStatusWording } from '../../core/status/statusMap.js';
+/**
+ * The kind of scan CouriersPlease's tracker gives each row (`nodeType`). Only
+ * kinds seen in replies are mapped. `faildeliver` covers failed attempts as
+ * well as parcels held for a problem or refused, so its wording comes first;
+ * `status` rows are notes whose wording alone can stage them.
+ */
+const CODES = new Map([
+    ['manifest', 'registered'], // Shipment information received from the sender.
+    ['pickup', 'accepted'],
+    ['futile', 'exception'], // A pickup attempt at the sender failed.
+    ['reweigh', 'in_transit'], // Arrived at a facility for processing.
+    ['transit', 'in_transit'], // In transit between delivery centres.
+    ['deconsolidate', 'in_transit'], // Arrived at the delivery centre.
+    ['indepot', 'in_transit'], // Processed at the delivery centre.
+    ['agent', 'in_transit'], // Handed to a regional delivery partner.
+    ['accept', 'out_for_delivery'], // Onboard for delivery.
+    ['offboard-depot', 'failed_attempt'], // Back at the depot undelivered; rescheduled for the next business day.
+    ['faildeliver', 'failed_attempt'],
+    ['deliver', 'delivered'],
+]);
+/** A wording in `normalizeStatusWording` form, with dashes made plain and no closing full stop. */
+function key(wording) {
+    return normalizeStatusWording(wording).replace(/\s*[–—]\s*/g, ' - ').replace(/[\s.]+$/, '');
+}
+/**
+ * The help centre's statuses, by their whole wording. They come before the
+ * row's kind, which several of them share.
+ */
+const WORDINGS = new Map([
+    ['Shipment information received', 'registered'],
+    ['Your parcel has been picked up', 'accepted'],
+    ['Received at Collection Point and awaiting collection by our driver', 'accepted'],
+    ['Pickup attempt was unsuccessful', 'exception'],
+    ['Pickup attempt was unsuccessful. Awaiting rebook confirmation by sender', 'exception'],
+    ['Arrived at facility for processing', 'in_transit'],
+    ['Processed at delivery centre', 'in_transit'],
+    ['In transit to delivery centre', 'in_transit'],
+    ['Arrived at delivery centre', 'in_transit'],
+    ['On the way to our delivery partner', 'in_transit'],
+    ['In transit to regional delivery centre', 'in_transit'],
+    ['Incomplete Shipment Received', 'in_transit'],
+    ['In Transit with Couriers Please', 'in_transit'],
+    ['Processing for collection at a nearby collection point', 'in_transit'],
+    ['Onboard for delivery', 'out_for_delivery'],
+    ['Resent for delivery', 'out_for_delivery'],
+    ['Delivery rescheduled for next business day', 'failed_attempt'],
+    ['Delivery attempted – Signature required', 'failed_attempt'],
+    ['Delivery attempted – Signature required – Redirected to a collection point', 'failed_attempt'],
+    ['Delivery attempted – Unsafe to leave', 'failed_attempt'],
+    ['Delivery attempted – Unsafe to leave – Sent to a collection point', 'failed_attempt'],
+    ['Delivery attempted – Business was closed', 'failed_attempt'],
+    ['Delivery attempted – Additional address information required', 'exception'],
+    ['Unable to deliver', 'exception'],
+    ['Delivery attempted – Delivery refused by receiver', 'returned'],
+    ['Pickup at Collection Point – Ready for collection', 'ready_for_pickup'],
+    ['Depot collection arranged', 'ready_for_pickup'],
+    ['Parcel has been collected from the collection point', 'delivered'],
+    ['Collected from Depot', 'delivered'],
+    ['Delivered', 'delivered'],
+    ['Delivered with Authority to Leave (ATL)', 'delivered'],
+    ['Collection period expired – Return to sender in progress', 'returned'],
+    ['Return to Sender In Progress', 'returned'],
+].map(([wording, stage]) => [key(wording), stage]));
+/**
+ * Notices the help centre lists that move nothing: a new delivery date or the
+ * receiver's instructions for the delivery still to come.
+ */
+const NOTICES = [
+    ['Delivery rescheduled', 'A new delivery date, which tracking shows; the parcel does not move.'],
+    ['Delivery instructions – Rescheduled', 'The receiver chose a new delivery date; it moves nothing.'],
+    ['Delivery instructions – Collection point', 'The receiver redirected the parcel to a collection point; the parcel has not moved yet.'],
+    ['Delivery instructions – Leave with Neighbour', 'An instruction for the delivery still to come; it moves nothing.'],
+    ['Delivery instructions – Authority to Leave (ATL)', 'An instruction for the delivery still to come; it moves nothing.'],
+    ['Delivery instructions – New delivery address', 'An instruction for the delivery still to come; it moves nothing.'],
+];
+const NOTES = new Set(NOTICES.map(([wording]) => key(wording)));
+/** The stage CouriersPlease's vocabulary gives a row's wording, else its kind. */
+export function couriersPleaseMappedStage(code, wording) {
+    return WORDINGS.get(key(wording)) ?? (code ? CODES.get(code.toLowerCase()) : undefined);
+}
+/** A scan's stage: its wording or kind, else the shared wording rules, else nothing. */
+export function couriersPleaseStage(code, wording) {
+    if (NOTES.has(key(wording)))
+        return null;
+    const mapped = couriersPleaseMappedStage(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) => (NOTES.has(key(wording)) ? undefined : couriersPleaseMappedStage(code, wording)),
+    gaps: NOTICES.map(([wording, note]) => ({ wording: normalizeStatusWording(wording), note })),
+};

package/dist/carriers/couriersplease/statuses.json

@@ -1,18 +1,20 @@
 {
   "carrier": "couriersplease",
   "entries": [
-    {"wording": "Shipment information received", "stage": "registered", "language": "en", "confirmedBy": "official-doc", "note": "The sender has created the shipment; Couriers Please may not have the parcel yet."},
-    {"wording": "Your parcel has been picked up", "stage": "accepted", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
+    {"code": "manifest", "wording": "Shipment information received", "stage": "registered", "language": "en", "confirmedBy": "live", "note": "The sender has created the shipment; Couriers Please may not have the parcel yet."},
+    {"code": "pickup", "wording": "Your parcel has been picked up", "stage": "accepted", "language": "en", "confirmedBy": "live"},
     {"wording": "Pickup attempt was unsuccessful", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "A collection attempt at the sender failed."},
-    {"wording": "Arrived at facility for processing", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Processed at delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "In transit to delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Arrived at delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
+    {"code": "futile", "wording": "Pickup attempt was unsuccessful. Awaiting rebook confirmation by sender", "stage": "exception", "language": "en", "confirmedBy": "live", "note": "The reply breaks the line between the two sentences."},
+    {"code": "reweigh", "wording": "Arrived at facility for processing", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "The reply ends it with a full stop, which the adapter drops."},
+    {"code": "indepot", "wording": "Processed at delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "live"},
+    {"code": "transit", "wording": "In transit to delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "The reply appends the line haul's two cities in brackets."},
+    {"code": "deconsolidate", "wording": "Arrived at delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "live"},
     {"wording": "On the way to our delivery partner", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Handed to a partner that completes the delivery."},
-    {"wording": "In transit to regional delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Transferred to a regional delivery partner; updates can be slower."},
-    {"wording": "Onboard for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Delivery rescheduled for next business day", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Not delivered in the current cycle."},
-    {"wording": "Delivery rescheduled", "language": "en", "confirmedBy": "official-doc", "note": "Delivery moved to the date shown in tracking."},
+    {"code": "agent", "wording": "In transit to regional delivery centre", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "Handed to a regional delivery partner; also seen as a line haul scan."},
+    {"code": "status", "wording": "In Transit with Couriers Please", "stage": "in_transit", "language": "en", "confirmedBy": "live", "note": "A note on the item's history beside its line haul scans."},
+    {"code": "accept", "wording": "Onboard for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "live"},
+    {"code": "offboard-depot", "wording": "Delivery rescheduled for next business day", "stage": "failed_attempt", "language": "en", "confirmedBy": "live", "note": "Back at the depot undelivered."},
+    {"wording": "Delivery rescheduled", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "A new delivery date, which tracking shows; the parcel does not move."},
     {"wording": "Resent for delivery", "stage": "out_for_delivery", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Delivery attempted – Signature required", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Delivery attempted – Signature required – Redirected to a collection point", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
@@ -20,23 +22,24 @@
     {"wording": "Delivery attempted – Unsafe to leave – Sent to a collection point", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Delivery attempted – Business was closed", "stage": "failed_attempt", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Delivery attempted – Additional address information required", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "Needs a corrected address before delivery can go on."},
-    {"wording": "Unable to deliver", "stage": "exception", "language": "en", "confirmedBy": "official-doc", "note": "The help centre says the issue needs further review."},
+    {"code": "faildeliver", "wording": "Unable to deliver", "stage": "exception", "language": "en", "confirmedBy": "live", "note": "The reply adds a sentence pointing to customer support with a link, which the adapter drops. The help centre says the issue needs further review."},
     {"wording": "Delivery attempted – Delivery refused by receiver", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Refused and being returned to the sender."},
     {"wording": "Processing for collection at a nearby collection point", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "At the collection point but not yet ready to collect."},
     {"wording": "Pickup at Collection Point – Ready for collection", "stage": "ready_for_pickup", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Parcel has been collected from the collection point", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
+    {"code": "deliver", "wording": "Parcel has been collected from", "stage": "delivered", "language": "en", "confirmedBy": "live", "note": "Followed by the collection point's name."},
     {"wording": "Collection period expired – Return to sender in progress", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Received at Collection Point and awaiting collection by our driver", "stage": "accepted", "language": "en", "confirmedBy": "official-doc", "note": "A customer drop-off waiting for a Couriers Please driver."},
     {"wording": "Depot collection arranged", "stage": "ready_for_pickup", "language": "en", "confirmedBy": "official-doc", "note": "The parcel is set aside for collection at a depot; the help centre says to wait for collection details."},
     {"wording": "Collected from Depot", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Delivered with Authority to Leave (ATL)", "stage": "delivered", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
+    {"code": "deliver", "wording": "Delivered", "stage": "delivered", "language": "en", "confirmedBy": "live"},
+    {"code": "deliver", "wording": "Delivered with Authority to Leave (ATL)", "stage": "delivered", "language": "en", "confirmedBy": "live"},
     {"wording": "Return to Sender In Progress", "stage": "returned", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
     {"wording": "Incomplete Shipment Received", "stage": "in_transit", "language": "en", "confirmedBy": "official-doc", "note": "Not all parcels of a multi-parcel shipment have arrived yet."},
-    {"wording": "Delivery instructions – Rescheduled", "language": "en", "confirmedBy": "official-doc", "note": "The receiver chose a new delivery date."},
-    {"wording": "Delivery instructions – Collection point", "language": "en", "confirmedBy": "official-doc", "note": "The receiver redirected the parcel to a collection point."},
-    {"wording": "Delivery instructions – Leave with Neighbour", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Delivery instructions – Authority to Leave (ATL)", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."},
-    {"wording": "Delivery instructions – New delivery address", "language": "en", "confirmedBy": "official-doc", "note": "Listed in Couriers Please's help centre article on tracking statuses."}
+    {"wording": "Delivery instructions – Rescheduled", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "The receiver chose a new delivery date; it moves nothing."},
+    {"wording": "Delivery instructions – Collection point", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "The receiver redirected the parcel to a collection point; it moves nothing."},
+    {"wording": "Delivery instructions – Leave with Neighbour", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "Listed in Couriers Please's help centre article on tracking statuses; it moves nothing."},
+    {"wording": "Delivery instructions – Authority to Leave (ATL)", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "Listed in Couriers Please's help centre article on tracking statuses; it moves nothing."},
+    {"wording": "Delivery instructions – New delivery address", "language": "en", "confirmedBy": "official-doc", "unmapped": true, "note": "Listed in Couriers Please's help centre article on tracking statuses; it moves nothing."}
   ]
 }

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

@@ -0,0 +1,17 @@
+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';
+/** The tracking search of the GDEX app, which app.gdexpress.com also serves on the web. */
+export declare const GDEX_API = "https://app.gdexpress.com/api/trackings";
+/** The address the app asks for one number. */
+export declare function gdexLookupUrl(number: string): string;
+export declare class GdexTracker {
+    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/gdex/adapter.js

@@ -0,0 +1,58 @@
+import { accepted, recognizeFromLookup } from '../../core/adapter/index.js';
+import { ChallengeError, SchemaError, TransportError } 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 { GDEX_MAX_BYTES, normalizeGdexNumber, parseGdex, PROVIDER } from './parser.js';
+/** The tracking search of the GDEX app, which app.gdexpress.com also serves on the web. */
+export const GDEX_API = 'https://app.gdexpress.com/api/trackings';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// Bot checks a CDN or firewall could put in place of the reply.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|<title>\s*Just a moment|challenge-platform|<title>\s*Attention Required|AwsWafIntegration/i;
+/** The address the app asks for one number. */
+export function gdexLookupUrl(number) {
+    return `${GDEX_API}?search=${encodeURIComponent(number)}`;
+}
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'GDEX answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'GDEX returned a reply that is not JSON', { cause });
+    }
+}
+export class GdexTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeGdexNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(gdexLookupUrl(number), { method: 'GET', signal, headers: {
+                    Accept: 'application/json, text/plain, */*', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: GDEX_MAX_BYTES,
+                redirect: 'manual', fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'GDEX redirected its tracking lookup');
+            // The app reads an unknown number from a 200 reply; a 404 is a moved route.
+            if (response.status === 404 || response.status === 410)
+                throw new TransportError(PROVIDER, 'GDEX tracking lookup is unavailable');
+            return parseGdex(json(decodeText(bytes)), number);
+        };
+        return runSteps({ carrier: 'gdex', 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 GdexTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'gdex', recordsSteps: true, steps: ['direct'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeGdexNumber(number))),
+    };
+};

package/dist/carriers/gdex/carrier.json

@@ -19,18 +19,58 @@
   "timezone": "Asia/Kuala_Lumpur",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "gdex",
+    "steps": [
+      "direct"
+    ],
+    "recognition": {
+      "rank": 957
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "delivered_at"
+  ],
   "portal": {
-    "canaryUrl": "https://my.gdexpress.com/",
-    "shows": [],
-    "scraped": [],
+    "url": "https://gdexpress.com/tracking/?consignmentno={trackingNumber}",
+    "searchUrl": "https://gdexpress.com/our-business/delivery/tools-references/tracking/",
+    "canaryUrl": "https://app.gdexpress.com/",
+    "shows": [
+      "status",
+      "history",
+      "location"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "provider_code",
+      "delivered_at"
+    ],
     "discarded": [],
-    "unavailable": []
+    "unavailable": [
+      "eta",
+      "weight",
+      "service_name",
+      "offset_timestamps",
+      "sender_name",
+      "recipient_name",
+      "proof_of_delivery"
+    ]
   },
   "links": [
+    {
+      "domains": [
+        "gdexpress.com",
+        "www.gdexpress.com"
+      ],
+      "pathPattern": "^/tracking/?$",
+      "params": [
+        "consignmentno"
+      ]
+    },
     {
       "domains": [
         "web2.gdexpress.com"

package/dist/carriers/gdex/numbers.json

@@ -250,6 +250,44 @@
         ]
       },
       "note": "A Lowyat forum post about the GDex courier service gives it as the tracking number of a parcel sent through a GDex branch."
+    },
+    {
+      "number": "MY37324153968",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://web.archive.org/web/20260504075317/https://gdexpress.com/tracking/?consignmentno=MY37324153968",
+        "date": "2026-05-04",
+        "dateKind": "capture",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "confirmed"
+      },
+      "expect": {
+        "carrier": "gdex",
+        "confidence": "high"
+      },
+      "note": "An archived lookup on GDEX's current tracking page; the opened capture shows the consignment's history."
+    },
+    {
+      "number": "MY37279142960",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://web.archive.org/web/20250805102258/https://gdexpress.com/tracking/?consignmentno=MY37279142960",
+        "date": "2025-08-05",
+        "dateKind": "capture",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "gdex",
+        "confidence": "high"
+      },
+      "note": "An archived lookup on GDEX's current tracking page passes it as the consignment number; the opened capture shows no history."
     }
   ]
 }

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

@@ -0,0 +1,15 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "GDEX";
+export declare const GDEX_MAX_BYTES: number;
+/** A GDEX consignment number, in upper case; anything else is not one GDEX issues. */
+export declare function normalizeGdexNumber(raw: string): string;
+/** A scan's wording, without the person a delivery names, a receiver or signer, or phone numbers. */
+export declare function gdexWording(raw: string): string;
+/**
+ * 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 declare function parseGdex(payload: unknown, raw: string): CarrierResult;