universal-parcel-scraper 0.487.0-main.2349 → 0.490.0-main.2360

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 **530 dedicated adapters** and **5 universal fallbacks**
+**3,500+ carriers** through **533 dedicated adapters** and **5 universal fallbacks**
 
 <sub>772 catalog entries · 134 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 15,354 such statuses, each filed under one stage.
+The carrier folders record 15,394 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

@@ -7355,7 +7355,8 @@
     "timezone": "America/Chicago",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "better-trucks",
+      "recognitionRank": 738
     },
     "canaryUrl": "https://tracking.bettertrucks.com/",
     "trackingUrlTemplate": "https://tracking.bettertrucks.com/tracking?trackingNumber={trackingNumber}",
@@ -8915,7 +8916,9 @@
     "timezone": "Asia/Seoul",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "chunil",
+      "recognitionRank": 621,
+      "localClocks": true
     },
     "canaryUrl": "https://www.chunil.co.kr/HTrace/HTrace.jsp",
     "trackingUrlTemplate": "https://www.chunil.co.kr/HTrace/HTrace.jsp?transNo={trackingNumber}",
@@ -16502,7 +16505,8 @@
     "timezone": "Asia/Seoul",
     "tracking": {
       "mode": "automatic",
-      "adapter": "universal"
+      "adapter": "ilyang-logis",
+      "recognitionRank": 703
     },
     "canaryUrl": "https://www.ilyanglogis.co.kr/page/Tracking.do",
     "trackingUrlTemplate": "https://www.ilyanglogis.co.kr/page/TrackingResult.do?trackingType=0&blNum={trackingNumber}",

package/data/coverage-summary.json

@@ -1,6 +1,6 @@
 {
   "catalog": 772,
-  "activeAdapters": 530,
+  "activeAdapters": 533,
   "countries": 134,
   "referenceCarriers": 100,
   "comparison": {

package/data/detection-golden.json

@@ -9406,6 +9406,28 @@
       "j-and-t"
     ]
   },
+  {
+    "input": "10000000001",
+    "carrier": "unknown",
+    "confidence": "low",
+    "candidates": [
+      "postlogistics",
+      "gls-ch",
+      "gls-fr",
+      "gls-de",
+      "dhl-ecommerce-pl",
+      "gls-at",
+      "gls-pl",
+      "ppl"
+    ],
+    "asked": [
+      "gls-fr",
+      "gls-de",
+      "gls-ch",
+      "postlogistics",
+      "dhl-ecommerce-pl"
+    ]
+  },
   {
     "input": "1000000157123",
     "carrier": "unknown",
@@ -13483,28 +13505,6 @@
       "zto"
     ]
   },
-  {
-    "input": "11633265509",
-    "carrier": "unknown",
-    "confidence": "low",
-    "candidates": [
-      "postlogistics",
-      "gls-ch",
-      "gls-fr",
-      "gls-de",
-      "dhl-ecommerce-pl",
-      "gls-at",
-      "gls-pl",
-      "ppl"
-    ],
-    "asked": [
-      "gls-fr",
-      "gls-de",
-      "gls-ch",
-      "postlogistics",
-      "dhl-ecommerce-pl"
-    ]
-  },
   {
     "input": "116439049496",
     "carrier": "unknown",
@@ -64490,6 +64490,9 @@
     "confidence": "low",
     "candidates": [
       "better-trucks"
+    ],
+    "asked": [
+      "better-trucks"
     ]
   },
   {
@@ -64498,6 +64501,12 @@
     "confidence": "none",
     "candidates": []
   },
+  {
+    "input": "BTS_0261SMTF8S",
+    "carrier": "unknown",
+    "confidence": "none",
+    "candidates": []
+  },
   {
     "input": "BTYCN0092384464YQ",
     "carrier": "anserx",

package/dist/browser/scraper.js

@@ -5961,7 +5961,8 @@ var Ue = {
 		timezone: "America/Chicago",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "better-trucks",
+			recognitionRank: 738
 		},
 		canaryUrl: "https://tracking.bettertrucks.com/",
 		trackingUrlTemplate: "https://tracking.bettertrucks.com/tracking?trackingNumber={trackingNumber}",
@@ -7075,7 +7076,9 @@ var Ue = {
 		timezone: "Asia/Seoul",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "chunil",
+			recognitionRank: 621,
+			localClocks: !0
 		},
 		canaryUrl: "https://www.chunil.co.kr/HTrace/HTrace.jsp",
 		trackingUrlTemplate: "https://www.chunil.co.kr/HTrace/HTrace.jsp?transNo={trackingNumber}",
@@ -12668,7 +12671,8 @@ var Ue = {
 		timezone: "Asia/Seoul",
 		tracking: {
 			mode: "automatic",
-			adapter: "universal"
+			adapter: "ilyang-logis",
+			recognitionRank: 703
 		},
 		canaryUrl: "https://www.ilyanglogis.co.kr/page/Tracking.do",
 		trackingUrlTemplate: "https://www.ilyanglogis.co.kr/page/TrackingResult.do?trackingType=0&blNum={trackingNumber}",
@@ -29520,6 +29524,7 @@ var Tl = {
 	"bangladesh-post": 909,
 	"barid-al-maghrib": 901,
 	belpost: 929,
+	"better-trucks": 738,
 	"bex-express": 827,
 	"bjs-home-delivery": 844,
 	"blue-express": 971,
@@ -29550,6 +29555,7 @@ var Tl = {
 	"chit-chats": 115,
 	chronodiali: 781,
 	chronopost: 890,
+	chunil: 621,
 	ciblex: 640,
 	"city-express-rs": 817,
 	citymail: 868,
@@ -29676,6 +29682,7 @@ var Tl = {
 	"hr-parcel": 887,
 	"hrvatska-posta": 160,
 	hywl: 993,
+	"ilyang-logis": 703,
 	imile: 997,
 	"indah-logistik": 798,
 	inpost: 820,

package/dist/carriers/better-trucks/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 lookup the tracking page on tracking.bettertrucks.com makes for one number. */
+export declare const BETTER_TRUCKS_API = "https://tracking.bettertrucks.com/api/tracking/";
+/** The lookup's address for one number, with the flag the page adds. */
+export declare function betterTrucksLookupUrl(number: string): string;
+export declare class BetterTrucksTracker {
+    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/better-trucks/adapter.js

@@ -0,0 +1,62 @@
+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 { BETTER_TRUCKS_MAX_BYTES, normalizeBetterTrucksNumber, parseBetterTrucks, PROVIDER } from './parser.js';
+/** The lookup the tracking page on tracking.bettertrucks.com makes for one number. */
+export const BETTER_TRUCKS_API = 'https://tracking.bettertrucks.com/api/tracking/';
+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|<title>\s*Attention Required|captcha/i;
+/** The lookup's address for one number, with the flag the page adds. */
+export function betterTrucksLookupUrl(number) {
+    return `${BETTER_TRUCKS_API}${encodeURIComponent(normalizeBetterTrucksNumber(number))}?isFromExternalTracking=true`;
+}
+function json(body) {
+    try {
+        return JSON.parse(body);
+    }
+    catch (cause) {
+        if (CHALLENGE.test(body.slice(0, 64_000)))
+            throw new ChallengeError(PROVIDER, 'Better Trucks answered with a browser check', { cause });
+        throw new SchemaError(PROVIDER, 'Better Trucks returned a reply that is not JSON', { cause });
+    }
+}
+export class BetterTrucksTracker {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async fetch(raw, context = {}) {
+        const number = normalizeBetterTrucksNumber(raw);
+        const read = async (signal, timeoutMs) => {
+            const { response, bytes } = await fetchBounded(betterTrucksLookupUrl(number), { method: 'GET', signal, headers: {
+                    Accept: 'application/json', 'User-Agent': userAgentOf(this.options.userAgent),
+                } }, { provider: PROVIDER, timeoutMs: Math.max(1, Math.floor(timeoutMs)), maxBytes: BETTER_TRUCKS_MAX_BYTES, redirect: 'manual',
+                fetcher: this.options.fetcher, allowHttpStatuses: [...REDIRECTS, 404, 410] });
+            if (REDIRECTS.includes(response.status))
+                throw new TransportError(PROVIDER, 'Better Trucks redirected its tracking lookup');
+            // The page 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, 'Better Trucks tracking lookup is unavailable');
+            return parseBetterTrucks(json(decodeText(bytes)), number);
+        };
+        // A request that fails to reach the service, or hangs, gets one more try: the
+        // first gets half of the budget, so the retry fits in the rest.
+        return runSteps({ carrier: 'better-trucks', 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 BetterTrucksTracker({ fetcher: environment.fetcher, recorder: environment.recorder, userAgent: environment.userAgent });
+    return {
+        id: 'better-trucks', recordsSteps: true, steps: ['direct', 'retry'],
+        track: (input, context) => tracker.fetch(input.number, context),
+        recognize: (number, context) => recognizeFromLookup(() => tracker.fetch(number, context), () => accepted(() => normalizeBetterTrucksNumber(number))),
+    };
+};

package/dist/carriers/better-trucks/carrier.json

@@ -16,18 +16,62 @@
   "timezone": "America/Chicago",
   "tracking": {
     "mode": "automatic",
-    "adapter": "universal",
-    "steps": []
+    "adapter": "better-trucks",
+    "steps": [
+      "direct",
+      "retry"
+    ],
+    "recognition": {
+      "rank": 738
+    }
   },
-  "capabilities": [],
+  "capabilities": [
+    "history",
+    "location",
+    "provider_code",
+    "delivered_at",
+    "destination_country",
+    "offset_timestamps"
+  ],
   "portal": {
     "url": "https://tracking.bettertrucks.com/tracking?trackingNumber={trackingNumber}",
     "searchUrl": "https://tracking.bettertrucks.com/",
     "canaryUrl": "https://tracking.bettertrucks.com/",
-    "shows": [],
-    "scraped": [],
-    "discarded": [],
-    "unavailable": []
+    "shows": [
+      "status",
+      "progress_rail",
+      "history",
+      "location",
+      "coordinates",
+      "delivered_at",
+      "proof_of_delivery",
+      "pickup_point",
+      "delivery_options"
+    ],
+    "scraped": [
+      "status",
+      "history",
+      "location",
+      "coordinates",
+      "provider_code",
+      "delivered_at",
+      "destination_country",
+      "offset_timestamps"
+    ],
+    "discarded": [
+      "progress_rail",
+      "proof_of_delivery",
+      "pickup_point",
+      "delivery_options"
+    ],
+    "unavailable": [
+      "eta",
+      "weight",
+      "service_name",
+      "sender_name",
+      "recipient_name",
+      "delivery_partner"
+    ]
   },
   "links": [
     {

package/dist/carriers/better-trucks/numbers.json

@@ -12,7 +12,7 @@
         "access": "full_page"
       },
       "context": {
-        "assessment": "candidate"
+        "assessment": "confirmed"
       },
       "expect": {
         "carrier": "unknown",
@@ -23,6 +23,25 @@
       },
       "note": "A PissedConsumer review of Better Trucks gives it for a parcel the tracker called delivered but that never arrived."
     },
+    {
+      "number": "BTS_0261SMTF8S",
+      "role": "shipment",
+      "evidence": "public_shipment_report",
+      "source": {
+        "url": "https://better-trucks.pissedconsumer.com/5/RT-P.html",
+        "date": "2025-04-10",
+        "dateKind": "publication",
+        "access": "full_page"
+      },
+      "context": {
+        "assessment": "candidate"
+      },
+      "expect": {
+        "carrier": "unknown",
+        "confidence": "none"
+      },
+      "note": "A PissedConsumer review of Better Trucks gives it as the tracking number of a TikTok Shop order Better Trucks marked delivered; the tracker no longer knows it."
+    },
     {
       "number": "BTS_0018P2LD557",
       "role": "shipment",

package/dist/carriers/better-trucks/parser.d.ts

@@ -0,0 +1,12 @@
+import { type CarrierResult } from '../../core/result/index.js';
+export declare const PROVIDER = "Better Trucks";
+export declare const BETTER_TRUCKS_MAX_BYTES: number;
+/** A number for Better Trucks' tracker, in upper case; anything else, package codes included, is not one it is asked. */
+export declare function normalizeBetterTrucksNumber(raw: string): string;
+/**
+ * The reply of the tracker's `/api/tracking/{number}`. A number it does not
+ * know is HTTP 200 with the status `UNKNOWN` ("Invalid tracking no") and an
+ * empty history, which the page shows as "Shipment can't be found". The reply
+ * must name the number asked.
+ */
+export declare function parseBetterTrucks(payload: unknown, raw: string): CarrierResult;

package/dist/carriers/better-trucks/parser.js

@@ -0,0 +1,211 @@
+import { DateTime, FixedOffsetZone } from 'luxon';
+import { normalizeTrackingNumber } from '../../core/detection/index.js';
+import { IndeterminateError, InvalidInputError, NoHistoryError, NotFoundError, SchemaError } from '../../core/errors/index.js';
+import { eventPoint } from '../../core/result/index.js';
+import { languageStageStatus } from '../../core/status/index.js';
+import { calendarDay } from '../../core/time/index.js';
+import { clean } from '../../core/transport/index.js';
+import { isRecord } from '../../core/types.js';
+import { betterTrucksStage, isHubScan } from './status.js';
+export const PROVIDER = 'Better Trucks';
+// A history of a dozen scans is about ten kilobytes; its delivery photo links are most of it.
+export const BETTER_TRUCKS_MAX_BYTES = 512 * 1024;
+// Letters, digits and underscores with at least one digit, as BTPA… and BTS_… numbers are written.
+const NUMBER = /^(?=[A-Z_]*\d)[A-Z0-9_]{10,40}$/;
+// The tracker's package codes: five characters from a 32-symbol alphabet, or
+// BTS and a code without the underscore. The page swaps them for the tracking
+// number they stand for, which lets a made-up code open a stranger's parcel.
+const PACKAGE_CODE = /^(?:[2-9A-HJ-NP-Z]{5}|BTS[^_].*)$/;
+// A scan's clock as the reply writes it: to the second, without an offset; one with an offset is read in it.
+const CLOCK = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,7})?(?:Z|[+-]\d{2}:\d{2})?$/;
+// The zone the reply gives a scan's local reading, as GMT-05:00.
+const GMT_OFFSET = /^GMT([+-])(\d{2}):(\d{2})$/;
+// Rows the page leaves out of its history: a duplicate of the label's
+// creation and a failure inside the dispatch system.
+const HIDDEN = new Set(['TRANSACTION_CREATED', 'ONFLEET_FAILED']);
+const MAX_ROWS = 500;
+const MAX_EVENTS = 100;
+/** A number for Better Trucks' tracker, in upper case; anything else, package codes included, is not one it is asked. */
+export function normalizeBetterTrucksNumber(raw) {
+    const number = raw.length <= 64 ? normalizeTrackingNumber(raw) : '';
+    if (PACKAGE_CODE.test(number))
+        throw new InvalidInputError(PROVIDER, 'Better Trucks package codes are not tracking numbers');
+    if (!NUMBER.test(number))
+        throw new InvalidInputError(PROVIDER, 'Better Trucks numbers are ten or more letters, digits and underscores');
+    return number;
+}
+function invalid(message) {
+    throw new SchemaError(PROVIDER, message);
+}
+/** An optional text field; anything but a string is a changed reply. */
+function text(row, key, maxLength = 200) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value !== 'string')
+        invalid(`Better Trucks returned an invalid ${key}`);
+    return clean(value, maxLength);
+}
+/** An optional record: absent is empty, anything but an object is a changed reply. */
+function record(row, key) {
+    const value = row[key];
+    if (value === null || value === undefined)
+        return {};
+    if (!isRecord(value))
+        invalid(`Better Trucks returned an invalid ${key}`);
+    return value;
+}
+/** A clock as an instant in UTC, its digits read as UTC without an offset; null when it is not a clock. Date libraries accept hour 24, so the fields are checked here. */
+function utcClock(value) {
+    const match = CLOCK.exec(value);
+    if (!match)
+        return null;
+    const [, year, month, date, hour, minute, second] = match;
+    if (!calendarDay(Number(year), Number(month), Number(date)) || Number(hour) > 23 || Number(minute) > 59 || Number(second) > 59)
+        return null;
+    const parsed = DateTime.fromISO(value, { zone: 'UTC' });
+    return parsed.isValid ? parsed.startOf('second') : null;
+}
+/**
+ * The offset of the scan's local reading in `relative_time`, in minutes, when
+ * that reading is the same instant as `object_created`; else null.
+ */
+function localOffset(row, utc) {
+    const readings = row.relative_time;
+    if (readings === null || readings === undefined)
+        return null;
+    if (!Array.isArray(readings))
+        invalid('Better Trucks returned an invalid relative_time');
+    const local = readings.find((reading) => isRecord(reading) && reading.name === 'LOCAL_TIME');
+    if (!isRecord(local) || typeof local.time !== 'string' || typeof local.timezone !== 'string')
+        return null;
+    const zone = GMT_OFFSET.exec(local.timezone.trim());
+    const wall = utcClock(local.time.trim());
+    if (!zone || !wall || Number(zone[2]) > 14 || Number(zone[3]) > 59)
+        return null;
+    const offset = (zone[1] === '-' ? -1 : 1) * (Number(zone[2]) * 60 + Number(zone[3]));
+    return wall.toMillis() - offset * 60_000 === utc.toMillis() ? offset : null;
+}
+/**
+ * A scan's instant. `object_created` is UTC without its offset: the page reads
+ * it as UTC, and `relative_time` labels the same digits Greenwich Mean Time.
+ * The instant is written in the offset of the scan's local reading when that
+ * reading agrees with it. The reply gives GMT+00:00 there when it has no
+ * position for the scan, which names no US clock, so that scan stays in UTC.
+ */
+function scanTime(row) {
+    const utc = utcClock(text(row, 'object_created', 40));
+    if (!utc)
+        invalid('Better Trucks returned an invalid scan time');
+    const offset = localOffset(row, utc);
+    const shown = offset ? utc.setZone(FixedOffsetZone.instance(offset)) : utc;
+    return shown.toISO({ suppressMilliseconds: true });
+}
+/** A scan's place: its town and state, and its country outside the US. */
+function placeOf(row) {
+    const place = record(row, 'location');
+    const town = text(place, 'city', 80);
+    const state = text(place, 'state', 40);
+    const country = text(place, 'country', 40);
+    const parts = [town, state, country && country.toUpperCase() !== 'US' ? country : ''].filter(Boolean);
+    return parts.join(', ');
+}
+/** The wording the page shows for a scan: the reply's own, or the page's label for a code it is given as. */
+function wordingOf(code, details) {
+    if (details.toUpperCase() === 'RTS_RETURNED_TO_STATION')
+        return 'Return To Station';
+    return details || code.toLowerCase().split('_').join(' ').replace(/^\w/, (letter) => letter.toUpperCase());
+}
+/**
+ * One history row: its `status` code, `status_details`, clock and place. Its
+ * `event_details` (who took the parcel, where it was left, why a delivery
+ * failed), `images` (delivery photos) and `location_info` are not read. Only a
+ * hub scan keeps its coordinates: the others can be the shipper's or the
+ * recipient's door.
+ */
+function projectRow(row) {
+    const code = text(row, 'status', 80).toUpperCase();
+    if (!code)
+        invalid('Better Trucks returned a scan without its status');
+    if (HIDDEN.has(code))
+        return null;
+    const description = wordingOf(code, text(row, 'status_details', 200));
+    const time = scanTime(row);
+    const location = placeOf(row);
+    const point = location && isHubScan(code) ? eventPoint(row.latitude, row.longitude) : null;
+    const staged = betterTrucksStage(code, description);
+    return {
+        time, ...(location ? { location } : {}), ...(point ? { point } : {}), description, provider_code: code,
+        ...(staged ? { stage: staged.stage, stage_source: staged.source } : {}),
+    };
+}
+/**
+ * The scan that sets the status: the newest with a stage. A corrected address
+ * ends the wait for its confirmation, so the wait before it no longer counts,
+ * as the page shows the scan before both instead.
+ */
+function statusScan(events) {
+    let corrected = false;
+    for (const event of events) {
+        if (event.provider_code === 'ADDRESS_CORRECTED')
+            corrected = true;
+        else if (event.stage && !(corrected && event.provider_code === 'AWAITING_ADDRESS_CONFIRMATION'))
+            return event;
+    }
+    return undefined;
+}
+/**
+ * The reply of the tracker's `/api/tracking/{number}`. A number it does not
+ * know is HTTP 200 with the status `UNKNOWN` ("Invalid tracking no") and an
+ * empty history, which the page shows as "Shipment can't be found". The reply
+ * must name the number asked.
+ */
+export function parseBetterTrucks(payload, raw) {
+    const number = normalizeBetterTrucksNumber(raw);
+    if (!isRecord(payload) || typeof payload.tracking_number !== 'string' || !Array.isArray(payload.tracking_history)) {
+        invalid('Better Trucks returned an invalid tracking reply');
+    }
+    if (normalizeTrackingNumber(clean(payload.tracking_number, 64)) !== number) {
+        throw new IndeterminateError(PROVIDER, 'Better Trucks answered for another parcel');
+    }
+    const rows = payload.tracking_history;
+    if (rows.length > MAX_ROWS)
+        invalid('Better Trucks returned an oversized history');
+    if (!rows.length) {
+        if (text(record(payload, 'tracking_status'), 'status', 40).toUpperCase() === 'UNKNOWN')
+            throw new NotFoundError(PROVIDER);
+        throw new NoHistoryError(PROVIDER);
+    }
+    const seen = new Set();
+    const events = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            invalid('Better Trucks returned an invalid scan');
+        const event = projectRow(row);
+        if (!event)
+            continue;
+        const key = JSON.stringify([event.time, event.provider_code, event.description, event.location]);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        events.push(event);
+    }
+    if (!events.length)
+        throw new NoHistoryError(PROVIDER);
+    // Every scan is an instant; newest first by the clock, the order stays stable.
+    events.sort((a, b) => Date.parse(b.time) - Date.parse(a.time));
+    const newest = events[0];
+    const scan = statusScan(events);
+    const stage = scan?.stage;
+    const country = text(record(payload, 'address_to'), 'country', 8).toUpperCase();
+    return {
+        status: stage ? languageStageStatus(stage) : 'unknown',
+        ...(stage ? { current_stage: stage, current_stage_source: scan.stage_source } : {}),
+        last_status_text: newest.description,
+        last_update: newest.time,
+        ...(stage === 'delivered' ? { delivered_at: scan.time } : {}),
+        ...(/^[A-Z]{2}$/.test(country) ? { destination_country: country } : {}),
+        events: events.slice(0, MAX_EVENTS),
+        ...(events.length > MAX_EVENTS ? { history_truncated: true } : {}),
+    };
+}

package/dist/carriers/better-trucks/status.d.ts

@@ -0,0 +1,9 @@
+import { type ClassifiedWording, type Stage } from '../../core/status/index.js';
+import type { CarrierStatusMap } from '../../core/status/statusMap.js';
+/** Whether the code is a hub scan, whose point is the hub. */
+export declare function isHubScan(code: string): boolean;
+/** The stage Better Trucks' codes give a scan code. */
+export declare function betterTrucksMappedStage(code: string): Stage | undefined;
+/** A scan's stage: its code, else the shared wording rules, else nothing. */
+export declare function betterTrucksStage(code: string, wording: string): ClassifiedWording | null;
+export declare const statusMap: CarrierStatusMap;