universal-parcel-scraper 0.183.0-main.1321 → 0.185.0-main.1328

package/README.md

@@ -13,7 +13,7 @@ The engine behind [Peek](https://peektracker.com) ([GitHub](https://github.com/p
 [![License: Apache-2.0](https://img.shields.io/badge/core-Apache--2.0-blue.svg)](LICENSE)
 
 <!-- GENERATED:summary -->
-**3,500+ carriers** through **260 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **263 dedicated adapters** and **5 universal fallbacks**
 
 <sub>494 catalog entries · 113 countries represented</sub>
 <!-- /GENERATED:summary -->
@@ -155,7 +155,7 @@ createTracker({ providers: ['ParcelsApp', 'Ship24', '17TRACK', 'Postal Ninja', '
 <!-- GENERATED:stages -->
 <img src="docs/assets/stages.svg" alt="DHL: Die Sendung wurde in das Zustellfahrzeug geladen.; Mondial Relay: En cours de livraison; Correios Brazil: Objeto saiu para entrega ao destinatário; Correos Express: EN REPARTO; Yamato Transport: 配達中; La Poste / Colissimo: DISTOU. All are filed under out_for_delivery." width="760">
 
-The carrier folders record 9,604 such statuses, each filed under one stage.
+The carrier folders record 9,707 such statuses, each filed under one stage.
 <!-- /GENERATED:stages -->
 
 Wording nobody recorded yet goes through a classifier that reads seven European languages.

package/data/catalog.json

@@ -7368,7 +7368,9 @@
     "timezone": "Asia/Shanghai",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "cj-packet",
+      "recognitionRank": 956,
+      "localClocks": true
     },
     "canaryUrl": "https://www.cjpacket.com/",
     "trackingUrlTemplate": "https://www.cjpacket.com/?trackingNumber={trackingNumber}",
@@ -12276,7 +12278,8 @@
     "timezone": "Asia/Bangkok",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "kex",
+      "recognitionRank": 959
     },
     "canaryUrl": "https://th.kex-express.com/en/track-parcel",
     "trackingUrlTemplate": "https://th.kex-express.com/en/track/?track={trackingNumber}",
@@ -16849,7 +16852,9 @@
     "timezone": "Asia/Shanghai",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "sfc",
+      "recognitionRank": 955,
+      "localClocks": true
     },
     "canaryUrl": "https://www.sendfromchina.com/track",
     "trackingSearchUrl": "https://www.sendfromchina.com/track",
@@ -16858,6 +16863,10 @@
       {
         "pattern": "^SFC\\d[A-Z]{2}\\d{13,14}$",
         "confidence": "high"
+      },
+      {
+        "pattern": "^SFC[A-Z]{2}\\d{10}YQ$",
+        "confidence": "high"
       }
     ]
   },
@@ -18070,7 +18079,6 @@
       "adapter": "universal"
     },
     "canaryUrl": "https://steadfast.com.bd/tracking",
-    "trackingUrlTemplate": "https://steadfast.com.bd/t/{trackingNumber}",
     "trackingSearchUrl": "https://steadfast.com.bd/tracking",
     "linkRules": [
       {

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 494,
-  "activeAdapters": 260,
+  "activeAdapters": 263,
   "countries": 113,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -50357,6 +50357,12 @@
       "pathao-courier"
     ]
   },
+  {
+    "input": "DCAT0000175027",
+    "carrier": "unknown",
+    "confidence": "none",
+    "candidates": []
+  },
   {
     "input": "DD-KBA6JL",
     "carrier": "unknown",
@@ -60872,6 +60878,18 @@
     "confidence": "none",
     "candidates": []
   },
+  {
+    "input": "PROS0518804706",
+    "carrier": "unknown",
+    "confidence": "none",
+    "candidates": []
+  },
+  {
+    "input": "PROS0585164315",
+    "carrier": "unknown",
+    "confidence": "none",
+    "candidates": []
+  },
   {
     "input": "PRT00000001234000000001",
     "carrier": "ecoscooting",
@@ -63218,6 +63236,12 @@
       "spring-gds"
     ]
   },
+  {
+    "input": "RUTD000239675UL",
+    "carrier": "unknown",
+    "confidence": "none",
+    "candidates": []
+  },
   {
     "input": "RW000336615R",
     "carrier": "speedaf",
@@ -63782,6 +63806,14 @@
       "sfc"
     ]
   },
+  {
+    "input": "SFCAA0121278784YQ",
+    "carrier": "sfc",
+    "confidence": "high",
+    "candidates": [
+      "sfc"
+    ]
+  },
   {
     "input": "SFR250908ST31F5CFEBD",
     "carrier": "steadfast",

package/dist/browser/scraper.js

@@ -5824,7 +5824,9 @@ var Ae = {
 		timezone: "Asia/Shanghai",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "cj-packet",
+			recognitionRank: 956,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.cjpacket.com/",
 		trackingUrlTemplate: "https://www.cjpacket.com/?trackingNumber={trackingNumber}",
@@ -9447,7 +9449,8 @@ var Ae = {
 		timezone: "Asia/Bangkok",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "kex",
+			recognitionRank: 959
 		},
 		canaryUrl: "https://th.kex-express.com/en/track-parcel",
 		trackingUrlTemplate: "https://th.kex-express.com/en/track/?track={trackingNumber}",
@@ -12829,7 +12832,9 @@ var Ae = {
 		timezone: "Asia/Shanghai",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "sfc",
+			recognitionRank: 955,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.sendfromchina.com/track",
 		trackingSearchUrl: "https://www.sendfromchina.com/track",
@@ -12837,6 +12842,9 @@ var Ae = {
 		detectionRules: [{
 			pattern: "^SFC\\d[A-Z]{2}\\d{13,14}$",
 			confidence: "high"
+		}, {
+			pattern: "^SFC[A-Z]{2}\\d{10}YQ$",
+			confidence: "high"
 		}]
 	},
 	shadowfax: {
@@ -13720,7 +13728,6 @@ var Ae = {
 			adapter: "universal"
 		},
 		canaryUrl: "https://steadfast.com.bd/tracking",
-		trackingUrlTemplate: "https://steadfast.com.bd/t/{trackingNumber}",
 		trackingSearchUrl: "https://steadfast.com.bd/tracking",
 		linkRules: [{
 			domains: ["steadfast.com.bd", "www.steadfast.com.bd"],
@@ -15859,7 +15866,7 @@ var Ae = {
 	serpost: [],
 	servientrega: [],
 	"seven-eleven-tw": [],
-	sfc: ["sfc-1"],
+	sfc: ["sfc-1", "sfc-ae"],
 	shadowfax: ["shadowfax-1", "shadowfax-2"],
 	"shree-maruti": [],
 	"shree-nandan": [],
@@ -21048,6 +21055,7 @@ var nl = {
 	chronopost: 890,
 	ciblex: 640,
 	"cj-logistics": 977,
+	"cj-packet": 956,
 	"colis-prive": 740,
 	coordinadora: 973,
 	"correo-argentino": 978,
@@ -21111,6 +21119,7 @@ var nl = {
 	"j-and-t": 530,
 	"j-and-t-cargo": 910,
 	jitsu: 85,
+	kex: 959,
 	"kuehne-nagel": 435,
 	"la-poste": 1e3,
 	"latvijas-pasts": 100,
@@ -21157,6 +21166,7 @@ var nl = {
 	"saudi-post": 963,
 	servientrega: 979,
 	seur: 870,
+	sfc: 955,
 	shadowfax: 595,
 	"slovak-parcel-service": 180,
 	"slovenska-posta": 170,

package/dist/carriers/cj-packet/adapter.d.ts

@@ -0,0 +1,15 @@
+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 lookup the tracking page on www.cjpacket.com makes for the numbers in its address. */
+export declare const CJ_PACKET_API = "https://www.cjpacket.com/cj-logistics-api/refactoring/cjpacket/track";
+export declare class CjPacketTracker {
+    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/cj-packet/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 { firstAttemptMs, networkRetryStep } from '../../core/runner/networkRetry.js';
+import { NOOP_RECORDER } from '../../core/telemetry/index.js';
+import { decodeText, fetchBounded, userAgentOf } from '../../core/transport/index.js';
+import { CJ_PACKET_MAX_BYTES, normalizeCjPacketNumber, parseCjPacket, PROVIDER } from './parser.js';
+/** The lookup the tracking page on www.cjpacket.com makes for the numbers in its address. */
+export const CJ_PACKET_API = 'https://www.cjpacket.com/cj-logistics-api/refactoring/cjpacket/track';
+const REDIRECTS = [301, 302, 303, 307, 308];
+// Bot checks Cloudflare, in front of the site, could put in place of the reply.
+const CHALLENGE = /_cf_chl_opt|cf-turnstile|challenge-platform|<title>\s*(?:Just a moment|Attention Required)/i;
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'CJ Packet answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'CJ Packet returned a reply that is not JSON', { cause });
+    }
+}
+export class CjPacketTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeCjPacketNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(CJ_PACKET_API, { method: 'POST', signal, headers: {
+                    Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': userAgentOf(this.options.userAgent),
+                }, body: JSON.stringify([number]) }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)),
+                maxBytes: CJ_PACKET_MAX_BYTES, redirect: 'manual', fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'CJ Packet redirected its tracking lookup');
+            // The service answers an unknown number with HTTP 200; a 404 is a moved route.
+            if (response.status === 404 || response.status === 410)
+                throw new TransportError(PROVIDER, 'CJ Packet tracking lookup is unavailable');
+            return parseCjPacket(json(decodeText(bytes)), number);
+        };
+        // A request that fails to reach the site, or hangs, gets one more try: the
+        // first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'cj-packet', budgetMs: context.budgetMs ?? 15_000, signal: context.signal,
+            recorder: this.options.recorder ?? NOOP_RECORDER }, [
+            { id: 'direct', run: ({ signal, remainingMs }) => read(signal, firstAttemptMs(remainingMs)) },
+            networkRetryStep(({ signal, remainingMs }) => read(signal, remainingMs)),
+        ]);
+    }
+}
+export const adapter = (environment) => {
+    const tracker = new CjPacketTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'cj-packet', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeCjPacketNumber(number))),
+    };
+};

package/dist/carriers/cj-packet/carrier.json

@@ -18,18 +18,71 @@
   "timezone": "Asia/Shanghai",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "cj-packet",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 956
+    },
+    "localClocks": true
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "offset_timestamps",
+    "service_name",
+    "destination_country",
+    "delivery_partner",
+    "delivery_tracking_number",
+    "delivered_at"
+  ],
   "portal": {
     "url": "https://www.cjpacket.com/?trackingNumber={trackingNumber}",
     "searchUrl": "https://www.cjpacket.com/",
     "canaryUrl": "https://www.cjpacket.com/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "history",
+      "location",
+      "service_name",
+      "origin_country",
+      "destination_country",
+      "tracking_alias",
+      "delivery_partner",
+      "delivery_tracking_number",
+      "delivered_at",
+      "order_reference",
+      "merchant_reference",
+      "contact_details"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "offset_timestamps",
+      "service_name",
+      "destination_country",
+      "delivery_partner",
+      "delivery_tracking_number",
+      "delivered_at"
+    ],
+    "discarded": [
+      "origin_country",
+      "tracking_alias",
+      "order_reference",
+      "merchant_reference",
+      "contact_details"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "sender_name",
+      "recipient_name",
+      "recipient_address",
+      "proof_of_delivery"
+    ]
   },
   "links": [
     {

package/dist/carriers/cj-packet/numbers.json

@@ -221,13 +221,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "cj-packet",
         "confidence": "high"
       },
-      "note": "Looked up on CJ Packet's own tracker, as an archived address shows; the capture was not opened, and the page loads its history by script."
+      "note": "Looked up on CJ Packet's own tracker, as an archived address shows; CJ Packet's tracker knows it."
     },
     {
       "number": "CJPBDC1240600053YQ",
@@ -240,13 +240,13 @@
         "access": "indexed_excerpt"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "cj-packet",
         "confidence": "high"
       },
-      "note": "Looked up on CJ Packet's own tracker, as an archived address shows; the capture was not opened, and the page loads its history by script."
+      "note": "Looked up on CJ Packet's own tracker, as an archived address shows; CJ Packet's tracker knows it."
     },
     {
       "number": "CJPMG0390200118YQ",

package/dist/carriers/cj-packet/parser.d.ts

@@ -0,0 +1,18 @@
+import type { CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "CJ Packet";
+export declare const CJ_PACKET_MAX_BYTES: number;
+/** A CJ Packet number, in capitals as the tracker needs it; anything else is not one CJ Packet issues. */
+export declare function normalizeCjPacketNumber(raw: string): string;
+/**
+ * A scan's wording without the support contact a courier appends to it, and
+ * without phone numbers or e-mail addresses.
+ */
+export declare function cjPacketWording(activity: string): string;
+/**
+ * The reply of the tracking page's `POST /cj-logistics-api/refactoring/cjpacket/track`
+ * for one number. An unknown number is an empty list. The tracker also finds a
+ * shipment by its forwarder's or its courier's number, so a shipment counts
+ * only when its own CJ Packet number is the one asked. The merchant, the
+ * order's references and the courier's phone are never read.
+ */
+export declare function parseCjPacket(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/cj-packet/parser.js

@@ -0,0 +1,210 @@
+import { DateTime, FixedOffsetZone } from 'luxon';
+import { carrierIdFromPartner } from '../../core/catalog/hints.js';
+import { detectCarrierMatch, normalizeTrackingNumber } from '../../core/detection/index.js';
+import { USPS_ROUTING_BARCODE, uspsPackageIdentifier } from '../../core/detection/usps.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 { cjPacketCurrentStage, cjPacketStage, cjPacketSummary } from './status.js';
+export const PROVIDER = 'CJ Packet';
+// A long history is under ten kilobytes.
+export const CJ_PACKET_MAX_BYTES = 512 * 1024;
+// `cj-packet-1`'s layout: CJP, two or three letters, ten digits and YQ.
+const NUMBER = /^CJP[A-Z]{2,3}\d{10}YQ$/;
+const WALL_CLOCK = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+const STAMP = /^\d{1,15}$/;
+// The place a relayed line can open with, such as "[US,SAMPLE CITY,ST]".
+const PLACE = /^\[([^\]]{1,120})\]\s*/;
+// A clause that sends the reader to someone's support, with whatever follows it.
+const CONTACT = /\s*[,，;；]\s*(?=[^,，;；]*\b(?:contact|support|customer service|hotline)\b)[\s\S]*$/i;
+const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g;
+// A run of nine or more digits, with spaces, brackets, dots or hyphens
+// between them, as phone numbers are written; a date stays.
+const PHONE = /(?<![A-Z\d])(?!\d{4}-\d{2}-\d{2}(?!\d))\+?\d(?:[\s().-]{0,2}\d){8,}(?![A-Z\d])/gi;
+// Who took a delivered parcel, after the delivery's own words.
+const RECEIVER = /\s*[,;:.\-–]\s*(?:signed(?: for)? by|signatory|received by|recibido por|entregado a)\b[\s\S]*$/i;
+const MAX_SHIPMENTS = 50;
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/** A CJ Packet number, in capitals as the tracker needs it; anything else is not one CJ Packet issues. */
+export function normalizeCjPacketNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw).toUpperCase() : '';
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'CJ Packet numbers are CJP, two or three letters, ten digits and YQ');
+    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, `CJ Packet returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+/**
+ * A scan's wording without the support contact a courier appends to it, and
+ * without phone numbers or e-mail addresses.
+ */
+export function cjPacketWording(activity) {
+    return clean(activity.replace(CONTACT, '').replace(EMAIL, '').replace(PHONE, '').replace(/\s+([,，;；.。])/g, '$1'))
+        .replace(/^[\s,，;；:]+|[\s,，;；:\-–]+$/g, '');
+}
+/**
+ * A scan's clock. `eventTime` is the scanning site's wall clock and
+ * `eventTimestamp`, when the forwarder sends one, the same moment in epoch
+ * milliseconds, which the page shows instead. Their difference is the site's
+ * offset, so such a scan is returned at it. A scan without one, or whose two
+ * clocks do not differ by an offset a clock can have, keeps its wall clock.
+ */
+function scanClock(row) {
+    const wall = text(row, 'eventTime', 32);
+    const local = wall.replace(' ', 'T');
+    // Parsing in UTC checks the calendar digits only.
+    const parsed = DateTime.fromISO(local, { zone: 'UTC' });
+    // Luxon rolls 24:00:00 over to the next day; only a clock that reads back unchanged is kept.
+    if (!WALL_CLOCK.test(wall) || !parsed.isValid || parsed.toFormat("yyyy-MM-dd'T'HH:mm:ss") !== local) {
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid scan time');
+    }
+    const raw = row.eventTimestamp;
+    if (raw === null || raw === undefined || raw === '')
+        return { local_time: local };
+    const stamp = typeof raw === 'number' ? raw : typeof raw === 'string' && STAMP.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(stamp) || stamp <= 0)
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid scan timestamp');
+    const minutes = (parsed.toMillis() - stamp) / 60_000;
+    if (!Number.isInteger(minutes) || minutes % 15 !== 0 || minutes < -12 * 60 || minutes > 14 * 60)
+        return { local_time: local };
+    const time = DateTime.fromMillis(stamp, { zone: FixedOffsetZone.instance(minutes) }).toISO({ suppressMilliseconds: true });
+    return time ? { time } : { local_time: local };
+}
+function projectRow(row) {
+    // The page writes the line out as HTML.
+    const activity = textFromHtml(text(row, 'activity', 1000), 1000);
+    const place = PLACE.exec(activity);
+    let description = cjPacketWording(place ? activity.slice(place[0].length) : activity);
+    const staged = cjPacketStage(description);
+    if (staged?.stage === 'delivered')
+        description = description.replace(RECEIVER, '');
+    const clock = scanClock(row);
+    // A line left empty says nothing to keep.
+    if (!description)
+        return null;
+    const location = text(row, 'location', 200) || clean(place?.[1], 120);
+    const event = {
+        ...clock,
+        description,
+        ...(location ? { location } : {}),
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+    return { key: JSON.stringify([clock, description, location]), event };
+}
+/**
+ * The destination courier's number from the reply's last-mile field, and
+ * that courier when the reply names one the catalog knows whose rules fit
+ * the number. A USPS routing barcode gives its package identifier.
+ */
+function handoff(shipment, number) {
+    const compact = normalizeTrackingNumber(text(shipment, 'lastTrackNumber', 64)).toUpperCase();
+    const reference = USPS_ROUTING_BARCODE.test(compact) ? uspsPackageIdentifier(compact) ?? '' : compact;
+    if (!/^[A-Z0-9]{4,40}$/.test(reference) || reference === number)
+        return {};
+    const partner = carrierIdFromPartner(text(shipment, 'providerEnName', 80), text(shipment, 'providerUrl', 500));
+    const named = partner && partner !== 'cj-packet' && detectCarrierMatch(reference).candidates.includes(partner);
+    return { ...(named ? { delivery_carrier: partner } : {}), delivery_tracking_number: reference };
+}
+/** The shipment's summary code: a whole number, or nothing. */
+function summaryCode(shipment) {
+    const code = shipment.status;
+    if (code === null || code === undefined)
+        return undefined;
+    if (typeof code !== 'number' || !Number.isSafeInteger(code))
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid status');
+    return code;
+}
+/**
+ * The reply of the tracking page's `POST /cj-logistics-api/refactoring/cjpacket/track`
+ * for one number. An unknown number is an empty list. The tracker also finds a
+ * shipment by its forwarder's or its courier's number, so a shipment counts
+ * only when its own CJ Packet number is the one asked. The merchant, the
+ * order's references and the courier's phone are never read.
+ */
+export function parseCjPacket(payload, raw) {
+    const number = normalizeCjPacketNumber(raw);
+    if (!isRecord(payload) || typeof payload.success !== 'boolean')
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid envelope');
+    if (!payload.success)
+        throw new IndeterminateError(PROVIDER, 'CJ Packet did not complete the lookup');
+    const shipments = payload.data;
+    if (!Array.isArray(shipments) || shipments.length > MAX_SHIPMENTS)
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid shipment list');
+    // The page shows "No tracking info found." for an empty list.
+    if (!shipments.length)
+        throw new NotFoundError(PROVIDER);
+    const own = shipments.filter((shipment) => {
+        if (!isRecord(shipment) || typeof shipment.cjTrackNumber !== 'string') {
+            throw new SchemaError(PROVIDER, 'CJ Packet returned a shipment without its number');
+        }
+        return normalizeTrackingNumber(clean(shipment.cjTrackNumber, 64)).toUpperCase() === number;
+    });
+    if (!own.length)
+        throw new IndeterminateError(PROVIDER, 'CJ Packet answered for another shipment');
+    if (own.length > 1)
+        throw new IndeterminateError(PROVIDER, 'CJ Packet answered with several shipments for the number');
+    const shipment = own[0];
+    const rows = shipment.trackEvent ?? [];
+    if (!Array.isArray(rows))
+        throw new SchemaError(PROVIDER, 'CJ Packet returned a shipment with invalid scans');
+    if (rows.length > MAX_ROWS)
+        throw new SchemaError(PROVIDER, 'CJ Packet returned an oversized history');
+    const seen = new Set();
+    const events = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            throw new SchemaError(PROVIDER, 'CJ Packet returned an invalid scan');
+        const scan = projectRow(row);
+        if (!scan || seen.has(scan.key))
+            continue;
+        seen.add(scan.key);
+        events.push(scan.event);
+    }
+    const code = summaryCode(shipment);
+    const summary = code === undefined ? undefined : cjPacketSummary(code);
+    const service = text(shipment, 'logisticsName', 80);
+    const country = text(shipment, 'destCountryCode', 8).toUpperCase();
+    const facts = {
+        ...(service ? { service_name: service } : {}),
+        ...(/^[A-Z]{2}$/.test(country) ? { destination_country: country } : {}),
+        ...handoff(shipment, number),
+    };
+    if (!events.length) {
+        // A shipment without scans keeps the status the tracker gives it.
+        if (!summary)
+            throw new NoHistoryError(PROVIDER);
+        return { status: languageStageStatus(summary.stage), current_stage: summary.stage, current_stage_source: 'carrier_map',
+            last_status_text: text(shipment, 'statusDescription', 80) || summary.wording, provider_code: String(code),
+            last_update: null, expected_delivery: null, ...facts, summary_only: true, events: [] };
+    }
+    // Newest first, as the page lists them by wall clock: scans at different
+    // offsets are not all instants, so the reply's order stands.
+    const newest = events[0];
+    const scanned = events.find((event) => event.stage);
+    const stage = cjPacketCurrentStage(summary, scanned?.stage);
+    const source = stage === scanned?.stage ? scanned?.stage_source : 'carrier_map';
+    // A delivery's moment is its delivered scan's, when that scan has an offset;
+    // the summary alone, or a wall clock, gives none.
+    const deliveredAt = stage === 'delivered' && scanned?.stage === 'delivered' ? scanned.time : undefined;
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: source ?? 'carrier_map' } : {}),
+        last_status_text: newest.description,
+        last_update: newest.time ?? null,
+        ...(newest.local_time ? { last_update_local: newest.local_time } : {}),
+        expected_delivery: null,
+        ...(deliveredAt ? { delivered_at: deliveredAt } : {}),
+        ...facts,
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/cj-packet/status.d.ts

@@ -0,0 +1,18 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import { type CarrierStatusMap } from '../../core/status/statusMap.js';
+/** One of a shipment's summary statuses: the tracker's name for it and its stage. */
+interface CjPacketSummary {
+    readonly wording: string;
+    readonly stage: Stage;
+    /** A summary that spans several legs: the newest scan says which, when it is no earlier. */
+    readonly scansDecide?: boolean;
+}
+export declare function cjPacketSummary(code: number): CjPacketSummary | undefined;
+/** The shipment's stage: its summary, or the newest staged scan within a summary that spans several legs. */
+export declare function cjPacketCurrentStage(summary: CjPacketSummary | undefined, scanned: Stage | undefined): Stage | undefined;
+export declare function cjPacketMappedStage(wording: string): Stage | undefined;
+/** A scan's stage: the map, else the shared wording rules, else nothing. */
+export declare function cjPacketStage(wording: string): ClassifiedWording | null;
+/** Scans carry no code; a summary status is the provider code of a shipment without scans. */
+export declare const statusMap: CarrierStatusMap;
+export {};